構文
パラメーター
targetEndpointCount uint32_t
targetEndpoints 配列内のターゲット エンドポイントの数。ネットワーク内のすべてのリモート エンドポイントにブロードキャストするには 0 を指定できます。ブロードキャスト メッセージを受信するデバイスでは、PartyEndpointMessageReceivedStateChange のターゲット エンドポイント フィールドに、そのデバイスのすべてのローカル エンドポイントが設定されます。
targetEndpoints PartyEndpointArrayサイズ
targetEndpointCount の入力配列
メッセージの送信先となるターゲット PartyEndpoint オブジェクト ポインターの targetEndpointCount エントリ配列。targetEndpointCount が 0 の場合、この値は無視されます。
options PartySendMessageOptions
メッセージの送信方法を記述する 0 個以上のオプション フラグ。
queuingConfiguration PartySendMessageQueuingConfiguration*省略可能 ローカルにキューイングされ、送信の機会を待っている間のメッセージの動作を記述するオプションの構造体。既定のキューイング動作を使用するには nullptr にできます。
dataBufferCount uint32_t
dataBuffers 配列に指定されているバッファー構造体の数。0 より大きい必要があります。
dataBuffers PartyDataBuffer*サイズ
dataBufferCount の入力配列
送信するメッセージ ペイロードを記述する PartyDataBuffer 構造体の dataBufferCount エントリ配列。
messageIdentifier void*省略可能 このメッセージを参照するすべての状態変化に Party ライブラリが含める、不透明な呼び出し元固有のコンテキスト ポインター。解釈されたり、リモートに送信されたりすることはありません。メッセージ識別コンテキストが不要な場合は nullptr にできます。
戻り値
PartyError 送信のためのメッセージのエンキューが成功した場合はc_partyErrorSuccess、それ以外の場合はエラー コード。このメソッドが失敗した場合、関連する状態変化は生成されません。エラー コードの人間が判読可能な形式は、PartyManager::GetErrorMessage() から取得できます。
解説
ローカル エンドポイントへのメッセージ送信は現在サポートされていません。ターゲット エンドポイントの配列にローカル ターゲットが含まれている場合、この呼び出しは同期的に失敗します。特定のデバイス上のすべてのターゲット エンドポイントには、単一の PartyEndpointMessageReceivedStateChange が提供され、対象となったすべてのローカル エンドポイントが PartyEndpointMessageReceivedStateChange の receiverEndpoints 配列に含まれます。
ターゲット エンドポイントの配列がエントリを 0 個持つとして指定された場合、メッセージは現在ネットワークにあるすべてのリモート エンドポイントにブロードキャストされます。
呼び出し元は、
dataBuffers 配列に 1 つ以上の PartyDataBuffer 構造体を提供します。構造体が参照するメモリは連続している必要がないため、たとえば固定ヘッダー バッファーの後に可変ペイロードを続けるといった構成が簡単に行えます。バッファーは順番に組み立てられ、送信され、PartyEndpointMessageReceivedStateChange 内の単一の連続したデータ ブロックとしてターゲット エンドポイントに配信されます。Party ライブラリは、元の PartyDataBuffer のセグメント化を記述するメタデータの送信に帯域幅を消費しません。 既定では、呼び出し元の
dataBuffers 配列に記述されたバッファーは、SendMessage() が戻る前に割り当てられたバッファーにコピーされます。PartySendMessageOptions::DontCopyDataBuffers を指定すると、この追加のコピー ステップが回避されますが、代わりに、PartyDataBuffersReturnedStateChange がメモリの所有権を呼び出し元に返すまで、各バッファーで指定されたメモリを有効かつ変更されないまま保持することが呼び出し元に要求されます。PartyDataBuffer 構造体自体は、SendMessage() 呼び出しが戻った後は有効である必要はなく、有効である必要があるのは、それらが参照するメモリだけです。 PartySendMessageOptions::DontCopyDataBuffers を使用する呼び出し元は、呼び出し元固有の
messageIdentifier コンテキストを提供できます。このポインター サイズの値はすべての PartyDataBuffersReturnedStateChange に含まれるので、呼び出し元は独自のプライベート メッセージ追跡情報に簡単にアクセスできます。実際の値は不透明なものとして扱われ、Party ライブラリによって解釈されることも、リモートに送信されることもありません。messageIdentifier が表す可能性のある呼び出し元自身のメモリが、メッセージおよび関連する messageIdentifier に関連付けられた最後の要求された状態変化が処理され、PartyManager::FinishProcessingStateChanges() を介して返されるまで有効に保たれることを保証するのは、呼び出し元の責任です。 メッセージは、接続品質や受信側の応答性などの要因により、ターゲット エンドポイントにすぐに送信されない場合があります。エンドポイントへの接続が現在サポートしていると推定される速度よりも速く送信している場合、ローカル送信キューが増加します。これによりメモリ使用量が増加し、体感されるメッセージ待機時間が増加する可能性があるので、呼び出し元にはローカル送信キューを監視および管理することを強く推奨します。送信キューに関する情報は、PartyLocalEndpoint::GetEndpointStatistics() を使用して取得できます。送信キューは、送信のサイズや頻度を減らすこと、
queuingConfiguration オプション設定を使用して長時間キューに残ったメッセージを自動的に期限切れにするタイムアウトを構成すること、または PartyLocalEndpoint::CancelMessages() を使用してキューに入っているメッセージの一部またはすべてを明示的に削除することによって管理できます。 このメソッドが成功を返した場合、メッセージは送信を開始したか、将来の送信のためにキューに正常に追加されました。特に、このメソッドからの正常な戻りは、メッセージが受信者に正常に配信されたことを意味しません。Party API では現在、個々のメッセージの配信と処理を追跡する方法は提供されていません。PartyNetwork::GetNetworkStatistics() および GetEndpointStatistics() メソッドを使用すると、ネットワーク全体または個々のローカル エンドポイントの集計統計をそれぞれクエリできます。
options に PartySendMessageOptions::GuaranteedDelivery が含まれ、メッセージが転送先エンドポイントへの転送のために透過的クラウド リレー サーバーに正常に配信できなかった場合、PartyNetworkDestroyedStateChange が生成されます。つまり、配信保証要件のあるメッセージは配信されるか、そうでなければ送信元クライアントがネットワークから切断されます。透過的クラウド リレー サーバーが配信保証メッセージを 1 つ以上のターゲット エンドポイントを含む各リモート デバイスに転送する際に、メッセージを配信できなかった場合、リモート デバイスも同様にネットワークから切断され、PartyNetworkDestroyedStateChange によって示されます。つまり、配信保証要件のあるメッセージの受信に失敗したデバイスは、ネットワークから切断されます。 Party ライブラリは、環境でサポートされる最大サイズを超える大きなメッセージを自動的にフラグメント化して再構築するので、呼び出し元がこれを管理する必要はありません。ただし、フラグメント化にはわずかなオーバーヘッドが伴います。より小さなメッセージを送信できる、または大きな状態ペイロードを自分で効率的に自然に分割できる呼び出し元は、そうすることを検討することもできます。
SendMessage() が、最初のユーザーがネットワークへの認証に成功する前に、ターゲット エンドポイント配列が 0 エントリで呼び出された場合、リモート エンドポイントが PartyEndpointCreatedStateChange 状態変化を介して報告されていない (したがってネットワークに存在することがわかっている) にもかかわらず、メッセージはそれでもキューに入れられます。最初のユーザーが認証に成功し、この送信元のローカル エンドポイントが正常に作成されると、キューに入れられたメッセージは、その後の時点でネットワークに存在するすべてのリモート エンドポイントを対象にします。この場合、SendMessage() の時点ではネットワークの将来の状態と最終的に受信するエンドポイントのセットが不明であるため、タイトルはそのような遅延ブロードキャスト メッセージにどのようなコンテンツを配置するかについて注意を払うか、このローカル デバイスとエンドポイントがネットワークに完全に参加するまで、単にそれらの送信を控える必要があります。
要件
ヘッダー: Party.h関連項目
PartyLocalEndpointPartySendMessageOptions
PartySendMessageQueuingConfiguration
PartyDataBuffersReturnedStateChange
PartyEndpointMessageReceivedStateChange
PartyNetwork::GetNetworkStatistics
PartyLocalEndpoint::GetEndpointStatistics
PartyLocalEndpoint::FlushMessages