Platform SDK: DirectX |
DirectPlay4.GetDPEnumSessions メソッドは、特定のアプリケーションに対するアクティブ セッションと、特定のアプリケーションに対してサービスを提供するアクティブ ロビー セッションのいずれかまたは両方をすべて列挙する。このメソッドは、DirectPlay4.InitializeConnection によって接続が作成され、初期化された後に呼び出すことができる。
このメソッドは、セッションが既に開いているときに呼び出されると、エラーを返す。
object.GetDPEnumSessions( _ sessionDesc As DirectPlaySessionData, _ timeOut As Long, _ flags As CONST_DPENUMSESSIONFLAGS) _ As DirectPlayEnumSessions
非同期の場合は、内部セッション リストを更新するために DirectPlay が列挙要求をブロードキャストする間隔をミリ秒単位で指定する。
このタイムアウトを 0 に設定すると、サービス プロバイダと接続のタイプに適したデフォルトのタイムアウトが使用される。この値は、0 に設定するように推奨されている。アプリケーションでは、DirectPlay4.GetCaps を呼び出し、DPCAPS 型の lTimeout メンバを調べて、このタイムアウトを判断することができる。
成功すれば、DirectPlayEnumSessions オブジェクトを返す。
失敗すればエラーが発生し、Err.Number に次のいずれかの値が設定される。
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 を返す。ネットワークへの接続処理で使用されている場合は、DPERR_CONNECTING を返す。
このメソッドは、1 つ以上のホストをネットワーク上で見つけ、それらに列挙要求を送信するようにサービス プロバイダに要求することによって機能する。受信された応答が、列挙されたセッションを形成する。
このメソッドは、同期的 (デフォルト) または非同期的に呼び出すことができる。同期的に呼び出すと、DirectPlay が内部のセッション キャッシュを消去し、列挙要求を送信して、指定されたタイムアウトが経過するまで応答を収集する。すると、各セッションがアプリケーションに返される。アプリケーションは、すべてのセッションが返されるまでブロックする。
非同期的に呼び出すと (DPENUMSESSIONS_ASYNC)、セッション キャッシュ内のすべてのカレント セッション (存在する場合) がアプリケーションに返され、その後でメソッドが戻る。その後、DirectPlay はタイムアウト パラメータに設定された間隔で列挙要求を自動的に送信し、応答を待機する。各応答は、セッション キャッシュを更新するために利用される。
アプリケーションでは、DPENUMSESSIONS_ASYNC フラグを設定して GetDPEnumSessions をもう一度呼び出し、失効したセッションが削除され、新しいセッションが追加され、セッションが更新された最新のセッション リストを取得する必要がある。以降に GetDPEnumSessions を呼び出すと、列挙要求は生成されない。列挙要求は、プロセスが DPENUMSESSIONS_STOPASYNC を設定した GetDPEnumSessions の呼び出しによってキャンセルされるか、DirectPlay4.Open メソッドによってセッションが開かれるか、または DirectPlay オブジェクトが解放されるまで、DirectPlay によって定期的に生成される。
非同期的に列挙されているセッションの記述を変更するには、非同期の列挙を中止して、再度開始する必要がある。たとえば、パスワードなしでセッションを開始し、後で非同期呼び出しのときにパスワードを追加して、そのパスワードを使用してプライベート セッションの列挙を開始させることはできない。逆に、正しいパスワードを設定し、それを間違ったパスワードに変更しても、依然としてセッションを列挙することができる。しかし、DPENUMSESSIONS_STOPASYNC フラグを設定して GetDPEnumSessions を呼び出してからパスワードを設定すると、プライベート セッションが列挙される。
利用可能なセッションの列挙が完了したら、アプリケーションでは DirectPlay4.Open メソッドを使用して、いずれかのセッションに参加することができる。開くことができるのは、セッション キャッシュ内のセッションだけである。アプリケーションでは、GetDPEnumSessions が最後に呼び出されてから失効したセッションを開くことを試みることができる。この場合、エラーが返される。
保証サーバー上でセッションを列挙するときは、認証は実行されない。列挙の条件に合うセッションがすべて返される。認証は、アプリケーションがそれらのセッションのいずれかを Open または DirectPlay4.SecureOpen メソッドで開こうとしたときに実行される。
アプリケーションがロビーによって起動されていない場合、サービス プロバイダはダイアログ ボックスを表示し、ネットワーク上で列挙を実行するための情報のうち、DirectPlay4.InitializeConnection で提供されていないもの (電話番号、IP アドレスなど) をユーザーに要求することができる。サービス プロバイダがブロードキャスト列挙を実行でき、ユーザーに追加情報を要求しない場合、ダイアログ ボックスは表示されない。