IDirectPlay4::EnumConnections

The IDirectPlay4::EnumConnections method 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.

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) gives the same results as DPCONNECTION_DIRECTPLAY.

Possible values are:

DPCONNECTION_DIRECTPLAY

Enumerate only DirectPlay service providers to communicate in an application session.

DPCONNECTION_DIRECTPLAYLOBBY

Enumerate DirectPlay lobby providers to communicate with a lobby server.

Return Values

Returns DP_OK if successful, or one of the following error values otherwise:

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.

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

IDirectPlay4::InitializeConnection, EnumConnectionsCallback