DirectPlay4.GetDPEnumSessions

The DirectPlay4.GetDPEnumSessions method enumerates all the active sessions for a particular application and/or all the active lobby sessions that serve a particular application. This method can be called after a connection has been created and initialized by DirectPlay4.InitializeConnection.

The method returns an error if called while a session is already open.

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

Parameters

object

Object expression that resolves to a DirectPlay4 object.

sessionDesc

DirectPlaySessionData object representing the description of the sessions to be enumerated. This object is obtained by using the DirectPlay4.CreateSessionData method. The GuidApplication member can be set to the globally unique identifier (GUID) of an application of interest if it is known, or to "" to obtain all sessions. The SessionPassword member is only needed if you want private sessions. All other data members are ignored.

timeOut

In the synchronous case, the total amount of time, in milliseconds, that DirectPlay will wait for replies to the enumeration request (not the time between each enumeration). Any replies received after this time-out will be ignored. The application will be blocked until the time-out expires.

In the asynchronous case, this is the interval, in milliseconds, that enumeration requests will be broadcast by DirectPlay in order to update the internal sessions list.

If the time-out is set to 0, a default time-out appropriate for the service provider and connection type will be used. It is recommended that you set this value to 0. The application can determine this time-out by calling DirectPlay4.GetCaps and examining the lTimeout member of the DPCAPS type.

flags

Zero or more flags from the CONST_DPENUMSESSIONFLAGS enumeration. The default is 0, which is equivalent to DPENUMSESSIONS_AVAILABLE. When enumerating sessions with DPENUMSESSIONS_ALL or DPENUMSESSIONS_PASSWORDREQUIRED, it is important for the application to know which sessions cannot be joined and which sessions are password-protected so the user can be warned or prompted for a password.

Return Values

If it succeeds, the method returns a DirectPlayEnumSessions object.

Error Codes

If the method fails, an error is raised and Err.Number may be set to one of the following values:

This method returns DPERR_GENERIC if the session is already open. It returns DPERR_UNINITIALIZED if the DirectPlay object has not been initialized. It returns DPERR_USERCANCEL if the user canceled the enumeration process (usually by canceling a service provider dialog box). It returns DPERR_CONNECTING if the method is in the process of connecting to the network.

Remarks

This method works by requesting that the service provider locate one or more hosts on the network and send them an enumeration request. The replies that are received make up the sessions that are enumerated.

This method can be called synchronously (default) or asynchronously. When called synchronously, DirectPlay will clear the internal session cache, send out an enumeration request, and collect replies until the specified time-out expires. Each session will then be returned to the application. The application will be blocked until all the sessions have been returned.

When called asynchronously (DPENUMSESSIONS_ASYNC), all the current sessions (if any) in the session cache will be returned to the application and then the method will return. DirectPlay will then automatically send out enumeration requests with the period of the time-out parameter and listen for replies. Each reply will be used to update the session cache:

• Sessions already in the cache will be updated.
• Sessions that have not been updated for a set period of time (and thus have expired) will be deleted.
• New sessions will be added.

The application must call GetDPEnumSessions (with the DPENUMSESSIONS_ASYNC flag set) again to obtain the most up-to-date session list with all the expired sessions deleted, new sessions added, and updated sessions. Subsequent calls to GetDPEnumSessions will not generate an enumeration request. Enumeration requests will be generated periodically by DirectPlay until the process is either canceled by calling GetDPEnumSessions with the DPENUMSESSIONS_STOPASYNC flag, a session is opened by using the DirectPlay4.Open method, or the DirectPlay object is released.

To change the description of the sessions being enumerated asynchronously, you must stop the asynchronous enumeration and then start it up again. For example, you cannot start an enumeration without a password and then later, during an asynchronous call, add a password and have it begin enumerating private sessions using that password. Conversely, if you specify the correct password, then change to an incorrect password, you will still enumerate the session. However, you can call GetDPEnumSessions with the DPENUMSESSIONS_STOPASYNC flag, then specify the password, and the private session will be enumerated.

Once enumeration of the available sessions is complete, the application can join one of the sessions using the DirectPlay4.Open method. Only sessions in the session cache can be opened. An application may attempt to open a session that has expired since the last time GetDPEnumSessions was called in which case an error will be returned.

No authentication is performed when enumerating sessions on a secure server. All sessions that meet the enumeration criteria will be returned. Authentication will be done when the application attempts to open one of these sessions with the Open or DirectPlay4.SecureOpen method.

If the application was not started by a lobby, the service provider can display a dialog box asking the user for information (such as a phone number or IP address) in order to perform the enumeration on the network, if that information was not provided in DirectPlay4.InitializeConnection. If the service provider can do a broadcast enumeration and requires no extra information from the user, no dialog box will appear.