Platform SDK: DirectX

IDirectPlay4::SendEx

IDirectPlay4::SendEx メソッドは、メッセージをセッション内の別のプレーヤー、プレーヤーのグループ、またはすべてのプレーヤーに送信する。SendEx は、Send メソッドを強化したものであり、使用可能なオプションも多い。SendEx では、保証付きメッセージと保証なしメッセージの両方をサポートしている。また、非同期メッセージを送信したり、メッセージの優先順位やタイムアウトを設定することもできる。

HRESULT SendEx(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwPriority,
  DWORD dwTimeout,
  LPVOID lpContext,
  LPDWORD lpdwMsgID
);

パラメータ

idFrom
送信側プレーヤーの ID。プレーヤー ID は、メッセージの送信元コンピュータのローカル プレーヤーのいずかに対応していなければならない。
idTo
メッセージの送信先 ID。メッセージを別のプレーヤーに送信するには、プレーヤーの ID を指定する。メッセージをグループ内のすべてのプレーヤーに送信するには、グループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数記号の DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数記号の DPID_SERVERPLAYER を指定する。プレーヤーが自分にメッセージを送信することはできない。
dwFlags
メッセージの送信方法を指定する。デフォルト (dwFlags = 0) では、メッセージは保証なしで送信される。
DPSEND_ASYNC
メッセージを非同期に送信する。関数はすぐに戻り、lpdwMsgID パラメータには値が設定されている。このフラグを指定しない場合、メッセージが送信される (保証付きで送信されている場合は、肯定応答を受け取る) まで関数は戻らない。送信が完了すると、DPMSG_SENDCOMPLETE システム メッセージが送られる。

このフラグを使用した場合、メッセージが送信キューに設定されたときは、戻り値が DPERR_PENDING となる。これは、致命的なエラーではなく、メッセージがすぐに送信されなかったことをユーザーにただ知らせるための戻り値である。

DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これは、セキュア セッションでのみ行われる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
保証付き配信方式が使用可能な場合、それによりメッセージを送信する。
DPSEND_NOSENDCOMPLETEMSG
このフラグを設定した場合、未完了メッセージが送信される。このフラグは、DPSEND_ASYNC フラグも設定されている場合にのみ使用できる。
DPSEND_SIGNED
デジタル署名を使用してメッセージを送信する。これは、セキュア セッションでのみ行うことができる。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合にのみ使用できる。メッセージは、DPMSG_SECUREMESSAGE システム メッセージとして送信される。
lpData
送信するデータへのポインタ。
dwDataSize
送信するデータの長さ。
dwPriority
メッセージの優先順位で、範囲は 0〜65535 である。0 が最低の優先順位のメッセージとなる。値が大きければ大きいほど、メッセージの優先順位は高くなる。キューの中に、ここで指定した優先順位より高い優先順位のメッセージがない場合にのみ、そのメッセージが送信される。

メモ  すべてのサービス プロバイダでこのオプションがサポートされているとは限らない。これがサポートされていない場合、0 以外の優先順位を指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判定するには、GetCaps を呼び出す。

dwTimeout
メッセージ配信時の時間制限をアプリケーションがオプションで指定するタイムアウト (ミリ秒単位)。この時間内にメッセージを配信できない場合、そのメッセージは自動的に取り消されて、DPMSG_SENDCOMPLETE メッセージが送信される。0 は、タイムアウトを使用することを示す。

メモ  すべてのサービス プロバイダでこのオプションがサポートされているとは限らない。サポートされていない場合、0 以外のタイムアウトを指定すると、DPERR_UNSUPPORTED エラーが返される。このオプションがサポートされているかどうかを判定するには、GetCaps を呼び出す。

lpContext
アプリケーションにより定義されたコンテキストで、送信が完了したときに完了メッセージの一部としてアプリケーションに返されるもの。NULL も設定できる。
lpdwMsgID
DirectPlay によりメッセージ用に生成された ID が設定される DWORD へのポインタ。この ID は、メッセージのステータスを調べたり、それを取り消すときに使用する。メッセージ ID が必要ない場合は、NULL を指定する。このパラメータは、非同期メッセージの場合にのみ返される。

戻り値

