Platform SDK: DirectX

DirectPlay4.SendEx

DirectPlay4.SendEx メソッドは、ほかのプレーヤー、プレーヤーのグループ、またはセッション内のすべてのプレーヤーにメッセージを送信する。SendEx は、DirectPlay4.Send メソッドの強化版であり、より多くのオプションを利用できる。SendEx は、保証付きおよび保証なしの両方のメッセージをサポートする。また、非同期メッセージの送信と、メッセージの優先順位およびタイムアウトの設定を可能にする。

object.SendEx(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage, _
    priority As Long, _
    timeOut As Long, _
    context As Long) As Long

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
fromPlayerId
送信側のプレーヤーの ID。このプレーヤー ID は、このメッセージを発信したコンピュータ上のローカル プレーヤーのいずれかに一致していなければならない。
toPlayerId
メッセージの送信先の ID。メッセージをほかのプレーヤーに送信するには、そのプレーヤーの ID を設定する。メッセージをグループ内のすべてのプレーヤーに送信するには、そのグループの ID を指定する。メッセージをセッション内のすべてのプレーヤーに送信するには、定数 DPID_ALLPLAYERS を使用する。メッセージをサーバー プレーヤーに送信するには、定数 DPID_SERVERPLAYER を指定する。プレーヤーは、自らにメッセージを送信することはできない。
flags
メッセージの送信方法を指定する、CONST_DPSENDFLAGS 列挙型のフラグ。デフォルト (flags = 0) では、メッセージは保証なしで送信される。
DPSEND_ASYNC
メッセージを非同期で送信する。メソッドは直ちに戻る。このフラグを指定しない場合、メソッドは、メッセージが送信されるまで (および、保証付きで送信される場合は、送信が確認されるまで) 戻らない。送信が完了すると、DPSYS_SENDCOMPLETE システム メッセージが送信される。

このフラグを使用すると、メッセージが送信キューに配置された場合は、戻り値が DPERR_PENDING になる。これは致命的なエラーではなく、メッセージが送信されなかったことを直ちに伝えるだけである。

DPSEND_ENCRYPTED
メッセージを暗号化して送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
DPSEND_GUARANTEED
利用可能であれば、保証された配信方法を使用してメッセージを送信する。
DPSEND_NOSENDCOMPLETEMSG
このフラグを設定すると、完了メッセージは送信されない。このフラグは、DPSEND_ASYNC も設定されている場合に限り、使用できる。
DPSEND_SIGNED
デジタル署名付きでメッセージを送信する。これができるのは、保証セッションの場合だけである。このフラグは、DPSEND_GUARANTEED フラグも設定されている場合に限り、使用できる。メッセージは、DPSYS_SECUREMESSAGE システム メッセージとして送信される。
msg
送信するデータを表す DirectPlayMessage オブジェクト。このオブジェクトは、DirectPlay4.CreateMessage メソッドを使用して取得される。このオブジェクト自体のメソッドを使用して、オブジェクトにデータを代入することができる。
priority
メッセージの優先順位を、0 〜 65535 の範囲で指定する。0 は、最も優先順位が低い。番号が大きくなるほど、優先順位は高い。優先順位の設定されたメッセージは、キュー内にそのメッセージよりも優先順位の高いメッセージがなくなってから、送信される。

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

timeOut
アプリケーションで提供されるオプションのタイムアウト。メッセージを送信する時間制限を、ミリ秒単位で指定する。この時間内にメッセージを送信できなかった場合、メッセージは自動的にキャンセルされる。0 を指定すると、タイムアウトは使用されない。

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

context
送信が完了したときに、完了メッセージの一部としてアプリケーションに返される、アプリケーション定義のコンテキスト。0 に設定することもできる。

戻り値

DirectPlay によって生成された、メッセージに対する ID を返す。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

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

注意

このメソッドは、保証付きのメッセージと保証なしのメッセージをサポートする。保証付きで送信されるメッセージは、受信側に認識されるのを待機している保留中のメッセージが存在する場合に、ブロックしない。

メッセージを非同期で送信すると、メッセージは送信キューに入れられ、SendEx メソッドは直ちに戻る。送信の結果を示すために、システム メッセージが送信側のプレーヤーの受信キューに入れられる。

メッセージに優先順位を設定することができる。メッセージは、そのメッセージよりも優先順位の高いメッセージが送信を待機しておらず、十分な帯域幅が利用可能な場合に、送信される。

メッセージにタイムアウトを設定することができる。DirectPlay が指定された時間内にメッセージを配信できない場合、メッセージはキャンセルされる。

セッション記述でフラグが設定されているために、保証メッセージの配信の順番が確保されていない場合は、DPSEND_SIGNED フラグと DPSEND_ENCRYPTED フラグを使用することはできない。

異なる優先順位を使用してメッセージを送信すると、署名と暗号化はうまくいかない場合がある。アプリケーションでは、安全なメッセージのための優先順位レベルを 1 つ決め、そのレベルでのみセキュリティ フラグを使用すべきである。これは、安全なメッセージの確認は受信された順序に基づいていて、優先順位によってこの順序が変更される可能性があるからである。

DirectPlay プロトコルがアクティブであると、外向きのネットワーク トラフィックをスロットリングしようとする。つまり、パケットを常に可能な限り速く送信するわけではないということである。DirectPlay プロトコルは、受信側のコンピュータの内向きの帯域幅に影響を与えない範囲で、可能な限り高速にパケットを送信する。

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

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

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

参照

DirectPlay4.SendDirectPlay4.CancelMessageDirectPlay4.CancelPriority