PartyLocalEndpoint::SendMessage

[アーティクル]
07/15/2023

ネットワークで他のエンドポイントにメッセージを送信します。

構文

PartyError SendMessage(  
    uint32_t targetEndpointCount,  
    PartyEndpointArray targetEndpoints,  
    PartySendMessageOptions options,  
    const PartySendMessageQueuingConfiguration* queuingConfiguration,  
    uint32_t dataBufferCount,  
    const PartyDataBuffer* dataBuffers,  
    void* messageIdentifier  
)

パラメーター

targetEndpointCount uint32_t

targetEndpoints 配列内のターゲットエンドポイントの数。ゼロを指定して、ネットワークにあるすべてのリモートエンドポイントにブロードキャストすることができます。ブロードキャストメッセージを受信したデバイスは、PartyEndpointMessageReceivedStateChange のターゲットエンドポイントフィールドに、デバイスのすべてのローカルエンドポイントが入力されます。

targetEndpoints PartyEndpointArray
サイズ targetEndpointCount の入力配列

メッセージを送信する対象となる PartyEndpoint オブジェクトポインタの targetEndpointCount エントリ配列。これは、targetEndpointCount がゼロの場合は無視されます。

options PartySendMessageOptions

メッセージの送信方法を示すゼロ以上のオプションフラグ。

queuingConfiguration PartySendMessageQueuingConfiguration*
オプション

ローカルでキューに入り、送信の機会を待機する間、メッセージがどのように動作する必要があるかを記述したオプションの構造体です。既定のキュー動作を使用するには、nullptr を指定します。

dataBufferCount uint32_t

dataBuffers 配列で提供されるバッファー構造体の数。 0 より大きくなければなりません。

dataBuffers PartyDataBuffer*
サイズ dataBufferCount の入力配列

送信するメッセージのペイロードを記述した PartyDataBuffer 構造体の dataBufferCount エントリ配列。

messageIdentifier void*
オプション

Party ライブラリが、このメッセージを参照するすべての状態変化に含める、あいまいで発信者固有のコンテキストポインタ。リモートで解釈したり送信したりするものではありません。メッセージ識別コンテキストが必要ない場合は、nullptr を指定できます。

戻り値

PartyError

c_partyErrorSuccessメッセージの送信のためのキュー登録が成功した場合、またはエラーコードの場合。このメソッドが失敗した場合、関連する状態の変更は発生しません。人間が読める形式のエラーコードは、PartyManager::GetErrorMessage() を介して取得できます。

解説

ローカルエンドポイントへのメッセージ送信は現在サポートされていません。ターゲットエンドポイントの配列にローカルターゲットが含まれていた場合、この呼び出しは同期的に失敗します。

付与されたデバイス上のすべての対象となるエンドポイントには、単一の PartyEndpointMessageReceivedStateChange が指定され、すべての対象となるローカルエンドポイントには receiverEndpoints 配列が指定されます。

対象となるエンドポイントの配列がゼロエントリであると指定された場合、メッセージは現在ネットワークにあるすべてのリモートエンドポイントにブロードキャストされます。

発信者は、dataBuffers 配列で 1 つ以上の PartyDataBuffer 構造体を提供します。構造体が参照するメモリは連続している必要はないため、たとえば、固定のヘッダーバッファーと可変ペイロードを簡単に組み合わせることができます。バッファーは順番に組み立てられ、送信され、PartyEndpointMessageReceivedStateChange の中の 1 つの連続したデータブロックとして対象となるエンドポイントに配信されます。 Party ライブラリは、元の PartyDataBuffer セグメンテーションを記述するためにメタデータを送信する帯域幅を拡張しません。

既定では、呼び出し元の dataBuffers 配列に記述されたバッファーは、endMessage() が返される前に、割り当てられたバッファーにコピーされます。 PartySendMessageOptions::DontCopyDataBuffers を指定すると、この余計なコピー手順を回避し、代わりに、PartyDataBuffersReturnedStateChange によってメモリの所有権が発信者に返されるまで、各バッファーで指定されたメモリを有効かつ変更されないように維持することを発信者に要求します。 PartyDataBuffer 構造体自体は、SendMessage() 呼び出しが返された後も有効であり続ける必要はなく、参照するメモリのみが有効となります。

