> ## 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.

# PFMultiplayerJoinMatchmakingTicketFromId

> 使用初始票证创建者共享的票证 ID 和队列名称，将一个或多个本地用户加入到现有的 PlayFab 多人游戏匹配票证。

使用票证 ID 和队列名称将一个或多个本地用户加入到匹配票证。

## 语法

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

### 参数

**`handle`**   PFMultiplayerHandle

PFMultiplayer API 实例的句柄。

**`localUserCount`**   uint32\_t

要加入票证的本地用户数量。

**`localUsers`**   [PFEntityKey\*](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/pfentitykey_clientsdk)\
*大小为 `localUserCount` 的输入数组*

要加入票证的本地用户数组。

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

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

**`ticketId`**   char\*\
*is null-terminated*

要加入的票证的 ID。

**`queueName`**   char\*\
*is null-terminated*

票证所属的队列。

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

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

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

生成的票证对象。

### 返回值

类型：HRESULT

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

## 备注

库将自动且异步地将所有指定的本地用户提交到匹配服务以加入票证。每次票证状态更改时，都会提供一个 [PFMatchmakingTicketStatusChangedStateChange](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange)。可以随时通过 [PFMatchmakingTicketGetStatus()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetstatus) 查询票证状态。票证立即从 `PFMatchmakingTicketStatus::Joining` 状态开始。<br /><br /> 当票证完成时，将提供一个 [PFMatchmakingTicketStatusChangedStateChange](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketstatuschangedstatechange)。此时，要么找到匹配，要么票证因失败而停止。成功时，可以通过 [PFMatchmakingTicketGetMatch()](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch) 查询找到的匹配。<br /><br /> 如果票证创建失败是因为指定用户的票证过多，将透明地取消这些未完成的票证，然后重试票证创建。

## 要求

**头文件：** PFMatchmaking.h

## 另请参阅

[PFMatchmaking 成员](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/pfmatchmaking_members)


## Related topics

- [从 MPSD 迁移到 PlayFab Multiplayer 和 MPA](/zh-CN/services/xbox-services/multiplayer/mpsd/concepts/live-mpsd-to-mlp.md)
- [PFMatchmakingTicketStatus](/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/enums/pfmatchmakingticketstatus.md)
- [PFMatchmakingTicketConfiguration](/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketconfiguration.md)
- [PFMultiplayerCreateMatchmakingTicket](/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreatematchmakingticket.md)
- [Matchmaking SDK 快速入门](/zh-CN/services/playfab/multiplayer/matchmaking/quickstart-client-sdk.md)