IDirectPlay8Client::EnumServiceProviders Method

DirectPlay

 
Microsoft DirectX 9.0 SDK Update (Summer 2003)

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_BUFFERTOOSMALLThe supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDPARAMOne 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.



© 2003 Microsoft Corporation. All rights reserved.