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 DirectPlay object has been created and initialized either by DirectPlayCreate or IDirectPlay3::InitializeConnection.
This method returns an error if called while a session is already open.
HRESULT EnumSessions(
LPDPSESSIONDESC2 lpsd,
DWORD dwTimeout,
LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
LPVOID lpContext,
DWORD dwFlags
);
Parameters
lpsd
Pointer to the DPSESSIONDESC2 structure describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. The guidApplication member can be set to the globally unique identifier (GUID) of an application of interest if it is known, or to GUID_NULL to obtain all sessions. The lpszPassword member is only needed if you want private sessions. All data members besides guidApplication and lpszPassword are ignored.
dwTimeout
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 zero, a default time-out appropriate for the service provider and connection type will be used. It is recommended that you set this value to zero. The application can determine this time-out by calling IDirectPlay3::GetCaps and examining the dwTimeout data member of the DPCAPS structure.
lpEnumSessionsCallback2
Pointer to the application-supplied EnumSessionsCallback2 function to be called for each DirectPlay session responding.
lpContext
Pointer to a user-defined context that is passed to each enumeration callback.
dwFlags
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.
Enumerate all active sessions, whether they are accepting new players or not. Sessions in which the player limit has been reached, new players have been disabled, or joining has been disabled will be enumerated.
Password protected sessions will not be enumerated unless the DPENUMSESSIONS_PASSWORDREQUIRED flag is also specified.
If DPENUMSESSIONS_ALL is not specified, DPENUMSESSIONS_AVAILABLE is assumed.
Enumerates all the current sessions in the session cache and returns immediately. Starts the asynchronous enumeration process if not already started. Updates to the session list continue until canceled by calling EnumSessions with the DPENUMSESSIONS_STOPASYNC flag, or by calling Open, or by calling Release.
If this flag is not specified, the enumeration is done synchronously.
Enumerate all sessions that are accepting new players to join. Sessions which have reached their maximum number of players, or have disabled new players, or have disabled joining will not be enumerated.
Password protected sessions will not be enumerated unless the DPENUMSESSIONS_PASSWORDREQUIRED flag is also specified.
DPENUMSESSIONS_PASSWORDREQUIRED
When used in combination with one of the two flags DPENUMSESSIONS_AVAILABLE or DPENUMSESSIONS_ALL, enables password-protected sessions to be enumerated in addition to sessions without password protection.
If this flag is not specified, no password protected sessions will be returned.
If this flag is specified, the enumeration will not display any dialog boxes showing the connection progress status. If the connection cannot be made immediately, the method will return with the DPERR_CONNECTING error. The application must keep calling EnumSessions until either DP_OK is returned, indicating successful completion, or some other error code is returned, indicating an error.
Enumerates all the current sessions in the session cache and cancels the asynchronous enumeration process.
Return Values
Returns DP_OK if successful, or one of the following error values otherwise:
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
EnumSessions 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.
EnumSessions 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 through the callback function. The application will be blocked until all the sessions have been returned through the callback function.
When called asynchronously (DPENUMSESSIONS_ASYNC), all the current sessions (if any) in the session cache will be returned to the application through the callback function 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 haven't been updated for a set period of time (and thus have expired) will be deleted
·New sessions will be added
The application must call EnumSessions (with the DPENUMSESSIONS_ASYNC flag) 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 EnumSessions will not generate an enumeration request. Enumeration requests will be generated periodically by DirectPlay until the process is either canceled by calling EnumSessions with the DPENUMSESSIONS_STOPASYNC flag, a session is opened using the IDirectPlay3::Open method, or the DirectPlay object is released.
Once enumeration of the available sessions is complete, the application can join one of the sessions using the IDirectPlay3::Open method. Only sessions in the session cache can be opened. It is possible for the application to attempt to open a session that has expired since the last time EnumSessions 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 IDirectPlay3::Open or IDirectPlay3::SecureOpen.
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 IDirectPlay3::InitializeConnection. If the service provider can do a broadcast enumeration and requires no extra information from the user, no dialog box will appear. If the user cancels a service provider dialog box, EnumSessions returns DPERR_USERCANCEL.
See Also
DPSESSIONDESC2, IDirectPlay3::Open, IDirectPlay3::SecureOpen