同期メッセージの場合は、処理が成功すると DP_OK を返す。非同期メッセージの場合は、送信処理でメッセージをキューに設定できると DPERR_PENDING を返す。ユーザーは、DPMSG_SENDCOMPLETE メッセージから完了情報を取得する。それ以外の場合は、次のエラー値のいずれかかを返す。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

保証付きとして指定されていないメッセージに暗号化フラグや署名付きフラグが指定された場合、または非同期でないメッセージに DPSEND_NOCOMPLETEMSG フラグが指定された場合は、DPERR_INVALIDPARAMS を返す。優先順位が 0〜65535 の範囲内にない場合は、DPERR_INVALIDPRIORITY を返す。0 以外の優先順位が指定された場合にサービス プロバイダが優先順位をサポートしていないとき、または 0 以外のタイムアウトが指定された場合にサービス プロバイダがこのオプションをサポートしていないときは、DPERR_NOTSUPPORTED を返す。

注意

DirectPlay プロトコルがセッション記述に指定されている (DPSESSIONDESC2 構造体の DPSESSION_DIRECTPLAYPROTOCOL フラグを設定することにより) 場合、SendEx のすべてのオプションを使用できる。それ以外の場合、アプリケーションは GetCaps を呼び出してサービス プロバイダで実装されているオプションを判定する必要がある。SendEx は、保証付きメッセージと保証なしメッセージの両方をサポートしている。保証付きで送信されたメッセージは、受信側からの肯定応答を待っているペンディング状態のメッセージがあってもブロックされない。

メッセージが非同期に送信された (DPSEND_ASYNC フラグを設定することにより) 場合、そのメッセージは送信キューに設定されて、SendEx 関数はすぐに戻る。システム メッセージ (DPMSG_SENDCOMPLETE) が送信側プレーヤーの受信キューに設定され、それにより送信結果が示される。

メッセージに優先順位を設定できる。メッセージは、送信されるのを待機しているメッセージの中に、それよりも優先順位が高いメッセージがなく、また使用可能な帯域幅がある場合に送信される。

メッセージのタイムアウトを指定できる。DirectPlay が指定された時間内にメッセージを配信できなかった場合、それは取り消される。

DPSESSION_NOPRESERVEORDER フラグがセッション記述 (DPSESSIONDESC2) に設定されているために、保証付きメッセージの配布順序が保持されない場合、DPSEND_SIGNED フラグや DPSEND_ENCRYPTED フラグを使用することはできない。

さまざまな優先順位を指定してメッセージを送信した場合は、署名や暗号が機能しない。アプリケーションでは、機密保護メッセージの優先順位を 1 つに決定し、またその優先順位でのみセキュリティ フラグを使用するとよい。これは、機密保護メッセージの検証がその受信順序に基づいて行われ、また優先順位を設定するとその順序が変更される可能性があるためである。

DirectPlay プロトコルは、アクティブな場合、送信方向のネットワーク トラフィックを抑制しようとする。つまり、必ずしもできる限り速くパケットを送信するわけではない。それは、受信側コンピュータの受信方向の帯域幅に影響を与えない範囲でできる限り速くパケットを送信する。

サービス プロバイダが保証付きメッセージをサポートしてるかどうかに関係なく、また DirectPlay プロトコル フラグを設定しているかどうかに関係なく、システム メッセージは常に保証付きで送信される。保証付きシステム メッセージを送信すると、DirectPlay プロトコルが自動的に使用される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定して、メッセージを保証付きで送信した (DPSEND_GUARANTEED フラグを設定することにより) 場合、サービス プロバイダが保証付きメッセージをサポートしているかどうかに関係なく、そのメッセージは保証付きで送信される。

システム メッセージ以外で、アプリケーションが DirectPlay プロトコル フラグを設定しないで、メッセージを保証付きで送信した場合、そのメッセージは、サービス プロバイダが保証付きメッセージをサポートしているときのみ保証付きで送信される。サービス プロバイダがそれをサポートしていない場合、DPSEND_GUARANTEED フラグに関係なく、メッセージは保証付きで送信されない。

必要条件

  Windows NT/2000 : Windows 2000 が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dplay.h で宣言。
  インポート ライブラリ : dplayx.lib を使用。

参照

IDirectPlay4::SendIDirectPlay4::CancelMessageIDirectPlay4::CancelPriorityIDirectPlay4::GetMessageQueueDPMSG_SENDCOMPLETE