HRESULT EnumSessions(LPDPSESSIONDESC2 lpsd,
DWORD dwTimeout,
LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
LPVOID lpContext, DWORD dwFlags);
Enumerates the sessions available to this DirectPlay object.
·Returns DP_OK if successful, or one of the following error values otherwise:
lpsd
Address of a 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 of the DPSESSIONDESC2 structure should be set to the globally unique identifier (GUID) of the application of interest, or NULL for all applications. The guidInstance member may be set to a specific GUID of a session instance if it is known; otherwise, it should be set to NULL to obtain all sessions. If a password is required, then the lpszPassword member should be set accordingly.
dwTimeout
Total amount of time, in milliseconds, that DirectPlay will wait for replies to the enumeration message (not the time between each enumeration). It is recommended that this parameter be set to zero so DirectPlay can compute the default timeout appropriate for the service provider.
lpEnumSessionsCallback2
Address of the EnumSessionsCallback2 function to be called for each DirectPlay session responding.
lpContext
Address of a user-defined context that is passed to each enumeration callback.
dwFlags
If this parameter is set to 0, only the available sessions will be enumerated (DPENUMSESSIONS_AVAILABLE).
Enumerates all sessions this application can join.
Enumerates all active sessions, whether they are available to join or not. Sessions in which the player limit has been reached, new players have been disabled, or joining has been disabled will be enumerated. The application can examine the dwFlags member of this structure to determine if the session will allow new applications to join or not.
This method is typically called immediately after the DirectPlay object is created by using the DirectPlayCreate function. It cannot be called while connected to a session or after an application has created a session. IDirectPlay2::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. The amount of time DirectPlay spends waiting for these replies is controlled by the dwTimeout parameter. When this time interval has expired, your callback will be notified by using the DPESC_TIMEDOUT flag, and a NULL value will be passed for the lpThisSD parameter. At this point, you can continue the enumeration by setting dwTimeout to a new value and returning TRUE, or you can cancel the enumeration by returning FALSE. It is recommended that dwTimeout be set to 0. In that case, DirectPlay will compute a time-out that is appropriate for the service provider.
Typically, only sessions that can be joined are enumerated. If the DPENUMSESSIONS_ALL flag is specified, sessions will be enumerated even if the creation of new players has been disabled. Note the application will still not be able to join these sessions.
If the application was not started by a lobby, the service provider may display a dialog to obtain information from the user to perform the enumeration. For example, the Microsoft serial service provider will ask for COM port settings, the modem service provider will ask for a phone number, and the Internet service provider will ask for an IP address of the host.
Password-protected sessions will not be enumerated unless you supply a correct password.