Microsoft DirectX 8.0 (C++)

IDirectPlay8Peer::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
データを受信するピアまたはグループの識別子。セッション内のすべてのプレーヤーにメッセージを送信する場合は、このパラメータを DPNID_ALL_PLAYERS_GROUP に設定する。
pBufferDesc
送信するデータを保持する DPN_BUFFER_DESC 構造体へのポインタ。
cBufferDesc
pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 1 つでなければならない。
dwTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
pvAsyncContext
ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。このパラメータはオプションであり、NULL に設定できる。
phAsyncHandle
DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
送信動作を記述するフラグ。次の 1 つ以上のフラグを設定することができる。
DPNSEND_SYNC
SendTo 要求を同期をとりながら処理する。
DPNSEND_NOCOPY
DPN_BUFFER_DESC 構造体のデータを使用し、内部コピーは行わない。これは、効率的なデータ送信の方法である。しかし、受信側がメッセージを処理する前に、送信側がメッセージを変更できるため、堅牢ではなくなる。このフラグを 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_NONSEQUENTIAL
このフラグが設定された場合、ターゲット アプリケーションは、ユーザーのコンピュータに到着した順にメッセージを受け取る。このフラグが設定されていない場合、メッセージはシーケンシャルに配信され、ターゲット アプリケーションは送信された順にメッセージを受け取る。したがって、着信したメッセージを、欠落しているメッセージが到着するまでバッファに格納する場合がある。
DPNSEND_NOLOOPBACK
ローカル プレーヤーを含むグループに送信しているときに、メッセージ ハンドラへの DPN_MSGID_RECEIVE システム メッセージを抑制する。たとえば、セッション全体にある要素を全要素にコピーする場合は、このフラグが便利である。

戻り値

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

DPNERR_CONNECTIONLOST
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_INVALIDPLAYER
DPNERR_TIMEDOUT

注意

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

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

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

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

アプリケーションは IDirectPlay8ClientIDirectPlay8Server、または IDirectPlay8PeerClose を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。

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

動作環境

  Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
  Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
  ヘッダー : Dplay8.h で宣言。