Platform SDK: DirectX |
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 );
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.
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.
If this flag is not specified, the enumeration is done synchronously.
Password-protected sessions will not be enumerated unless the DPENUMSESSIONS_PASSWORDREQUIRED flag is also specified.
If this flag is not specified, no password-protected sessions will be returned.
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_CONNECTING |
DPERR_CONNECTIONLOST |
DPERR_EXCEPTION |
DPERR_GENERIC |
DPERR_INVALIDOBJECT |
DPERR_INVALIDPARAMS |
DPERR_NOCONNECTION |
DPERR_UNINITIALIZED |
DPERR_USERCANCEL |
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.
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:
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.
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.
DPSESSIONDESC2, IDirectPlay4::Open, IDirectPlay4::SecureOpen