次の方法で共有

IDirectPlay8Client::EnumHosts メソッド

  • [アーティクル]

IDirectPlay8Client::EnumHosts メソッド

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。

構文

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

戻り値

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

DPNERR_INVALIDDEVICEADDRESS ローカル コンピュータまたはアダプタのアドレスが無効である。
DPNERR_INVALIDFLAGS このメソッドに渡されたフラグは無効である。
DPNERR_INVALIDHOSTADDRESS 指定されたリモート アドレスが無効である。
DPNERR_INVALIDPARAM メソッドに渡された 1 つあるいは複数のパラメータが無効である。
DPNERR_ENUMQUERYTOOLARGE 指定されたクエリ データが大きすぎる。
DPNERR_USERCANCEL ユーザーは処理を取り消した。

注意

列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体およびホストの場所を識別する IDirectPlay8Address オブジェクトが入っている。

列挙基準を満たすアプリケーションが見つかると、DPN_MSGID_ENUM_HOSTS_RESPONSE システム メッセージによりアプリケーションのメッセージ ハンドラが呼び出される。メッセージには、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 構造体およびホストの場所を識別する IDirectPlay8Address オブジェクトが入っている。

Transmission Control Protocol/Internet Protocol (TCP/IP) サービス プロバイダを使うときにネットワーク アドレス変換 (NAT) とプロキシのサポートを向上させるか、モデム サービス プロバイダによるリダイヤルを避ける場合は、列挙をアクティブにして IDirectPlay8Client::Connect メソッドを呼び出すこと。列挙が完了するのを避けるには、dwEnumCount パラメータを INFINITE に設定し、接続処理が完了する前に列挙が終わらないようにするため IDirectPlay8Client::CancelAsyncOperation を使わない。また、DPNMSG_ENUM_HOSTS_RESPONSE メッセージの pAddressSender および pAddressDevice の各アドレス オブジェクトを変更せずに IDirectPlay8Client::Connect メソッドのパラメータ pHostAddr および pDeviceInfo に渡す。コールバック関数の外側でアドレス オブジェクトを IDirectPlay8Client::Connect に渡すには、IDirectPlay8Address::Duplicate または IDirectPlay8Address::AddRef を使ってオブジェクトの破棄を防ぎ、スレッドに依存しないコードを使ってポインタを保存する。

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

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは dwEnumCount、dwRetryInterval、または dwTimeOut を指定しないことを推奨する。唯一の例外として、明示的に取り消されるまで列挙を継続させたい場合は、dwEnumCount を INFINITE に設定する。

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

1 つの列挙セッション中に同じホストから複数の DPN_MSGID_ENUM_HOSTS_RESPONSE メッセージを受け取ることがある。関連する DPN_APPLICATION_DESC 構造体の guidInstance メンバを使ってこれらの重複する応答を対応させることができる。

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

「データ値の概要」では、各サービス プロバイダに必要なアドレス情報を指定している。

IDirectPlay8Client::CancelAsyncOperation メソッドを呼び出して列挙を取り消した場合、またはDPN_MSGID_ENUM_HOSTS_RESPONSE メッセージの処理中に DPN_OK が返されない場合、DPNERR_USERCANCEL が返される。