> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uso de vales de reposición de servidor - Multiplayer SDK

> Aprenda a crear y usar vales de reposición de servidor de PlayFab con el Multiplayer SDK para rellenar las plazas vacantes en una sesión de juego de emparejamiento en curso.

Los juegos hospedados en un servidor a veces necesitan buscar jugadores adicionales. Lo más habitual es que esto ocurra cuando uno o varios jugadores se desconectan mientras la partida está en curso. Los vales de reposición de servidor permiten a un servidor de juego buscar jugadores adicionales que encajen en la partida que se está jugando actualmente.

Los vales de reposición de servidor difieren de los vales de emparejamiento normales de varias maneras:

1. Coincidencia
   * Los vales de reposición no pueden coincidir entre sí.
   * Los vales de reposición tienen prioridad durante la búsqueda, lo que reduce la fragmentación de la base de jugadores.
2. Contrato
   * Los vales de reposición se pueden crear con un campo `ServerDetails`. Esto permite al servidor indicar cómo deben conectarse a él los jugadores emparejados.
   * Los vales de reposición se pueden crear con asignaciones de equipo. Esto permite que los juegos con equipos mantengan su información de equipo.
3. Propiedades de la cola
   * Los vales de reposición no desencadenan la [asignación de Multiplayer Server](/services/playfab/multiplayer/matchmaking/multiplayer-servers).
   * Los vales de reposición no se reflejan en las [estadísticas de cola](/services/playfab/multiplayer/matchmaking/display-statistics), ya que sus jugadores ya están jugando una partida y sesgarían de forma imprecisa el tiempo de espera.
4. Propiedad
   * Los vales de reposición pertenecen a un servidor de juego, no a un usuario. Los usuarios no pueden ver los vales de reposición ni interactuar con ellos de ninguna manera.

## Requisitos previos

* Familiaridad básica con el Multiplayer SDK de PlayFab. Para obtener más información, consulte el [Inicio rápido del SDK de emparejamiento](/services/playfab/multiplayer/matchmaking/quickstart-client-sdk).
* Defina `PFMULTIPLAYER_INCLUDE_SERVER_APIS` antes de incluir el encabezado de emparejamiento. Por ejemplo:

```cpp theme={null}
#define PFMULTIPLAYER_INCLUDE_SERVER_APIS
#include <PFMatchmaking.h>
```

## Configurar un vale de reposición de servidor

Cree y rellene una estructura [PFMatchmakingServerBackfillTicketConfiguration](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingserverbackfillticketconfiguration) con los detalles necesarios:

* **`timeoutInSeconds`**: Cuánto tiempo se intentará rellenar el vale, en segundos.

* **`queueName`**: El nombre de una cola de partidas.

* **`memberCount`**: El número de miembros que hay actualmente en la partida.

* **`members`**: Los miembros [PFMatchmakingMatchMember](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingmatchmember) que hay actualmente en la partida.

* **`serverDetails`** (opcional): Rellene [PFMultiplayerServerDetails](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmultiplayerserverdetails) con información sobre su servidor (FQDN, dirección IP, puertos, región) que se proporciona a los clientes.

<Note>
  El campo `PFMultiplayerServerDetails::ipv4Address` no se valida y puede usarse para proporcionar información arbitraria de cadena de conexión a los clientes.
</Note>

```cpp theme={null}
// Define the server port configuration.
PFMultiplayerPort serverPorts[] = {
    { "portname", 12345, PFMultiplayerProtocolType::Udp }
};

// Populate the server details.
PFMultiplayerServerDetails serverDetails = {};
serverDetails.fqdn = "your.server.fqdn.com";
serverDetails.ipv4Address = "123.234.123.234";
serverDetails.ports = serverPorts;
serverDetails.portCount = sizeof(serverPorts) / sizeof(serverPorts[0]);
serverDetails.region = "EastUS";

// Set up the backfill ticket configuration.
PFMatchmakingServerBackfillTicketConfiguration backfillConfig = {};
backfillConfig.timeoutInSeconds = 60;                 // Try for 60 seconds
backfillConfig.queueName = "YourQueueName";
backfillConfig.memberCount = currentMatchMemberCount; // e.g., 4
backfillConfig.members = currentMatchMembers;         // Pointer to an array of PFMatchmakingMatchMember
backfillConfig.serverDetails = &serverDetails;        // Optional; can be nullptr if not needed
```

## Creación de un vale de reposición de servidor

Al usar [PFMultiplayerCreateServerBackfillTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreateserverbackfillticket) para crear un vale de reposición de servidor, es necesario pasar la entidad de nuestro servidor de juego (como una [PFEntityKey](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/pfentitykey_clientsdk)) junto con la configuración de reposición que creamos en el paso anterior.

