PFMultiplayerCreateMatchmakingTicket

Creates a matchmaking ticket for one or more local users.

Syntax

HRESULT PFMultiplayerCreateMatchmakingTicket(  
    PFMultiplayerHandle handle,  
    uint32_t localUserCount,  
    const PFEntityKey* localUsers,  
    const char* const* localUserAttributes,  
    const PFMatchmakingTicketConfiguration* configuration,  
    void* asyncContext,  
    PFMatchmakingTicketHandle* ticket  
)  

Parameters

handle   PFMultiplayerHandle

The handle of the PFMultiplayer API instance.

localUserCount   uint32_t

The count of local users to include in the ticket.

localUsers   PFEntityKey*
input array of size localUserCount

The array of local users to include in the ticket.

localUserAttributes   char* const*
input array of size localUserCount

The array of local user attribute strings. There should be one attribute string for each local user. Each attribute string should either be an empty string or a serialized JSON object. For example, {"player_color":"blue","player_role":"tank"}.

configuration   PFMatchmakingTicketConfiguration*

The 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().

Remarks

The library automatically, and asynchronously, submits all specified local users on a 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, a PFMatchmakingTicketStatusChangedStateChange is provided. At that point, a match was found or the ticket stopped due to failure. On success, the match that was found can be queried via PFMatchmakingTicketGetMatch().

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

A match can't be found until all remote users specified in the membersToMatchWith field of the configuration parameter join the ticket via PFMultiplayerJoinMatchmakingTicketFromId().

Requirements

Header: PFMatchmaking.h

See also

PFMatchmaking members