IDirectPlay4::EnumSessions

The IDirectPlay4::EnumSessions 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 DirectPlay object has been created and initialized either by DirectPlayCreate or IDirectPlay4::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 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 IDirectPlay4::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.

DPENUMSESSIONS_ALL

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.

DPENUMSESSIONS_ASYNC

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 Release.

If this flag is not specified, the enumeration is done synchronously.

DPENUMSESSIONS_AVAILABLE

Enumerate all sessions that are accepting new players to join. Sessions that 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.

DPENUMSESSIONS_RETURNSTATUS

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.

DPENUMSESSIONS_STOPASYNC

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), or DPERR_INVALIDPARAMS if the user entered a computer name in the TCP/IP service provider dialog that could not be resolved to an IP address. 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 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 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 IDirectPlay4::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 asychronous 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 EnumSessions 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 IDirectPlay4::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 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 IDirectPlay4::Open or IDirectPlay4::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 IDirectPlay4::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.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dplay.h.
  Import Library: Use dplayx.lib.

See Also

DPSESSIONDESC2, IDirectPlay4::Open, IDirectPlay4::SecureOpen