PartyManager::CreateNewNetwork

[アーティクル]
01/30/2024

非同期の試みをキューに入れて新しいネットワークを作成します。

構文

PartyError CreateNewNetwork(  
    const PartyLocalUser* localUser,  
    const PartyNetworkConfiguration* networkConfiguration,  
    uint32_t regionCount,  
    const PartyRegion* regions,  
    const PartyInvitationConfiguration* initialInvitationConfiguration,  
    void* asyncIdentifier,  
    PartyNetworkDescriptor* networkDescriptor,  
    char* appliedInitialInvitationIdentifier  
)

パラメーター

localUser PartyLocalUser*

ネットワークの作成やリレーの割り当てが帰属するローカルユーザー。

networkConfiguration PartyNetworkConfiguration*

最大ユーザー数や最大デバイス数などのネットワーク構成プロパティ。これらのプロパティは、ネットワークの有効期間まで継続し、変更することはできません。

regionCount uint32_t

regions を介して指定された優先リージョンの配列で提供されるリージョンの数。これが 0 の場合、ライブラリはタイトルが構成されているすべてのリージョンを使用し、このデバイスからのラウンドトリップ待機時間が最も短い順に並べられます。

regions PartyRegion*

ネットワークを作成する場合の優先リージョンの配列。ネットワークは、最初に利用可能なリージョンに作成されます。

initialInvitationConfiguration PartyInvitationConfiguration*
オプション

最初の招待用にオプションで指定された構成。

この値が null の場合は、既定の構成値が使用されます。既定では、PlayFab パーティーはタイトル用に固有の招待識別子を生成し、失効可能性は PartyInvitationRevocability::Anyone となり、PlayFab エンティティ ID リストは空になり、招待を使用して任意のユーザーが参加できるようになります。

構成が指定されている場合、タイトルは任意で構成上の識別子を指定することができます。識別子が nullptr または空の文字列の場合、PlayFab パーティーライブラリはタイトルの識別子を生成します。これは、PlayFab パーティーライブラリが、すべてのデバイスでこのネットワーク上のすべての今後の招待に対して生成するすべての識別子とは異なることが保証されます。タイトルは、構成に null 以外の空でない値を指定することで、独自の識別子を指定できます。タイトルが識別子を指定する場合、この識別子が、任意のデバイスで PartyNetwork::CreateInvitation() を介してこのネットワーク上に作成される将来の招待の識別子と競合しないようにするのは、タイトルの責任です。

システム構成が指定された場合、その失効可能性は PartyInvitationRevocability::Anyone であることが必要です。

システム構成が指定され、PlayFab エンティティ ID リストが空の場合、すべてのユーザーが新しい招待を使用して参加することができます。

asyncIdentifier void*
オプション

完了状態の変更をこの呼び出しに関連付けるために使用できる、オプションの、アプリによって定義されたポインターサイズのコンテキスト値。

networkDescriptor PartyNetworkDescriptor*
オプションの出力

オプションで、ConnectToNetwork() を介して新しく作成されたネットワークへのローカルデバイスの接続を瞬時にキューに入れるために使用できる出力ネットワーク記述子です。

appliedInitialInvitationIdentifier char*
オプションのサイズ c_maxInvitationIdentifierStringLength+1 の出力文字列バッファ

最初の招待の識別子が書き込まれる出力バッファ (オプション) です。 initialInvitationConfiguration に null 以外の空でない識別子が指定されている場合、このバッファーには同じ識別子が入力されます。初期構成が指定されていない場合、または指定された構成に空の識別子または null 識別子がある場合、PlayFab パーティーライブラリは識別子を生成し、このバッファー内のタイトルに返します。

戻り値

PartyError

新しいネットワークを作成する非同期操作が開始された場合は c_partyErrorSuccess、それ以外の場合はエラーコードになります。このメソッドが失敗した場合、関連する状態の変更は発生しません。人間が判読できる形式のエラーコードは、GetErrorMessage() を介して取得できます。

解説

PartyNetwork とは、クライアント-サーバートポロジを介して透過的なクラウドリレーサーバーに接続される一連のデバイスです。ネットワークにある各デバイスには、ネットワークに関連付けられたエンドポイントのコレクションが含まれ、この中ではローカルデバイス上のエンドポイントから指向性のあるメッセージを任意のエンドポイントのセットに送信したり、すべてのエンドポイントにブロードキャストしたりすることができます。このメソッドは、localUser で表されるユーザーに代わってリレーを割り当て、新しいネットワークを作成しようとする試みをキューに入れますが、ローカルデバイスをネットワークに接続することはありません。

リレーの作成から 10 分以内にネットワークに接続するデバイスがない場合は、シャットダウンされます。少なくとも 1 つのデバイスが接続されている間、ネットワークは無期限にアクティブなままになり、必要に応じて新しいリレーに移行されます。ネットワークにデバイスが接続されていない場合、リレーは非アクティブになり、1 分後にシャットダウンされます。

