IDirectPlay4::EnumConnections
IDirectPlay4 Interface
Enumerates all the registered service providers and lobby providers that are available to the application. These should be presented to the user to make a selection. The connection that the user selects should be passed to the IDirectPlay4::InitializeConnection method.
Syntax
HRESULT EnumConnections(
LPCGUID lpguidApplication,
LPDPENUMCONNECTIONSCALLBACK lpEnumCallback,
LPVOID lpContext,
DWORD dwFlags
);
Parameters
- lpguidApplication
- Pointer to an application globally unique identifier (GUID). Only service providers and lobby providers that are usable by this application will be returned. If set to a NULL pointer, a list of all the connections is enumerated regardless of the application GUID.
- lpEnumCallback
- Pointer to a user-supplied EnumConnectionsCallback function that will be called for each available connection.
- lpContext
- Pointer to a user-defined context that is passed to the callback function.
- dwFlags
- Flags that specify the type of connections to be enumerated. The default (dwFlags = 0) will enumerate DirectPlay service providers only. Possible values are:
- DPCONNECTION_DIRECTPLAY — enumerate DirectPlay service providers to communicate in an application session.
- DPCONNECTION_DIRECTPLAYLOBBY — enumerate DirectPlay lobby providers to communicate with a lobby server.
Return Value
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_CONNECTIONLOST DPERR_INVALIDFLAGS DPERR_INVALIDPARAMS
Remarks
This method replaces the DirectPlayEnumerate function. DirectPlayEnumerate still works, but only returns registered service providers.
The order in which the service and lobby providers are returned is not guaranteed to be the same in subsequent calls to EnumConnections.
Not all the enumerated connections are available for use. For example, this method will return the modem service provider even if the user has no modem installed. The application can call the IDirectPlay4::InitializeConnection method on each connection and check for an error code to determine whether the service provider can be used.
Calling this method on the IDirectPlay4A (ANSI) interface always returns a suitably localized, single-byte character string. No multi-byte characters are used, so there will be no problems displaying strings using fonts that do not support multi-byte characters. Calling this method on the IDirectPlay4 (Unicode) interface returns a localized, wide character description.
Some service providers can register themselves as private. These service providers are not enumerated using this method. To use private service providers, you must explicitly reference them by their GUID, either by lobby launching the application or by creating a DirectPlay Address and passing it to InitializeConnection.
See Also
IDirectPlay4::InitializeConnection, EnumConnectionsCallback, DirectPlay Address
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.