IDirectPlay8Client::EnumServiceProviders Method

Enumerates the registered service providers available to the application.

Syntax

HRESULT EnumServiceProviders(      

    const GUID *const pguidServiceProvider,
    const GUID *const pguidApplication,
    DPN_SERVICE_PROVIDER_INFO *const pSPInfoBuffer,
    PDWORD const pcbEnumData,
    PDWORD const pcReturned,
    const DWORD dwFlags
);

Parameters

pguidServiceProvider

[in] Pointer to a variable of type GUID that specifies a service provider. This optional parameter forces the enumeration of subdevices for the specified service provider. You should normally set this value to NULL, to enumerate all available service providers. Otherwise, set pguidServiceProvider to one of the following predefined values.

CLSID_DP8SP_TCPIP

Internet Protocol (IP) service providers

CLSID_NETWORKSIMULATOR_DP8SP_TCPIP

DP8Sim service providers

CLSID_DP8SP_SERIAL

Serial service providers

CLSID_DP8SP_MODEM

Modem service providers

CLSID_DP8SP_IPX

IPX service providers

pguidApplication

[in] Pointer to a variable of type GUID that specifies an application. If a pointer is passed in this parameter, only service providers who can be connected to the application are enumerated. You can also pass NULL to enumerate the registered service providers for the system.

pSPInfoBuffer

[out] Pointer to an array of DPN_SERVICE_PROVIDER_INFO structures that will be filled with service provider information.

pcbEnumData

[out] Pointer to DWORD, which is filled with the size of the pSPInfoBuffer array if the buffer is too small.

pcReturned

[out] Pointer to a variable of type DWORD that specifies the number of DPN_SERVICE_PROVIDER_INFO structures returned in the pSPInfoBuffer array.

dwFlags

[in] The following flag can be specified.

DPNENUMSERVICEPROVIDERS_ALL

Enumerates all the registered service providers for the system, including those that are not available to the application or do not have devices installed.

Return Value

Returns S_OK if successful, or one of the following error values.

DPNERR_BUFFERTOOSMALL	The supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.

Remarks

Call this method initially by specifying NULL in the pguidServiceProvider parameter to determine the base service providers available to the system. Specific devices for a service provider can be obtained by passing a pointer to a service provider globally unique identifier (GUID) in the pguidServiceProvider. This is useful, for example, when using the Modem Connection for Microsoft?DirectPlay?service provider. You can choose among different modems for dialing out and select specific modems for hosting.

If the pEnumDatabuffer is not big enough to hold the requested service provider information, the method returns DPNERR_BUFFERTOOSMALL and the cbEnumData parameter contains the required buffer size. Typically, the best strategy is to call the method once with a zero-length buffer to determine the required size. Then call the method again with the appropriate-sized buffer.

Normally, this method will return only those service providers that can be used by the application. For example, if the Internetwork Packet Exchange (IPX) networking protocol is not installed, DirectPlay will not return the IPX service provider. To have DirectPlay return all service providers, even those that cannot be used by the application, set the DPNENUMSERVICEPROVIDERS_ALL flag in dwFlags.