PFMultiplayerCreateServerBackfillTicket

Creates a server backfill ticket.

Syntax

HRESULT PFMultiplayerCreateServerBackfillTicket(  
    PFMultiplayerHandle handle,  
    const PFEntityKey* server,  
    const PFMatchmakingServerBackfillTicketConfiguration* configuration,  
    void* asyncContext,  
    PFMatchmakingTicketHandle* ticket  
)  

Parameters

handle   PFMultiplayerHandle

The handle of the PFMultiplayer API instance.

server   const PFEntityKey*

The server entity.

configuration   const PFMatchmakingServerBackfillTicketConfiguration*

The backfill ticket configuration.

asyncContext   void*
optional

An optional, app-defined, pointer-sized context value that can be used to associate the completion state change with this call.

ticket   PFMatchmakingTicketHandle*
library-allocated output

The resulting ticket object.

Return value

Type: HRESULT

S_OK if the call succeeded or an error code otherwise. The human-readable form of the error code can be retrieved via PFMultiplayerGetErrorMessage().

Returns E_POINTER if server, configuration or ticket is nullptr.

Remarks

To use this feature, you must define PFMULTIPLAYER_INCLUDE_SERVER_APIS before including PFMatchmaking.h.

The library automatically, and asynchronously, submits a server backfill ticket to the matchmaking service. Each time the ticket status changes, a PFMatchmakingTicketStatusChangedStateChange is provided. The ticket status can be queried at any time via PFMatchmakingTicketGetStatus(). The ticket immediately starts in the PFMatchmakingTicketStatus::Creating state.

When the ticket completes, the library provides a PFMatchmakingTicketStatusChangedStateChange with the final status, followed by a PFMatchmakingTicketCompletedStateChange whose result field reports success or the failure reason and whose asyncContext field contains the value you passed to this call. At that point, a match for the backfill ticket is found or the ticket stopped due to failure. If you destroy the ticket with PFMultiplayerDestroyMatchmakingTicket before it completes, the library doesn't provide the completion state change. On success, the match that was found can be queried via PFMatchmakingTicketGetMatch(). The regionPreferences in PFMatchmakingMatchDetails only contains the region that the server is located in.

If ticket creation fails because there are already too many tickets for the users specified in the configuration, the library transparently cancels those outstanding tickets and then retries ticket creation.

This function requires that a previous call to PFMultiplayerSetEntityToken() was made to set the game server entity token.

Requirements

Header: PFMatchmaking.h

See also

PFMatchmaking members