Platform SDK: DirectX

IDirectPlay4::EnumSessions

IDirectPlay4::EnumSessions メソッドは、特定のアプリケーションのアクティブなセッションと、特定のアプリケーションを提供しているアクティブなロビー セッションのすべてを列挙する。このメソッドは、DirectPlayCreate メソッドまたは IDirectPlay4::InitializeConnection メソッドのいずれかにより オブジェクトを作成および初期化した後に呼び出すことができる。

このメソッドは、セッションがまだ開いている間に呼び出されると、エラーを返す。

HRESULT EnumSessions(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwTimeout,
  LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

パラメータ

lpsd
列挙するセッションを記述した DPSESSIONDESC2 構造体へのポインタ。この構造体に設定されている条件を満たすセッションのみが列挙される。guidApplication メンバに、それが認識されているとき目的のアプリケーションのグローバル ユニーク識別子 (GUID) を設定したり、または GUID_NULL を設定してすべてのセッションを取得することができる。lpszPassword メンバは、プライベート セッションを希望する場合にのみ必要となる。guidApplicationlpszPassword 以外のデータ メンバはすべて無視される。
dwTimeout
同期の場合、DirectPlay が列挙要求に対する応答を待っている時間 (列挙と列挙の間の時間ではない)(ミリ秒単位)。このタイムアウト値が経過してから応答を受信しても、それらはすべて無視される。アプリケーションは、タイムアウト値を経過するまでブロックされる。

非同期の場合、この値は、内部セッション リストを更新するために DirectPlay により列挙要求がブロードキャストされる間隔 (ミリ秒単位) を示す。

タイムアウト値に 0 を設定すると、サービス プロバイダと接続タイプに適合したデフォルトのタイムアウト値が使用される。この値に 0 を設定することを推奨する。アプリケーションでは、IDirectPlay4::GetCaps メソッドを呼び出して DPCAPS 構造体の dwTimeout データ メンバを調べることにより、このタイムアウト値を判定できる。

lpEnumSessionsCallback2
DirectPlay セッションの応答ごとに呼び出される、アプリケーションにより指定された EnumSessionsCallback2 関数へのポインタ。
lpContext
各列挙コールバック関数へ渡される、ユーザー定義のコンテキストへのポインタ。
dwFlags
デフォルトは 0 であり、DPENUMSESSIONS_AVAILABLE と等価である。DPENUMSESSIONS_ALL または DPENUMSESSIONS_PASSWORDREQUIRED を使用して列挙するとき、参加できないセッションや、ユーザーが警告したり、パスワード入力を要求できるようにパスワードで保護されているセッションを、アプリケーションで認識することが重要である。
DPENUMSESSIONS_ALL
セッションが新しいプレーヤーを受け付けているかどうかに関係なく、すべてのアクティブなセッションを列挙する。プレーヤー制限に達したセッション、新しいプレーヤーが無効になったセッション、または参加が無効になったセッションを列挙する。

パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。

DPENUMSESSIONS_ALL が指定されていない場合は、DPENUMSESSIONS_AVAILABLE であると見なされる。

DPENUMSESSIONS_ASYNC
セッション キャッシュのカレント セッションをすべて列挙し、即座に戻る。非同期列挙プロセスがまだ起動されていない場合は、それを起動する。DPENUMSESSIONS_STOPASYNC フラグを指定して EnumSessions を呼び出すか、または OpenRelease を呼び出して取り消すまで、セッション リストは更新され続ける。

このフラグが指定されていない場合、列挙は同期をとりながら実行される。

DPENUMSESSIONS_AVAILABLE
新しいプレーヤーの参加を受け付けているセッションをすべて列挙する。プレーヤーの最大数に達しているセッション、新しいプレーヤーが無効になったセッション、または参加が無効になったセッションは列挙しない。

パスワードにより保護されたセッションは、DPENUMSESSIONS_PASSWORDREQUIRED フラグも指定されていなければ列挙されない。

DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_AVAILABLE フラグまたは DPENUMSESSIONS_ALL フラグのいずれかと共に使用すると、パスワードにより保護されていないセッションに加えて、パスワードにより保護されているセッションも列挙される。

このフラグを指定しない場合は、パスワードにより保護されているセッションは返されない。

DPENUMSESSIONS_RETURNSTATUS
このフラグを指定した場合は、列挙時に接続の進行状況を示すダイアログ ボックスが表示されない。すぐに接続できない場合、メソッドは DPERR_CONNECTING エラーを返す。アプリケーションは、正常終了を示す DP_OK が返されるか、またはエラーを示すそのほかのエラー コードが返されるまで EnumSessions を呼び出し続ける必要がある。
DPENUMSESSIONS_STOPASYNC
セッション キャッシュのカレント セッションをすべて列挙し、非同期列挙プロセスを取り消す。

戻り値

成功した場合は 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 に渡されていなければ、サービス プロバイダはダイアログ ボックスを表示してユーザーにそれらの情報を入力するように要求できる。サービス プロバイダがブロードキャスト列挙を実行できる場合、ユーザーに情報を入力してもらう必要がなければ、ダイアログ ボックスは表示されない。ユーザーがサービス プロバイダのダイアログ ボックスを取り消すと、EnumSessionsDPERR_USERCANCEL を返す。

必要条件

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

参照

DPSESSIONDESC2IDirectPlay4::OpenIDirectPlay4::SecureOpen