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

# 接收邀请

> 通过注册多人游戏协议和 XGameActivation 邀请事件回调，将多人游戏邀请处理添加到你的 XBOX 服务游戏中。

使用本主题将游戏邀请添加到你的 XBOX 服务游戏中。要接收多人游戏邀请，你的游戏需要注册多人游戏协议和游戏邀请回调。你的游戏接收本地用户的邀请，然后将该用户加入到多人游戏会话中。

## 先决条件

要在 Windows PC 上接收游戏邀请通知，请安装 XBOX Game Bar。默认情况下，Windows 10 操作系统 1903 版或更高版本上安装了 XBOX Game Bar 应用。选择 **Windows 键**+**G** 来启动 XBOX Game Bar 应用，以验证它是否已正确安装。

<Note>
  如果 Windows PC 上未安装 XBOX Game Bar，你可以从 [Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P) 安装它。
</Note>

## 注册多人游戏协议

注册多人游戏协议会告诉系统在用户接受多人游戏邀请时如何启动你的游戏。要注册多人游戏协议，需要将 `MultiplayerProtocol` 元素添加到 [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc) 文件中，如以下代码所示。

```xml theme={null}
    <MultiplayerProtocol>true</MultiplayerProtocol>
```

如果程序包中有多个可执行文件，你可以使用 `Executable` 属性指定哪个可执行文件处理多人游戏协议，如以下代码所示。

```xml theme={null}
    <MultiplayerProtocol Executable="MyExecutableForMultiplayer.exe">true</MultiplayerProtocol>
```

## 注册多人游戏邀请回调

<Info>
  `XGameInviteRegisterForEvent` 和 `XGameInviteUnregisterForEvent` API 现已被弃用。请改用 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 和 [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)。有关迁移指南，请参阅 [XGameActivation](/reference/system/xgameactivation/xgameactivation_members#remarks)。
</Info>

要接收多人游戏邀请回调，必须通过使用 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) API 注册激活回调，如以下代码所示。

有关注册和注销激活回调的详细信息，请参阅 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 和 [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)。

### Flat C

```cpp theme={null}
#include <XTaskQueue.h>
#include <XGameActivation.h>  
  
XTaskQueueHandle g_taskQueue;  
XTaskQueueRegistrationToken g_activationToken;  
  
void CALLBACK OnActivation(void* context, const XGameActivationInfo* activationInfo)  
{  
    if (activationInfo->type == XGameActivationType::AcceptedGameInvite)
    {
        if (activationInfo->inviteUri != nullptr)
        {
            std::string inviteString(activationInfo->inviteUri);
            auto pos = inviteString.find("handle=");
            auto handleId = inviteString.substr(pos + 7, 36);
            // Now call XblMultiplayerManagerJoinLobby
        }
    }
}  
  
void InitializeGame()  
{  
    XGameActivationRegisterForEvent(g_taskQueue, nullptr, OnActivation, &g_activationToken);  
}  
  
void ShutdownGame()  
{  
    XGameActivationUnregisterForEvent(g_activationToken, true);  
}  
```

为了正确处理"从挂起状态接受邀请"的场景，游戏必须存储在上面示例代码中传递给 [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent) 回调的 `OnActivation()` 处理程序方法的 `inviteUri`。然后，游戏必须等待 `RegisterAppStateChangeNotification`，该通知会在游戏完全恢复时进行通知，然后游戏才能继续使用 `inviteUri` 中提供的详细信息操作会话。

有关 `RegisterAppStateChangeNotification` 的详细信息，请参阅 [XBOX 游戏生命周期（NDA 主题）](/build/console-features/console-workflows/xbox-game-life-cycle)。

## 从 XGameActivationCallback 解析 inviteUri

当你的游戏收到激活类型为 `AcceptedGameInvite` 的 [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback) 事件时，你可以从 [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo) 结构中访问 `inviteUri` 字符串。`inviteUri` 采用以下格式之一。

### 接受游戏邀请

当用户接受游戏邀请时，游戏会收到游戏邀请回调，其 `inviteUri` 如以下代码所示。

```cpp theme={null}
    "ms-xbl-multiplayer://inviteHandleAccept?handle=%s&invitedXuid=%s&senderXuid=%s&context=%s"
    
    // for example:
    // "ms-xbl-multiplayer://inviteHandleAccept?handle=00000000-0000-1234-5678-1234567890ab&invitedXuid=1234567890123456&senderXuid=6543210987654321&context="
```

URI 始终以 "ms-xbl-multiplayer//" 开头，随后是以下句柄。

* `inviteHandleAccept` 表示回调是因为用户接受了游戏邀请而启动的。
* `handle` 是你用于加入多人游戏会话的邀请句柄。
* `invitedXuid` 是被邀请加入多人游戏会话的 XBOX 服务用户的 ID。
* `senderXuid` 是发送游戏邀请的 XBOX 服务用户的 ID。
* `context` 是发送方可能包含的额外（可选）上下文。

### 加入进行中的游戏会话

当用户尝试加入多人游戏会话时，游戏会收到邀请回调，其 `inviteUri` 如以下代码所示。

```cpp theme={null}
    "ms-xbl-multiplayer://activityHandleJoin?&handle=%s&joinerXuid=%s&joineeXuid=%s"
```

URI 始终以 "ms-xbl-multiplayer//" 开头，随后是以下句柄。

* `activityHandleJoin` 表示回调是因为用户接受了游戏邀请而启动的。
* `handle` 是你用于加入多人游戏会话的活动句柄。
* `joinerXuid` 是尝试加入多人游戏会话的 XBOX 服务用户的 ID。
* `joineeXuid` 是当前在多人游戏会话中的 XBOX 服务用户的 ID。

## 使用 handleId 加入多人游戏会话

### 使用多人游戏管理器

如果你使用多人游戏管理器，则可以通过使用 [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) API 并传入从 `inviteUri` 中提取的 `handleId` 来将用户加入到多人游戏会话中。你还可以使用 `xblUserHandle` 作为 `invitedXuid`，如以下代码所示。

#### Flat C

```cpp theme={null}
HRESULT hr = XblMultiplayerManagerJoinLobby(handleId, xblUserHandle);
```

### 直接使用多人游戏 API

如果你使用多人游戏 API，请按以下步骤配置游戏的多人游戏会话和邀请。

1. 通过使用 [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync) API 并将其传递到 `handleId` 中来获取多人游戏会话文档。
2. 通过使用 [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin) API 将本地用户加入到多人游戏会话文档中。
3. 通过使用 [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync) API 将多人游戏会话文档写入服务以提交此更改。

## 参考 API 文档

* [Xgameactivation (API 内容)](/reference/system/xgameactivation/xgameactivation_members)
  * 函数
    * [XGameActivationRegisterForEvent](/reference/system/xgameactivation/functions/xgameactivationregisterforevent)
    * [XGameActivationUnregisterForEvent](/reference/system/xgameactivation/functions/xgameactivationunregisterforevent)
    * [XGameActivationCallback](/reference/system/xgameactivation/functions/xgameactivationcallback)
  * 结构
    * [XGameActivationInfo](/reference/system/xgameactivation/structs/xgameactivationinfo)
* [multiplayer\_manager\_c (API 内容)](/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members)
  * 函数
    * [XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby)
    * [XblMultiplayerGetSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync)
    * [XblMultiplayerSessionJoin](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin)
    * [XblMultiplayerWriteSessionByHandleAsync](/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync)

## 另请参阅

[XGameActivation API](/reference/system/xgameactivation/xgameactivation_members) [使用多人游戏管理器处理协议激活以启动游戏](/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)