```cpp theme={null}
PFMatchmakingTicketHandle backfillTicket = nullptr;
HRESULT hr = PFMultiplayerCreateServerBackfillTicket(
    multiplayerHandle,            // The handle of the PFMultiplayer API instance.
    &serverEntity,                // PFEntityKey for your game server entity
    &backfillConfig,              // The backfill ticket configuration.
    nullptr,                      // Optional async context
    &backfillTicket               // The resulting ticket object.
);

if (FAILED(hr))
{
    // handle ticket creation failure
}
```

## Comprobar el estado del vale de emparejamiento

Debe comprobar si hay actualizaciones del vale llamando a [PFMultiplayerStartProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges) para recibir los cambios de estado y llamando después a [PFMultiplayerFinishProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges) cuando termine de procesar esos cambios de estado.

El SDK devuelve un cambio de estado **TicketStatusChanged** cada vez que cambia el estado del vale y un cambio de estado **TicketCompleted** cuando el emparejamiento se ha completado.

```cpp theme={null}
HRESULT hrTicketError = S_OK;

uint32_t stateChangeCount;
const PFMatchmakingStateChange * const * stateChanges;
HRESULT hr = PFMultiplayerStartProcessingMatchmakingStateChanges(g_pfmHandle, &stateChangeCount, &stateChanges);
if (FAILED(hr))  
{  
    return;  
}  

for (uint32_t i = 0; i < stateChangeCount; ++i)
{
    const PFMatchmakingStateChange& stateChange = *stateChanges[i];

    switch (stateChange.stateChangeType)
    {
        case PFMatchmakingStateChangeType::TicketStatusChanged:
        {
            const auto& ticketStatusChanged = static_cast<const PFMatchmakingTicketStatusChangedStateChange&>(stateChange);

            PFMatchmakingTicketStatus status;
            if (SUCCEEDED(PFMatchmakingTicketGetStatus(ticketStatusChanged.ticket, &status)))
            {
                printf("Ticket status is now: %i.\n", status);
            }

            break;
        }
        case PFMatchmakingStateChangeType::TicketCompleted:
        {
            const auto& ticketCompleted = static_cast<const PFMatchmakingTicketCompletedStateChange&>(stateChange);

            printf("PFMatchmaking completed with Result 0x%08x.\n", ticketCompleted.result);

            if (FAILED(ticketCompleted.result))
            {
                // On failure, we must record the HRESULT so we can return the state change(s) and then bail
                // out of this function.
                hrTicketError = ticketCompleted.result;
            }

            break;
        }
    }
}

hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(g_pfmHandle, stateChangeCount, stateChanges);
if (FAILED(hr))  
{  
    return;  
}  

// Now that we've returned the state change(s), bail out if we detected ticket failure.
if (FAILED(hrTicketError))  
{  
    return;  
}  
```

## Obtener la partida

Después de recibir el cambio de estado **PFMatchmakingStateChangeType::TicketCompleted**, llame a [PFMatchmakingTicketGetMatch](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch) para obtener los detalles de la partida. Estos detalles contienen el identificador de la partida, los usuarios que se han emparejado juntos, la región preferida para la partida y una cadena de organización para el lobby asociado a la partida.

Una vez que recupere toda la información que necesite de la estructura **PFMatchmakingMatchDetails**, el vale debe destruirse con [PFMultiplayerDestroyMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket).

```cpp theme={null}
const PFMatchmakingMatchDetails* match;
HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match);
if (FAILED(hr))  
{  
    return;  
}  

std::string matchId = match->matchId;
std::string lobbyArrangementString = match->lobbyArrangementString;

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);
```

## Cancelación de un vale

Si desea cancelar el proceso de emparejamiento antes del tiempo de espera establecido en `PFMatchmakingServerBackfillTicketConfiguration`, llame a [PFMatchmakingTicketCancel](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketcancel) con el identificador del vale.

Llamar a esta API no garantiza que el vale se cancele. El vale podría completarse antes de que la cancelación pueda procesarse, o la solicitud de cancelación puede producir un error debido a errores de red o del servicio. Puede seguir procesando los cambios de estado de emparejamiento para obtener el resultado del vale si desea confirmar que la cancelación del vale se ha completado antes de continuar. De lo contrario, puede llamar inmediatamente a [PFMultiplayerDestroyMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket).

```cpp theme={null}
HRESULT hr = PFMatchmakingTicketCancel(ticket);

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);
```


## Related topics

- [Uso de vales de reposición de servidor - API REST](/es/services/playfab/multiplayer/matchmaking/backfill-tickets.md)
- [Uso de PlayFab Multiplayer Servers para hospedar juegos multijugador](/es/services/playfab/multiplayer/servers/using-playfab-servers-to-host-games.md)
- [Notas de la versión del SDK de C++ de PlayFab Multiplayer](/es/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-and-matchmaking-release-notes.md)
- [Ejemplo de Wrapper](/es/services/playfab/multiplayer/servers/wrapper-sample.md)
- [SDK de servidor de juego de PlayFab Multiplayer](/es/services/playfab/multiplayer/servers/server-sdks/overview.md)