Platform SDK: DirectX |
IDirectPlay4::EnumSessions メソッドは、特定のアプリケーションのアクティブなセッションと、特定のアプリケーションを提供しているアクティブなロビー セッションのすべてを列挙する。このメソッドは、DirectPlayCreate メソッドまたは IDirectPlay4::InitializeConnection メソッドのいずれかにより オブジェクトを作成および初期化した後に呼び出すことができる。
このメソッドは、セッションがまだ開いている間に呼び出されると、エラーを返す。
HRESULT EnumSessions( LPDPSESSIONDESC2 lpsd, DWORD dwTimeout, LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2, LPVOID lpContext, DWORD dwFlags );
非同期の場合、この値は、内部セッション リストを更新するために DirectPlay により列挙要求がブロードキャストされる間隔 (ミリ秒単位) を示す。
タイムアウト値に 0 を設定すると、サービス プロバイダと接続タイプに適合したデフォルトのタイムアウト値が使用される。この値に 0 を設定することを推奨する。アプリケーションでは、IDirectPlay4::GetCaps メソッドを呼び出して DPCAPS 構造体の dwTimeout データ メンバを調べることにより、このタイムアウト値を判定できる。
パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。
DPENUMSESSIONS_ALL が指定されていない場合は、DPENUMSESSIONS_AVAILABLE であると見なされる。
このフラグが指定されていない場合、列挙は同期をとりながら実行される。
パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。
このフラグを指定しない場合は、パスワードにより保護されているセッションは返されない。
成功した場合は DP_OK を返す。失敗した場合は、次のエラー値のいずれかを返す。
DPERR_CONNECTING |
DPERR_CONNECTIONLOST |
DPERR_EXCEPTION |
DPERR_GENERIC |
DPERR_INVALIDOBJECT |
DPERR_INVALIDPARAMS |
DPERR_NOCONNECTION |
DPERR_UNINITIALIZED |
DPERR_USERCANCEL |
セッションが既に開いている場合は、DPERR_GENERIC を返す。DirectPlay オブジェクトが初期化されていない場合は、DPERR_UNINITIALIZED を返す。ユーザーが列挙プロセスを取り消した場合 (一般にサービス プロバイダのダイアログボックスを取り消すことにより) は DPERR_USERCANCEL を返し、ユーザーが TCP/IP サービス プロバイダのダイアログ ボックスに IP アドレスに変換できないコンピュータ名を入力した場合は DPERR_INVALIDPARAMS を返す。メソッドがネットワークへ接続中の場合は、DPERR_CONNECTING を返す。
EnumSessions は、サービス プロバイダがネットワーク上のホストを検索し、それらを列挙要求に送信するように要求することで機能する。受信した応答により、列挙されるセッションがすべて揃う。
EnumSessions は、同期 (デフォルト) または非同期に呼び出すことができる。同期をとりながら呼び出した場合、DirectPlay は内部セッション キャッシュをクリアし、列挙要求を送信して、指定されたタイムアウトになるまで応答を収集する。各セッションは、コールバック関数によりアプリケーションに返される。アプリケーションは、すべてのセッションがコールバック関数から返されるまでブロックされる。
非同期に呼び出された場合 (DPENUMSESSIONS_ASYNC)、セッション キャッシュのカレント セッション (存在する場合) はすべてコールバック関数によりアプリケーションに返され、またメソッドは戻る。DirectPlay は、タイムアウト パラメータを指定して列挙要求を自動的に送信し、応答が返されるのを待つ。次のように、各応答を使用してセッション キャッシュを更新する。
アプリケーションは、失効したセッションをすべて削除し、新しいセッションを追加し、またセッションを更新した最新のセッション リストを取得するために、EnumSessions を (DPENUMSESSIONS_ASYNC フラグを設定して) 再度呼び出す必要がある。それ以降は EnumSessions を呼び出しても列挙要求は生成されない。DPENUMSESSIONS_STOPASYNC フラグを設定して EnumSessions を呼び出し、プロセスを取り消すか、IDirectPlay4::Open メソッドを使用してセッションを開くか、または DirectPlay オブジェクトを解放するまで、列挙要求は DirectPlay により定期的に作成される。
非同期に列挙するセッションの記述を変更するには、非同期列挙を停止して、それを再起動する必要がある。たとえば、パスワードを指定しなければ列挙を起動できないので、後から非同期呼び出しでパスワードを追加し、それによりそのパスワードを使用してプライベート セッションの列挙を開始する。反対に、正しいパスワードを指定してから、不正なパスワードに変更しても、そのセッションは列挙される。ただし、DPENUMSESSIONS_STOPASYNC フラグを指定して EnumSessions を呼び出し、パスワードを指定すると、プライベート セッションが列挙される。
使用可能なセッションの列挙が完了したら、アプリケーションは IDirectPlay4::Open メソッドを使用してセッションのいずれかに参加できる。開くことが可能なのは、セッション キャッシュのセッションだけである。アプリケーションは、最後に EnumSessions を呼び出してエラーが返されてから、失効したセッションを開くこともできる。
認証は、保証サーバーでセッションを列挙するときには実行されない。列挙条件を満たすセッションがすべて返される。アプリケーションで IDirectPlay4::Open または IDirectPlay4::SecureOpen を使用してこれらのセッションのいずれかを開こうとすると、認証が行われる。
アプリケーションがロビーにより起動されたのではない場合、ネットワークで列挙を実行するための情報 (電話番号や IP アドレスなど) が IDirectPlay4::InitializeConnection に渡されていなければ、サービス プロバイダはダイアログ ボックスを表示してユーザーにそれらの情報を入力するように要求できる。サービス プロバイダがブロードキャスト列挙を実行できる場合、ユーザーに情報を入力してもらう必要がなければ、ダイアログ ボックスは表示されない。ユーザーがサービス プロバイダのダイアログ ボックスを取り消すと、EnumSessions は DPERR_USERCANCEL を返す。
Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dplay.h で宣言。
インポート ライブラリ : dplayx.lib を使用。