Platform SDK: DirectX

IDirectPlay4::Receive

IDirectPlay4::Receive メソッドは、メッセージ キューからメッセージを取得する。

HRESULT Receive(
  LPDPID lpidFrom,
  LPDPID lpidTo,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

パラメータ

lpidFrom
送信側プレーヤーの ID を受け取る変数のアドレス。DPRECEIVE_FROMPLAYER フラグを指定する場合、この変数は、このメソッドを呼び出す前にプレーヤー ID により初期化する必要がある。
lpidTo
受信側プレーヤーの ID を受け取る変数のアドレス。DPRECEIVE_TOPLAYER フラグを指定する場合、この変数は、このメソッドを呼び出す前にプレーヤー ID により初期化する必要がある。
dwFlags
次のコントロール フラグのいずれかまたはいくつかを設定できる。デフォルト (dwFlags = 0) では、最初の使用可能なメッセージが取得される。
DPRECEIVE_ALL
最初の使用可能なメッセージを返す。これがデフォルトである。
DPRECEIVE_PEEK
ほかのフラグにより指定されたようにメッセージを返すが、それをメッセージ キューから削除しない。このフラグは、lpData が NULL の場合に指定する必要がある。
DPRECEIVE_TOPLAYER および DPRECEIVE_FROMPLAYER
DPRECEIVE_TOPLAYER と DPRECEIVE_FROMPLAYER を両方とも指定した場合、Receive は 1) lpidTo により指定されたプレーヤーに送信されたメッセージと、2) lpidFrom により指定されたプレーヤーから送信されたメッセージのみを返す。ただし、これら両方の条件が満たされなければならない。

DPRECEIVE_TOPLAYER lpidTo により指定されたプレーヤーに送信されたメッセージのみを返す。

DPRECEIVE_FROMPLAYER のみを指定した場合、ReceivelpidFrom により指定されたプレーヤーから送信されたメッセージのみを返す。

DPRECEIVE_TOPLAYER も DPRECEIVE_FROMPLAYER も設定しない場合、Receive は最初に使用可能なメッセージを返す。

lpData
メッセージ データを書き込むバッファへのポインタ。データのサイズのみを要求するときは、このパラメータに NULL を設定する。lpdwDataSize パラメータはデータを保持するのに必要なサイズに設定される。プレーヤー ID が DPID_SYSMSGのプレーヤーからメッセージが送信されている場合、アプリケーションは lpDataDPMSG_GENERIC に設定し、dwType メンバを調べてシステム メッセージのタイプを調べてからそれを処理する。
lpdwDataSize
このメソッドを呼び出す前に、バッファのサイズに初期化された DWORD へのポインタ。メソッドが戻ると、このパラメータにはバッファにコピーされたバイト数が設定されている。バッファが小さすぎる場合 (DPERR_BUFFERTOOSMALL)、このパラメータには必要なバッファのサイズが設定される。

戻り値

成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOMESSAGES

注意

DPID_SYSMSG として定義されたプレーヤー ID から受信したメッセージは、セッションでアプリケーションに変更を通知するときに使用するシステム メッセージである。これらの場合、システム メッセージの lpDataDPMSG_GENERIC に設定し、dwType メンバを調べて何に固有のシステム メッセージかを調べる。

DPID_ALLPLAYERS として定義されたプレーヤー ID、またはグループ ID に送信されたメッセージは、送信元のプレーヤー ID から取得したかのように表示される。アプリケーションは、ローカル プレーヤーに送信されたメッセージのみを受信する。プレーヤーは、lpidFromlpidTo がポイントしている値が同じであるメッセージは受信できない。

セッション記述で DPSESSION_NOMESSAGEID を指定した場合、lpidFrom は必ず 0xFFFFFFFF となり、また lpidTo 値は任意となる。

DirectPlay に搭載されているサービス プロバイダはすべて、データを破損から守るために整合性チェックを行なう。Receive を使用して取得したメッセージは、破損していないと保証されている。

必要条件

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

参照

DPMSG_GENERICIDirectPlay4::Send