IDirectPlay8Peer::SendTo メソッド
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
[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 メンバに返される。このパラメータはオプションであり、NULL に設定できる。 - phAsyncHandle
[out] DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNSEND_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。 - dwFlags
[in] 送信動作を記述するフラグ。次の 1 つ以上のフラグを設定できる。DPNSEND_SYNC
非同期 IDirectPlay8Peer::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_NONSEQUENTIAL
このフラグが設定された場合、ターゲット アプリケーションは、ユーザーのコンピュータに到着した順にメッセージを受け取る。このフラグが設定されていない場合、メッセージはシーケンシャルに配信され、ターゲット アプリケーションは送信された順にメッセージを受け取る。したがって、着信したメッセージを、欠落しているメッセージが到着するまでバッファに格納する場合がある。DPNSEND_NOLOOPBACK
ローカル プレーヤを含むグループに送信しているときに、メッセージ ハンドラへの DPN_MSGID_RECEIVE システム メッセージを抑制する。たとえば、セッション全体にある要素を全要素にコピーする場合は、このフラグが便利である。DPNSEND_COALESCE
DirectPlay がパケットを組み合わせて送信できるようにする。
戻り値
メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。
| DPNERR_CONNECTIONLOST | データの送信中にサービス プロバイダ接続がリセットされた。 |
| DPNERR_GENERIC | 定義されていないエラー条件が発生した。 |
| DPNERR_INVALIDFLAGS | このメソッドに渡されたフラグは無効である。 |
| DPNERR_INVALIDPARAM | メソッドに渡された 1 つ以上のパラメータが無効である。 |
| DPNERR_INVALIDPLAYER | プレーヤ ID が、このゲーム セッションに対する有効なプレーヤ ID として認識されていない。 |
| DPNERR_TIMEDOUT | 時間切れのため、処理が完了できなかった。 |
注意
このメソッドは、受信側のメッセージ ハンドラに DPN_MSGID_RECEIVE システム メッセージを生成する。データ バッファは、関連付けられている構造体の pReceiveData メンバに保持されている。
メッセージには、低、通常、高の 3 つの優先順位のいずれかを設定できる。メッセージに低い優先順位または高い優先順位を指定するには dwFlags に適切なフラグを設定する。どちらの優先順位フラグも設定しなかった場合、メッセージは通常の優先順位になる。送信優先順位の詳細については、「ネットワーキングの基本」を参照すること。
IDirectPlay8Peer::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 メッセージを受け取り、メッセージ ハンドラが処理してしまうことがある。メッセージ ハンドラがデータ バッファなどのリソースを割り当て解除、または無効にした場合、メソッドが呼び出された後でリソースが無効になることがある。
送信側コンピュータは他のプレーヤが接続されていないホストであり、DPNSEND_SYNC フラグと DPNSEND_NOLOOPBACK フラグが設定されている場合、このメソッドは DPNERR_GENERIC エラー値を返す。