This method of the DirectPlay2 Class enumerates the sessions available to this DirectPlay object. Use the stopEnumSessions method to stop the enumeration.
public void enumSessions(DPSessionDesc sessionDesc, _Guid sessionGuid, _Guid applicationGuid, String sessionName, String password, int timeOut, IEnumSessionsCallback2 callback, IUnknown context, int flags);
sessionDesc | A DPSessionDesc object describing the sessions to be enumerated. Only those sessions that meet the criteria set in this structure will be enumerated. If a password is required, the password field should be set accordingly. |
sessionGuid | The GUID of the DirectPlay session of interest. This parameter must be set to NULL unless the DPENUMPLAYERS_SESSION flag is specified. |
applicationGuid | The GUID of the application. |
sessionName | The Unicode string containing the name of the session. Use this member only if the IDirectPlay2 interface is in use. |
password | The Unicode string containing the password of the session. Use this member only if the IDirectPlay2 interface is in use. |
timeOut | The 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. |
callback | The callback interface that contains the callback function to be called for each DirectPlay session responding. |
context | A user-defined context that is passed to each enumeration callback. |
flags | A value of the DPENUMSESSIONS_ALL type. Set to 0 or DPENUMSESSIONS_AVAILABLE, to enumerate only available sessions. |
This method is usually called immediately after the DirectPlay object is created using directPlayCreate. It cannot be called while connected to a session or after an application has created a session. enumSessions works by asking that the service provider locate one or more hosts on the network and send the hosts an enumeration request. The replies received make up the sessions that are enumerated. The amount of time DirectPlay spends listening for these replies is controlled by the f1 parameter. When this time interval has expired, your callback will be notified with the DPESC_TIMEDOUT flag. At this point, you can choose to continue the enumeration by setting f1 to a new value and returning 1 or by returning 0 to cancel the enumeration. It is recommended that f1 be set to 0. In that case, DirectPlay will compute a time out that is appropriate for the service provider.
Usually, 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. Be aware that the application will still not be able to join these sessions.
If the application was not launched by a lobby, the service provider can 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.