IDirectPlay8Client::Send
データをサーバーに転送する。メッセージは同期または非同期で送信することができる。
HRESULT Send(
const DPN_BUFFER_DESC *const pBufferDesc,
const DWORD cBufferDesc,
const DWORD dwTimeOut,
void *const pvAsyncContext,
DPNHANDLE *const phAsyncHandle,
const DWORD dwFlags
);
パラメータ
- pBufferDesc
- 送信するデータを記述する DPN_BUFFER_DESC 構造体へのポインタ。
- cBufferDesc
- pBufferDesc が示す DPN_BUFFER_DESC 構造体の数。このバージョンの Microsoft® DirectPlay® では、バッファは 1 つでなければならない。
- dwTimeOut
- メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが dwTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
- pvAsyncContext
- ユーザー指定のコンテキストへのポインタ。これは、DPN_MSGID_SEND_COMPLETE システム メッセージの pvUserContext メンバに返される。
- phAsyncHandle
- DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Client::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
- dwFlags
- 送信動作を記述するフラグ。次の 1 つ以上のフラグを設定することができる。
- DPNSEND_SYNC
- Send 要求を同期をとりながら処理する。
- 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_NOLOOPBACK
- 自分に送信する場合、メッセージ ハンドラにDPN_MSGID_RECEIVE システム メッセージを送信しない。
- DPNSEND_NONSEQUENTIAL
- このフラグを設定しない場合、メッセージは送信順にターゲット アプリケーションに配信される。したがって、順序どおりでないメッセージは、欠落しているメッセージが到着するまでバッファに格納する必要がある。このフラグを設定すると、メッセージは受信順にターゲット アプリケーションに配信される。
戻り値
メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。
注意
このメソッドは、サーバーのメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データ バッファは、関連付けられている構造体の pReceiveData メンバに保持されている。
メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。dwFlags メッセージに低い優先順位または高い優先順位を指定するには dwFlags に適切なフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。
Send 要求が完了すると、送信側のメッセージ ハンドラに DPN_MSGID_SEND_COMPLETE システム メッセージが送信される。要求の成功または失敗は、関連付けられた構造体の hResultCode メンバに保持される。dwflags に DPN_NOCOMPLETE フラグを設定すると、送信完了のシステム メッセージは送信されない。
通常、メッセージが送信されると直ちに、送信完了が送信元のコンピュータに送信される。言い換えると、送信完了は、メッセージがターゲット上で処理されたことを必ずしも意味しない。メッセージはまだキュー内にある可能性もある。メッセージがターゲットで処理されたことを確認するには、dwFlags にDPN_COMPLETEONPROCESS フラグを設定する。このフラグを設定すると、ターゲットのメッセージ ハンドラがメッセージを処理して戻るまで、送信完了は送信されない。
アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。
注 メソッドが戻るまでは、データ バッファなどのリソースが有効な状態のままであると見なしてはならない。このメソッドを非同期に呼び出す場合、呼び出しが戻る前に DPN_MSGID_SEND_COMPLETE メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。
Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。