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

# 接收邀請

> 透過註冊多人遊戲通訊協定和 XGameActivation 邀請事件回呼，將多人遊戲邀請處理新增至您的 XBOX 服務遊戲。

使用本主題將遊戲邀請新增至您的 XBOX 服務遊戲。若要接收多人遊戲邀請，您的遊戲需註冊多人遊戲通訊協定和遊戲邀請回呼。您的遊戲會為本機使用者接收邀請，然後讓該使用者加入多人遊戲工作階段。

## 必要條件

若要在 Windows PC 上接收遊戲邀請通知，請安裝 XBOX Game Bar。XBOX Game Bar 應用程式預設會安裝在 Windows 10 OS 版本 1903 或更新版本上。選取 **Windows 鍵**+**G** 以啟動 XBOX Game Bar 應用程式，確認其已正確安裝。

> [!NOTE]
>
> 如果您的 Windows PC 上未安裝 XBOX Game Bar，您可以從 [Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P) 安裝它。

## 註冊多人遊戲通訊協定

註冊多人遊戲通訊協定會告知系統在使用者接受多人遊戲邀請時如何啟動您的遊戲。若要註冊多人遊戲通訊協定，您需要將 `MultiplayerProtocol` 元素新增至您的 [MicrosoftGame.config](https://docs.xbox.com/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-toc.md) 檔案，如下列程式碼所示。

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

如果套件中有多個可執行檔，您可以使用 `Executable` 屬性指定由哪個可執行檔處理多人遊戲通訊協定，如下列程式碼所示。

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

## 註冊多人遊戲邀請回呼

> [!NOTE]
>
> `XGameInviteRegisterForEvent` 和 `XGameInviteUnregisterForEvent` API 現在已淘汰。請改用 [XGameActivationRegisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) 和 [XGameActivationUnregisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md)。如需移轉指引，請參閱 [XGameActivation](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/xgameactivation_members.md#remarks)。

若要接收多人遊戲邀請回呼，您必須使用 [XGameActivationRegisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) API 註冊啟用回呼，如下列程式碼所示。

如需註冊和取消註冊啟用回呼的詳細資訊，請參閱 [XGameActivationRegisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) 和 [XGameActivationUnregisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md)。

### 平面 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](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md) 回呼傳入上述範例程式碼中 `OnActivation()` 處理常式方法的 `inviteUri`。然後，遊戲必須等待 `RegisterAppStateChangeNotification` 通知遊戲已完全繼續，才能使用 `inviteUri` 中提供的詳細資料對工作階段進行操作。

如需 `RegisterAppStateChangeNotification` 的詳細資訊，請參閱 [XBOX 遊戲生命週期 (NDA 主題)](https://docs.xbox.com/zh-TW/build/console-features/console-workflows/xbox-game-life-cycle.md)。

## 從 XGameActivationCallback 剖析 inviteUri

當您的遊戲收到啟用類型為 `AcceptedGameInvite` 的 [XGameActivationCallback](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationcallback.md) 事件時，您可以從 [XGameActivationInfo](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/structs/xgameactivationinfo.md) 結構存取 `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 服務使用者的識別碼。
* `senderXuid` 是傳送遊戲邀請之 XBOX 服務使用者的識別碼。
* `context` 是傳送者可能包含的額外 (選擇性) 內容。

### 加入進行中的遊戲工作階段時

當使用者嘗試加入多人遊戲工作階段時，遊戲會收到包含 `inviteUri` 的邀請回呼，如下列程式碼所示。

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

URI 一律以 "ms-xbl-multiplayer//" 開頭，後面接著下列控制代碼。

* `activityHandleJoin` 表示回呼是因為使用者接受了遊戲邀請而起始的。
* `handle` 是您用來加入多人遊戲工作階段的活動控制代碼。
* `joinerXuid` 是嘗試加入多人遊戲工作階段之 XBOX 服務使用者的識別碼。
* `joineeXuid` 是目前位於多人遊戲工作階段中之 XBOX 服務使用者的識別碼。

## 使用 handleId 加入多人遊戲工作階段

### 使用多人遊戲管理員

如果您使用的是多人遊戲管理員，可以使用 [XblMultiplayerManagerJoinLobby](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md) API 並傳入從 `inviteUri` 擷取的 `handleId`，讓使用者加入多人遊戲工作階段。您也可以為 `invitedXuid` 使用 `xblUserHandle`，如下列程式碼所示。

#### 平面 C

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

### 直接使用多人遊戲 API

如果您使用的是多人遊戲 API，請使用下列步驟為您的遊戲設定多人遊戲工作階段和邀請。

1. 使用 [XblMultiplayerGetSessionByHandleAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md) API 擷取多人遊戲工作階段文件，並傳入 `handleId`。
2. 使用 [XblMultiplayerSessionJoin](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md) API 將本機使用者加入多人遊戲工作階段文件。
3. 使用 [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md) API 將多人遊戲工作階段文件寫入服務，以認可此變更。

## 參考 API 文件

* [Xgameactivation (API 內容)](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/xgameactivation_members.md)
  * 函式
    * [XGameActivationRegisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationregisterforevent.md)
    * [XGameActivationUnregisterForEvent](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationunregisterforevent.md)
    * [XGameActivationCallback](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/functions/xgameactivationcallback.md)
  * 結構
    * [XGameActivationInfo](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/structs/xgameactivationinfo.md)
* [multiplayer\_manager\_c (API 內容)](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/multiplayer_manager_c_members.md)
  * 函式
    * [XblMultiplayerManagerJoinLobby](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md)
    * [XblMultiplayerGetSessionByHandleAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayergetsessionbyhandleasync.md)
    * [XblMultiplayerSessionJoin](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayersessionjoin.md)
    * [XblMultiplayerWriteSessionByHandleAsync](https://docs.xbox.com/zh-TW/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)

## 另請參閱

[XGameActivation API](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/xgameactivation_members.md) [使用多人遊戲管理員處理通訊協定啟用以啟動遊戲](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation.md)


## Related topics

- [多人遊戲活動的範例程式碼](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [邀請](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/invites/index.md)
- [大廳邀請](https://docs.xbox.com/zh-TW/services/playfab/multiplayer/lobby/lobby-invites.md)
- [邀請範例程式碼](https://docs.xbox.com/zh-TW/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)
- [XGameActivation (API 內容)](https://docs.xbox.com/zh-TW/reference/system/xgameactivation/xgameactivation_members.md)