Microsoft DirectX 8.0 (C++)

IDirectPlay8Peer::EnumHosts

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体が保持される。

任意の数の列挙を同時に実行できる。異なる複数の列挙への応答を区別するために、pvUserContext の値がメッセージ ハンドラに提供される。

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは dwEnumPerioddwRetryInterval、または dwTimeOut を指定してはならない。

デフォルトの列挙カウント値とタイムアウト値で、EnumHosts は適切な時間内に終了する。これらの値はサービス プロバイダによって設定され、IDirectPlay8Peer::GetSPCaps を呼び出して取得できる。非同期の列挙は、IDirectPlay8Peer::CancelAsyncOperation を呼び出すか、または dwFlags パラメータに pAsyncHandle パラメータに返されたハンドラを渡すか DPENUM_CANCEL フラグを設定すれば、いつでも停止できる。メッセージ ハンドラから S_OK 以外の値を返して、列挙を停止することもできる。

HRESULT EnumHosts(
PDPN_APPLICATION_DESC const pApplicationDesc,
IDirectPlay8Address *const pdpaddrHost,
IDirectPlay8Address *const pdpaddrDeviceInfo,
PVOID const pvUserEnumData,
const DWORD dwUserEnumDataSize,
const DWORD dwEnumCount,
const DWORD dwRetryInterval,
const DWORD dwTimeOut,
PVOID const pvUserContext,
HANDLE *const pAsyncHandle
const DWORD dwFlags,
);

パラメータ

pApplicationDesc
列挙するアプリケーションのホストを指定する DPN_APPLICATION_DESC 構造体へのポインタ。pApplicationDesc.dwSize メンバを適切な値に設定しなければならない。応答の数を減らすには、pApplicationDesc.guidApplication に検索するアプリケーションの GUID を設定する。このメンバが設定されていない場合、すべてのアプリケーションが検索対象になる。
pdpaddrHost
アプリケーションをホストしているコンピュータのアドレスを指定する IDirectPlay8Address オブジェクトへのポインタ。NULL を指定すると、DirectPlay がアドレスを作成する。デフォルトでは、DirectPlay は pdpaddrDeviceInfo パラメータからアドレスを作成する。dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、ユーザーにアドレス情報を問い合わせることができる。
pdpaddrDeviceInfo
列挙に使用するサービス プロバイダおよびローカル デバイスの設定を指定する IDirectPlay8Address オブジェクトへのポインタ。
pvUserEnumData
列挙要求からホストに送信されるデータ ブロックへのポインタ。データのサイズは、ネットワークの種類によって制限される。正確な値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。
dwUserEnumDataSize
pvUserEnumData パラメータで示すデータのサイズを指定する DWORD 型の変数。
dwEnumCount
列挙データを送信する回数を指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwEnumCount のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。dwEnumCount に INFINITE が指定された場合、列挙は取り消されるまで続行される。
dwRetryInterval
列挙の再試行の間隔をミリ秒単位で指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwRetryInterval のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。
dwTimeOut
最後の列挙が送信された後、DirectPlay が応答を待つ時間 (ミリ秒) を指定する、DWORD 型の変数。デフォルト値を使用するには、このパラメータを 0 に設定する。dwTimeOut のデフォルト値を取得するには、IDirectPlay8Peer::GetSPCaps を呼び出す。INFINITE が指定された場合、列挙は取り消されるまで続行される。
pvUserContext
列挙への応答と共に呼び出された場合に、ピアのメッセージ ハンドラに提供されるコンテキスト。同時実行されている列挙の応答を区別する場合に役立つ。
pAsyncHandle
DPNHANDLE。メソッドが値を返すと、phAsyncHandle は、IDirectPlay8Peer::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNENUMHOSTS_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
dwFlags
次のフラグを設定できる。
DPNENUMHOSTS_SYNC
メソッドを同期をとりながら処理する。
DPNENUMHOSTS_OKTOQUERYFORADDRESSING
このフラグを設定すると、DirectPlay® の標準のダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
DPNENUMHOSTS_NOBROADCASTFALLBACK
サービス プロバイダがある要素を全要素にコピーすることをサポートしている場合、このフラグを設定するとある要素を全要素にコピーする機能が無効になる。このフラグを設定する前に DPN_SP_CAPS 構造体を調べ、ある要素を全要素にコピーすることがサポートされているかどうかを確認すること。

戻り値

メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。デフォルトでは、このメソッドは非同期に実行され、通常の場合、DPNSUCCESS_PENDING を返す。また、次のいずれかのエラー値を返す場合もある。

DPNERR_INVALIDDEVICEADDRESS
DPNERR_INVALIDFLAGS
DPNERR_INVALIDHOSTADDRESS
DPNERR_INVALIDPARAM
DPNERR_ENUMQUERYTOOLARGE

注意

dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。

動作環境

  Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
  Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
  ヘッダー : Dplay8.h で宣言。