> ## 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 services タイトルにマルチプレイヤー ゲーム招待処理を追加します。

このトピックでは、XBOX services タイトルにゲーム招待を追加する方法について説明します。マルチプレイヤー招待を受信するには、ゲームがマルチプレイヤー プロトコルとゲーム招待コールバックを登録します。ゲームはローカル ユーザー宛ての招待を受信し、そのユーザーをマルチプレイヤー セッションに参加させます。

## 前提条件

Windows PC でゲーム招待通知を受信するには、XBOX Game Bar をインストールします。XBOX Game Bar アプリは、Windows 10 OS バージョン 1903 以降には既定でインストールされています。**Windows キー**+**G** キーを押して XBOX Game Bar アプリを起動し、正しくインストールされていることを確認します。

<Note>
  XBOX Game Bar が Windows PC にインストールされていない場合は、[Microsoft Store](https://www.microsoft.com/store/productId/9NZKPSTSNW4P) からインストールできます。
</Note>

## マルチプレイヤー プロトコルの登録

マルチプレイヤー プロトコルを登録すると、ユーザーがマルチプレイヤー ゲーム招待を承諾したときにシステムがゲームをどのように起動すべきかがわかります。マルチプレイヤー プロトコルを登録するには、次のコードのように、[MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc) ファイルに `MultiplayerProtocol` 要素を追加する必要があります。

```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 services ユーザーの ID です。
* `senderXuid` は、ゲーム招待を送信した XBOX services ユーザーの ID です。
* `context` は、送信者が含めた可能性のある追加の (オプションの) コンテキストです。

### 進行中のゲーム セッションに参加する場合

ユーザーがマルチプレイヤー セッションへの参加を試みると、ゲームは次のコードに示すような `inviteUri` を含む招待コールバックを受信します。

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

URI は常に "ms-xbl-multiplayer//" で始まり、その後に次のハンドルが続きます。

* `activityHandleJoin` は、ユーザーがゲーム招待を承諾したためにコールバックが開始されたことを示します。
* `handle` は、マルチプレイヤー セッションへの参加に使用するアクティビティ ハンドルです。
* `joinerXuid` は、マルチプレイヤー セッションに参加しようとしている XBOX services ユーザーの ID です。
* `joineeXuid` は、現在マルチプレイヤー セッションにいる XBOX services ユーザーの ID です。

## handleId を使用したマルチプレイヤー ゲーム セッションへの参加

### Multiplayer Manager の使用

Multiplayer Manager を使用している場合は、次のコードに示すように、[XblMultiplayerManagerJoinLobby](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby) API を使用して、`inviteUri` から抽出された `handleId` を渡すことにより、ユーザーをマルチプレイヤー セッションに参加させることができます。また、`invitedXuid` には `xblUserHandle` を使用することもできます。

#### Flat C

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

### Multiplayer API の直接使用

Multiplayer 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 contents)](/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 contents)](/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) [Multiplayer Manager を使用したゲーム起動のプロトコル アクティベーションの処理](/services/xbox-services/multiplayer/mpm/how-to/live-handle-protocol-activation)


## Related topics

- [Multiplayer Activity のサンプル コード](/ja-jp/services/xbox-services/multiplayer/mpa/how-to/live-mpa-client-how-to.md)
- [ロビーの招待](/ja-jp/services/playfab/multiplayer/lobby/lobby-invites.md)
- [招待の例コード](/ja-jp/services/xbox-services/multiplayer/invites/how-to/live-invites-howto-nav.md)
- [XblMultiplayerWriteSessionByHandleAsync](/ja-jp/reference/live/xsapi-c/multiplayer_c/functions/xblmultiplayerwritesessionbyhandleasync.md)
- [XblMultiplayerManagerJoinLobby](/ja-jp/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md)