ローカルデバイスは、networkDescriptor を直ちに ConnectToNetwork() に渡すことで、新しいネットワークへの接続試行をキューに入れることができます。 SerializeNetworkDescriptor() を含むこの記述子を使用すると、記述子にはリモートデバイスがネットワークに接続するための十分な情報が含まれていないため、失敗します。ネットワーク記述子は、PartyCreateNewNetworkCompletedStateChange が指定された場合に変更されてシリアル化可能になり、成功を示します。更新されたネットワーク記述子は、PartyCreateNewNetworkCompletedStateChange のフィールドとして指定されます。この記述子は、PartyNetwork::GetNetworkDescriptor() を使用してネットワークに接続した後に取得することもできます。

ネットワークは、regions で指定された順序で、最初に利用可能なリージョンに作成されます。指定したリージョンが利用できない場合は、ネットワークは作成されません。 regionCount に 0 を指定すると、既定で、タイトルが構成されているすべてのリージョンを、GetRegions() によって返される配列と同じ、このデバイスへの待機時間が最も小さい順に使用することになる。

既定のリージョン選択では、このデバイスからの待機時間の測定値のみが含まれ、他のデバイスからの測定値は含まれません。セッションの一連の参加者を事前に把握しているタイトルでは、ネットワークを作成する前にすべてのデバイスから測定値を収集し、グループ全体の合計待機時間が最も低い順に新しい regions 配列を構築する必要があります。

途中参加をサポートするタイトルでは、接続済み参加者のグループで総合的に最良の待機時間を含むリージョンが、デバイスの参加と離脱によって変更する可能性があります。タイトルは、Party がサポートする複数のネットワークへの同時接続を利用して、グループ全体の待機時間がより良いリージョンで作成されたネットワークにデバイスをシームレスに移行することができます。タイトルは、オリジナルの Party ネットワーク上のメッセージまたは外部の名簿サービスにアップロードされた情報を介してリージョンの待機時間測定値を収集し、待機時間が短いリージョンに新しい Party ネットワークを作成し、すべてのデバイスに、より有利なネットワークに接続して、元のネットワークから切断するように指示することができます。

PartyOption::RegionUpdateConfiguration オプションを使用して更新モードを PartyRegionUpdateMode::Deferred で構成した場合、利用可能なリージョンのセットを取得とそのリージョンに対する接続品質の測定がまだ開始されていないか、最後の更新が構成された更新間隔の経過期間を超えている可能性があります。 CreateNewNetwork() に regionCount の 0 を指定すると、この呼び出しの PartyCreateNewNetworkCompletedStateChange が完了する前に、遅延リージョンの更新が開始され、関連する PartyRegionsChangedStateChange が提供されます。

新たに作成されたネットワークの最初の招待は、どのユーザーにも所有されません。そのため、PartyInvitation::GetCreatorEntityId() の呼び出しでは、最初の招待に対して nullptr が返されます。最初の招待は、PartyNetwork::RevokeInvitation() を介して明示的に取り消されるまで、ネットワークの有効期間中も保持されます。ネットワークに認証されたローカルユーザーは、PartyNetwork::CreateInvitation() を介してネットワークに新しい招待を作成することができ、作成したローカルユーザーがネットワークから削除されるまで、これらの招待は保持されます。ユーザーは、正常に作成され、取り消されることなくユーザーの参加を許可する招待の識別子を指定することで PartyNetwork::AuthenticateLocalUser() を介してネットワークに参加します。

失敗時の再試行

CreateNewNetwork() が非同期に失敗した場合、StartProcessingStateChanges が結果を示すことにより PartyCreateNewNetworkCompletedStateChange が指定されます。指定された PartyStateChangeResult に応じて、操作が遅れて再試行される場合があります。

結果	再試行の動作
InternetConnectivityError	10 秒以上の小さな遅延で再試行します。お使いのアプリでは、自動的に再試行するのではなく、すぐにユーザーにエラーを表示する方が適切な場合があります。
PartyServiceError	エクスポネンシャルバックオフを使用して再試行します。最小 10 秒以上の遅延で開始し、再試行するたびに遅延時間を倍にしていきます。
NoServersAvailable	エクスポネンシャルバックオフを使用して再試行します。最小 30 秒以上の遅延で開始し、再試行するたびに遅延時間を倍にしていきます。お使いのアプリでは、自動的に再試行するのではなく、すぐにユーザーにエラーを表示する方が適切な場合があります。
UserNotAuthorized	この結果は、ユーザーのエンティティトークンが無効、期限切れ、またはその他の理由でユーザーが認証されないことを意味します。再試行は 1 回までとし、ユーザーに新しいエンティティトークンを取得して PartyLocalUser::UpdateEntityToken() を呼び出した後にのみ行われます。
UserCreateNetworkThrottled	自動的に再試行しないでください。代わりに、ユーザーにメッセージを表示し、ユーザーが次の試行を開始するまで待機します。
FailedToBindToLocalUdpSocket	この結果は、PartyOption::LocalUdpSocketBindAddress オプションで指定されたローカル UDP ソケットにライブラリがバインドできなかったことを意味します。タイトルは、ライブラリのインスタンスをクリーンアップし、PartyOption::LocalUdpSocketBindAddress オプションを有効で、アドレスをバインドでき、ライブラリを再初期化するよう更新します。

要件

ヘッダー: Party.h

次の方法で共有

PartyManager::CreateNewNetwork

構文

パラメーター

戻り値

解説

失敗時の再試行

要件

関連項目

フィードバック

その他のリソース