IDirectPlay8Client::EnumHosts
Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体が保持される。
任意の数の列挙を同時に実行できる。異なる複数の列挙への応答を区別するために、pvUserContext の値がメッセージ ハンドラに提供される。
列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは dwEnumPeriod、dwRetryInterval、または dwTimeOut を指定しないことを推奨する。
デフォルトの列挙カウント値とタイムアウト値で、EnumHosts は適切な時間内に終了する。これらの値はサービス プロバイダによって設定され、IDirectPlay8Client::GetSPCaps を呼び出して取得できる。非同期の列挙は、IDirectPlay8Client::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
- 列挙要求からホストに送信されるデータ ブロックへのポインタ。データのサイズは、ネットワークのタイプによって制限される。IDirectPlay8Client::GetSPCaps を呼び出して正確な値を取得する。
- dwUserEnumDataSize
- pvUserEnumData パラメータで示すデータのサイズを指定する DWORD 型の変数。
- dwEnumCount
- 列挙データを送信する回数を指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwEnumCount のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。dwEnumCount に INFINITE が指定された場合、列挙は取り消されるまで続行される。
- dwRetryInterval
- 列挙の再試行の間隔をミリ秒単位で指定する値。デフォルト値を使用するには、このパラメータを 0 に設定する。dwRetryInterval のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。
- dwTimeOut
- 最後の列挙が送信された後、DirectPlay が応答を待つ時間 (ミリ秒) を指定する、DWORD 型の変数。デフォルト値を使用するには、このパラメータを 0 に設定する。dwTimeOut のデフォルト値を取得するには、IDirectPlay8Client::GetSPCaps を呼び出す。INFINITE が指定された場合、列挙は取り消されるまで続行される。
- pvUserContext
- 列挙への応答と共に呼び出された場合に、クライアントのメッセージ ハンドラに提供されるコンテキスト。同時実行されている列挙の応答を区別する場合に役立つ。
- pAsyncHandle
- DPNHANDLE。メソッドが戻ると、phAsyncHandle は、IDirectPlay8Client::CancelAsyncOperation に渡して処理を取り消すことができるハンドルをポイントする。dwFlags に DPNENUMHOSTS_SYNC フラグが設定されている場合、このパラメータは NULL に設定しなければならない。
- dwFlags
- 次のフラグを設定できる。
- DPNENUMHOSTS_SYNC
- メソッドを同期をとりながら処理する。
- DPNENUMHOSTS_OKTOQUERYFORADDRESSING
- このフラグを設定すると、DirectPlay の標準ダイアログ ボックスが表示される。十分な情報がこのメソッドに渡されていない場合は、詳細について問い合わされる。
- DPNENUMHOSTS_NOBROADCASTFALLBACK
- サービス プロバイダがある要素を全要素にコピーすることをサポートしている場合、このフラグを設定するとある要素を全要素にコピーする機能が無効になる。このフラグを設定する前に DPN_SP_CAPS 構造体を調べ、ある要素を全要素にコピーすることがサポートされているかどうかを確認すること。
戻り値
メソッドが同期をとりながら処理され、処理が成功した場合は S_OK を返す。要求が非同期で処理される場合、メソッドが直ちに処理されると、S_OK を返す場合がある。デフォルトでは、このメソッドは非同期に実行され、通常は DPNSUCCESS_PENDING か、または次のいずれかのエラー値を返す。
注意
dwFlags に DPNENUMHOSTS_OKTOQUERYFORADDRESSING フラグを設定した場合、サービス プロバイダは、ダイアログ ボックスを表示して、ユーザーにアドレス情報の入力を求めようとする。サービス プロバイダがダイアログ ボックスの表示を試みるときには、表示可能なウィンドウが存在している必要がある。ウィンドウがない場合、アプリケーションはロックする。
Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : Dplay8.h で宣言。