PartySendMessageOptions::DontCopyDataBuffers を使用する発信者は、発信者固有の messageIdentifier コンテキストを指定することができます。このポインターサイズの値は、すべての PartyDataBuffersReturnedStateChanges に含まれ、発信者が自分のプライベートメッセージのトラッキング情報に簡単にアクセスできるようになります。実際の値はあいまいなものとして扱われ、Party ライブラリでは解釈されず、リモートデモ送信されません。メッセージに関連した messageIdentifier の最終的に要求された状態変化が処理され、PartyManager::FinishProcessingStateChanges() を介して返されるまで、messageIdentifier が表す可能性のある独自のメモリが有効であり続けることを確認するのは、発信者の責任です。

接続品質や受信者の応答性などの要因により、すぐにターゲットエンドポイントにメッセージが送信されない場合があります。エンドポイントへの接続が現在サポートしていると推定される速度よりも高速で送信している場合、ローカル送信キューは拡大します。これにより、メモリ使用量が増加し、メッセージの待機時間が長くなる可能性があるため、発信者はローカル送信キューを監視し、管理することを強く推奨します。送信キューに関する情報は、 PartyLocalEndpoint::GetEndpointStatistics() を使用して取得できます。送信のサイズや頻度を減らしたり、queuingConfiguration オプション設定を使用して、長時間キューに入っているメッセージを自動的に期限切れにするタイムアウトを設定したり、PartyLocalEndpoint::CancelMessages() を使用してキューに入っている一部または全部のメッセージを明示的に削除したりすることで、送信キューを管理することができます。

このメソッドが成功を返した場合、メッセージの送信が開始されたか、将来の送信のためにキュー登録されたことを示します。特に、このメソッドが正常に返されても、メッセージがどの受信者にも正常に配信されたことを示すものではありません。現在、Party API では、個々のメッセージの配信や処理を追跡する方法は提供されていません。 PartyNetwork::GetNetworkStatistics() メソッドおよび GetEndpointStatistics() メソッドを使用して、ネットワーク全体または個々のローカルエンドポイントの統計情報をクエリすることができます。

options に PartySendMessageOptions::GuaranteedDelivery が含まれ対象のエンドポイントに転送するための透過型クラウドリレーサーバーに、メッセージが正常に配信されなかった場合は、PartyNetworkDestroyedStateChange が生成されます。言い換えると、配信要件が保証されたメッセージは、配信されるか、または送信クライアントがネットワークから切断されるかのどちらかになります。透過型クラウドリレーサーバーが、1 つ以上のターゲットエンドポイントを含む各リモートデバイスに配信保証メッセージを転送するときにメッセージが配信できなかった場合は、同様にリモートデバイスがネットワークから切断され、PartyNetworkDestroyedStateChange で示されます。言い換えると、配信要件が保証されたメッセージの受信に失敗したデバイスは、ネットワークから切断されます。

Party ライブラリは、環境でサポートされた最大サイズを超える大きなメッセージを自動的に断片化して再構成するので、発信者がこれを管理する必要はありません。ただし、断片化に関連してわずかなオーバーヘッドが発生します。より小さなメッセージを送信したり、大きな状態ペイロードを自然に効率的に分割することができる発信者は、そうすることを望む可能性があります。

SendMessage() が、ネットワークへの最初のユーザーの認証に成功する前にゼロ設定のエンドポイントの配列を使用して呼び出された場合、PartyEndpointCreatedStateChange 状態変更 (つまりネットワーク内に存在することがわかっている) 経由でリモートエンドポイントが報告されていない場合でも、メッセージはキューに入ります。最初のユーザーが正常に認証され、この送信用ローカルエンドポイントが正常に作成されると、キューに登録されたメッセージは、後でネットワークに存在するすべてのリモートエンドポイントを対象にします。この場合、ネットワークの将来の状態と最終的に受信が行われるエンドポイントのセットは SendMessage() では認識できないため、タイトルで、このような遅延ブロードキャストメッセージに配置されるコンテンツに注意するか、それらを全く送らないようにして、このローカルデバイスとエンドポイントがネットワークに完全に参加するまで待機してください。

要件

ヘッダー: Party.h

次の方法で共有

PartyLocalEndpoint::SendMessage

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

その他のリソース