IDirectPlay8Server::SendTo メソッド

  • [アーティクル]

IDirectPlay8Server::SendTo メソッド

セッション内のクライアントまたはグループにデータを送信する。メッセージは同期または非同期で送信できる。

構文

HRESULT SendTo(      
    const DPNID dpnid,
    const DPN_BUFFER_DESC *const pBufferDesc,
    const DWORD cBufferDesc,
    const DWORD dwTimeOut,
    void *const pvAsyncContext,
    DPNHANDLE *const phAsyncHandle,
    const DWORD dwFlags
);

パラメータ

  • dpnid
    [in] データを受信するクライアントまたはグループの識別子。セッション内のすべてのプレーヤにメッセージを送信する場合は、このパラメータを DPNID_ALL_PLAYERS_GROUP に設定する。
  • pBufferDesc
    [in] 送信するデータを記述する DPN_BUFFER_DESC 構造体へのポインタ。
  • cBufferDesc
    [in] pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 8 個まで使える。
  • dwTimeOut
    [in] メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信キューから削除される。このパラメータを 0 に設定すると、メッセージは、送信されるかリンクが切断されるまで、送信キューに残る。
  • pvAsyncContext
    [in] ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。
  • phAsyncHandle
    [out] DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Server::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
  • dwFlags
    [in] 送信動作を記述するフラグ。次の 1 つあるいは複数のフラグを設定できる。
    • DPNSEND_SYNC
      非同期 IDirectPlay8Server::SendTo 要求を取り消す。
    • DPNSEND_NOCOPY
      DPN_BUFFER_DESC 構造体のデータを使い、内部コピーは行わない。データを送信する方法としてはより効率的な場合がある。しかし、DPN_MSGID_SEND_COMPLETE メッセージを受信するまでにデータの変更や削除を行うと、間違ったデータを送信することがあるため、堅牢ではなくなる。このフラグを DPNSEND_NOCOMPLETE と共に使うことはできない。
    • DPNSEND_NOCOMPLETE
      メッセージ ハンドラに DPN_MSGID_SEND_COMPLETE 構造体を送信しない。このフラグを DPNSEND_NOCOPY または DPNSEND_GUARANTEED と共に使うことはできない。また、このフラグを使う場合、pvAsyncContext は NULL でなければならない。
    • DPNSEND_COMPLETEONPROCESS
      メッセージがターゲットに配信され、メッセージの受信を示すターゲットのメッセージ ハンドラが返されるとき、DPN_MSGID_SEND_COMPLETE をメッセージ ハンドラに送信する。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下することがある。このフラグを設定する場合は、DPNSEND_GUARANTEED も設定する必要がある。
    • DPNSEND_GUARANTEED
      保証された配信方法により、メッセージを送信する。
    • DPNSEND_PRIORITY_HIGH
      メッセージの優先順位を高く設定する。このフラグは、DPNSEND_PRIORITY_LOW と共に使うことはできない。
    • DPNSEND_PRIORITY_LOW
      メッセージの優先順位を低く設定する。このフラグは、DPNSEND_PRIORITY_HIGH と共に使うことはできない。
    • DPNSEND_NOLOOPBACK
      ローカル プレーヤを含むグループに送信しているときに、メッセージ ハンドラへの DPN_MSGID_RECEIVE システム メッセージを抑制する。たとえば、セッション全体にある要素を全要素にコピーする場合は、このフラグが便利である。
    • DPNSEND_NONSEQUENTIAL
      このフラグが設定された場合、ターゲット アプリケーションは、ユーザーのコンピュータに到着した順にメッセージを受け取る。このフラグが設定されていない場合、メッセージはシーケンシャルに配信され、ターゲット アプリケーションは送信された順にメッセージを受け取る。したがって、着信したメッセージを、欠落しているメッセージが到着するまでバッファに格納する場合がある。
    • DPNSEND_COALESCE
      DirectPlay がパケットを組み合わせて送信できるようにする。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。

DPNERR_CONNECTIONLOST データの送信中にサービス プロバイダ接続がリセットされた。
DPNERR_INVALIDFLAGS このメソッドに渡されたフラグは無効である。
DPNERR_INVALIDPARAM メソッドに渡された 1 つあるいは複数のパラメータが無効である。
DPNERR_INVALIDPLAYER プレーヤ ID が、このゲーム セッションに対する有効なプレーヤ ID として認識されていない。
DPNERR_TIMEDOUT 時間切れのため、処理が完了できなかった。

注意

このメソッドは、受信側のメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データは、関連付けられている構造体の pReceiveData メンバに保持されている。

メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。メッセージに低い優先順位または高い優先順位を指定するには dwFlags に該当するフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。

IDirectPlay8Server::SendTo 要求が完了すると、送信側のメッセージ ハンドラに DPN_MSGID_SEND_COMPLETE システム メッセージが送信される。要求の成功または失敗は、関連付けられた構造体の hResultCode メンバに保持される。dwFlags に DPNSEND_NOCOMPLETE フラグを設定すると、送信完了のシステム メッセージは送信されない。

通常、メッセージが送信されると直ちに、送信完了が送信元のコンピュータに送信される。言い換えると、送信完了は、メッセージがターゲット上で処理されたことを必ずしも意味しない。メッセージはまだキュー内にある可能性もある。メッセージがターゲットで処理されたことを確認するには、dwFlags にDPNSEND_COMPLETEONPROCESS フラグを設定する。このフラグを設定すると、ターゲットのメッセージ ハンドラがメッセージを処理して戻るまで、送信完了は送信されない。

DPNSEND_COALESCE フラグが dwFlags に設定されると、DirectPlay はキューで待機している 32 個までのパケットを、流出するフレームに結合しようとする。DPNSEND_COALESCE フラグが設定されている場合でも、DirectPlay は結合を保証しない。キューに複数のメッセージがあり、受信するプレーヤが Microsoft DirectX® 9.0 以降を実行している場合にのみ、パケットは結合される。音声パケットはすべて結合できる。保証付きおよび保証なしのパケットは両方とも同じフレームに結合される。フレームが宛先に届く前に削除されると、フレームの保証付き部分のみ再送され、他のデータはフレームに結合されない。

注  メソッドが戻るまでは、データ バッファなどのリソースが有効な状態のままであると見なしてはならない。このメソッドを非同期に呼び出す場合、呼び出しが戻る前に DPN_MSGID_SEND_COMPLETE メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。