Platform SDK: DirectX

DirectPlay4.GetDPEnumSessions

DirectPlay4.GetDPEnumSessions メソッドは、特定のアプリケーションに対するアクティブ セッションと、特定のアプリケーションに対してサービスを提供するアクティブ ロビー セッションのいずれかまたは両方をすべて列挙する。このメソッドは、DirectPlay4.InitializeConnection によって接続が作成され、初期化された後に呼び出すことができる。

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

object.GetDPEnumSessions( _
    sessionDesc As DirectPlaySessionData, _
    timeOut As Long, _
    flags As CONST_DPENUMSESSIONFLAGS) _
    As DirectPlayEnumSessions

パラメータ

object
DirectPlay4 オブジェクトを表すオブジェクト式。
sessionDesc
列挙されるセッションの記述を表す DirectPlaySessionData オブジェクト。このオブジェクトを取得するには、DirectPlay4.CreateSessionData メソッドを使用する。GuidApplication メンバには、対象となるアプリケーションがわかっている場合にはそのグローバル ユニーク識別子 (GUID)、すべてのセッションを取得する場合には "" を設定できる。SessionPassword メンバは、プライベート セッションを列挙する場合にのみ必要である。ほかのデータ メンバは、すべて無視される。
timeOut
同期を取る場合は、DirectPlay が列挙要求の応答を待機する時間 (各列挙間の時間ではない) をミリ秒で指定する。ここに指定した時間が経過した後に受信された応答は、すべて無視される。このタイムアウト時間が経過するまで、アプリケーションはブロックする。

非同期の場合は、内部セッション リストを更新するために DirectPlay が列挙要求をブロードキャストする間隔をミリ秒単位で指定する。

このタイムアウトを 0 に設定すると、サービス プロバイダと接続のタイプに適したデフォルトのタイムアウトが使用される。この値は、0 に設定するように推奨されている。アプリケーションでは、DirectPlay4.GetCaps を呼び出し、DPCAPS 型の lTimeout メンバを調べて、このタイムアウトを判断することができる。

flags
CONST_DPENUMSESSIONFLAGS 列挙型の 0 個以上のフラグ。デフォルトは 0 であり、これは DPENUMSESSIONS_AVAILABLE に等しい。DPENUMSESSIONS_ALL または DPENUMSESSIONS_PASSWORDREQUIRED でセッションを列挙するときは、どのセッションが参加不可能で、どのセッションがパスワードで保護されているかをアプリケーションで把握し、ユーザーに警告したり、パスワードを要求できるようにすることが重要である。

戻り値

成功すれば、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 アドレスなど) をユーザーに要求することができる。サービス プロバイダがブロードキャスト列挙を実行でき、ユーザーに追加情報を要求しない場合、ダイアログ ボックスは表示されない。