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

# PFMultiplayerCreateMatchmakingTicket

> 为一个或多个本地用户创建 PlayFab Multiplayer 匹配票证，将其提交到指定队列以便与其他玩家进行匹配。

为一个或多个本地用户创建匹配票证。

## 语法

```cpp theme={null}
HRESULT PFMultiplayerCreateMatchmakingTicket(  
    PFMultiplayerHandle handle,  
    uint32_t localUserCount,  
    const PFEntityKey* localUsers,  
    const char* const* localUserAttributes,  
    const PFMatchmakingTicketConfiguration* configuration,  
    void* asyncContext,  
    PFMatchmakingTicketHandle* ticket  
)  
```

### 参数

**`handle`**   PFMultiplayerHandle

PFMultiplayer API 实例的句柄。

**`localUserCount`**   uint32\_t

要包含在票证中的本地用户数量。

**`localUsers`**   [PFEntityKey\*](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/pfentitykey_clientsdk.md)\
*大小为 `localUserCount` 的输入数组*

要包含在票证中的本地用户数组。

**`localUserAttributes`**   char\* const\*\
*大小为 `localUserCount` 的输入数组*

本地用户属性字符串数组。每个本地用户应有一个属性字符串。每个属性字符串应为空字符串或已序列化的 JSON 对象。例如 `{"player_color":"blue","player_role":"tank"}`。

**`configuration`**   [PFMatchmakingTicketConfiguration\*](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketconfiguration.md)

票证配置。

**`asyncContext`**   void\*\
*optional*

可选的应用定义指针大小上下文值，可用于将完成状态变更与此调用相关联。

**`ticket`**   PFMatchmakingTicketHandle\*\
*library-allocated output*

生成的票证对象。

### 返回值

类型：HRESULT

如果调用成功，则为 `S_OK`；否则为错误代码。可以通过 [PFMultiplayerGetErrorMessage()](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayergeterrormessage.md) 获取错误代码的人类可读形式。

## 备注

库将自动且异步地把票证上指定的所有本地用户提交到匹配服务。每次票证状态更改时，都会提供一个 [PFMatchmakingTicketStatusChangedStateChange](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange.md)。可以随时通过 [PFMatchmakingTicketGetStatus()](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetstatus.md) 查询票证状态。票证立即从 `PFMatchmakingTicketStatus::Creating` 状态开始。\
\
 当票证完成时，将提供一个 [PFMatchmakingTicketStatusChangedStateChange](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange.md)。此时，要么找到匹配，要么票证因失败而停止。成功时，可以通过 [PFMatchmakingTicketGetMatch()](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch.md) 查询找到的匹配。\
\
 如果票证创建失败是因为指定用户的票证过多，库将透明地取消这些未完成的票证，然后重试票证创建。\
\
 直到 `configuration` 参数的 `membersToMatchWith` 字段中指定的所有远程用户都通过 [PFMultiplayerJoinMatchmakingTicketFromId()](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerjoinmatchmakingticketfromid.md) 加入票证，才能找到匹配。

## 要求

**头文件：** PFMatchmaking.h

## 另请参阅

[PFMatchmaking 成员](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members.md)


## Related topics

- [从 MPSD 迁移到 PlayFab Multiplayer 和 MPA](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-to-mlp.md)
- [Matchmaking SDK 快速入门](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)
- [PFMultiplayer C/C++ API 概览 - PFMatchmaking.h](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members.md)
- [异步 Lobby 和 Matchmaking C++ SDK 操作指南](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/lobby/lobby-and-matchmaking-client-sdk-async.md)
- [Create Matchmaking Ticket](https://docs.xbox.com/api-reference/matchmaking/create-matchmaking-ticket.md)