IDirectPlay8Client::EnumHosts Method

Enumerates applications that host Microsoft® DirectPlay® games.

Syntax

HRESULT EnumHosts(      

    PDPN_APPLICATION_DESC const pApplicationDesc,
    IDirectPlay8Address *const pdpaddrHost,
    IDirectPlay8Address *const pdpaddrDeviceInfo,
    PVOID const pvUserEnumData,
    const DWORD dwUserEnumDataSize,
    const DWORD dwEnumCount,
    const DWORD dwRetryInterval,
    const DWORD dwTimeOut,
    PVOID const pvUserContext,
    HANDLE *const pAsyncHandle,
    const DWORD dwFlags
);

Parameters

pApplicationDesc

[in] Pointer to a DPN_APPLICATION_DESC structure that specifies which application hosts to enumerate. You must set the pApplicationDesc.dwSize member to the appropriate value. To reduce the number of responses, set pApplicationDesc.guidApplication to the globally unique identifier (GUID) of the application to be found. If this member is not set, the search will include all applications.

pdpaddrHost

[in] Pointer to an IDirectPlay8Address object that specifies the address of the computer that is hosting the application. Some service providers allow this parameter to be NULL or be an address object containing only the service provider component. In this case, DirectPlay will get the information by using a broadcast mechanism or from the pdpaddrDeviceInfo parameter. If you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag in dwFlags, the user can be queried for any missing address information.

pdpaddrDeviceInfo

[in] Pointer to an IDirectPlay8Address object that specifies the service provider and local device settings to use when enumerating. The user can be queried for any missing address information if you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag in the dwFlags parameter.

pvUserEnumData

[in] Pointer to a block of data that is sent in the enumeration request to the host. The size of the data is limited depending on the network type. Call IDirectPlay8Client::GetSPCaps to obtain the exact value.

dwUserEnumDataSize

[in] Variable of type DWORD that specifies the size of the data pointed at in the pvUserEnumData parameter.

dwEnumCount

[in] Value specifying how many times the enumeration data will be sent. Set this parameter to zero to use the default value. You can obtain the default value for dwEnumCount by calling IDirectPlay8Client::GetSPCaps. If dwEnumCount is set to INFINITE, the enumeration will continue until canceled.

dwRetryInterval

[in] Value specifying how many milliseconds between enumeration retries. Set this parameter to zero to use the default value. You can obtain the default value for dwRetryInterval by calling IDirectPlay8Client::GetSPCaps.

dwTimeOut

[in] Variable of type DWORD that specifies the number of milliseconds that DirectPlay will wait for replies after the last enumeration is sent. Set this parameter to zero to use the default value. You can obtain the default value for dwTimeOut by calling IDirectPlay8Client::GetSPCaps. If INFINITE is specified, the enumeration continues until it is canceled.

pvUserContext

[in] Context that is provided in the client's message handler when it is called with responses to the enumeration. This can be useful to differentiate replies from concurrent enumerations.

pAsyncHandle

[out] A DPNHANDLE. When the method returns, pAsyncHandle will point to a handle that you can pass to IDirectPlay8Client::CancelAsyncOperation to cancel the operation. This parameter must be set to NULL if you set the DPNENUMHOSTS_SYNC flag in dwFlags.

dwFlags

[in] The following flags can be set.

DPNENUMHOSTS_SYNC

Causes the method to process synchronously.

DPNENUMHOSTS_OKTOQUERYFORADDRESSING

Setting this flag will display a standard DirectPlay dialog box, which queries the user for more information if not enough information is passed in this method.

DPNENUMHOSTS_NOBROADCASTFALLBACK

If the service provider supports broadcasting, setting this flag will disable the broadcast capabilities. Check to see if broadcasting is supported by examining the DPN_SP_CAPS structure before setting this flag.

Return Value

Returns S_OK if this method is processed synchronously and is successful. By default, this method is run asynchronously and normally returns DPNSUCCESS_PENDING. It can also return one of the following error values.

DPNERR_INVALIDDEVICEADDRESS	The address for the local computer or adapter is invalid.
DPNERR_INVALIDFLAGS	The flags passed to this method are invalid.
DPNERR_INVALIDHOSTADDRESS	The specified remote address is invalid.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_ENUMQUERYTOOLARGE	The query data specified is too large.
DPNERR_USERCANCEL	The user canceled the operation.
DPNERR_ALREADYINITIALIZED	The object has already been initialized.

Remarks

When an application is found that meets the enumeration criteria, the application's message handler is called with a DPN_MSGID_ENUM_HOSTS_RESPONSE system message. The message contains a DPN_APPLICATION_DESC structure describing the applications found and IDirectPlay8Address objects identifying the location of the hosts.

When an application is found that meets the enumeration criteria, the application's message handler is called with a DPN_MSGID_ENUM_HOSTS_RESPONSE system message. The message contains a DPN_APPLICATION_DESC structure describing the applications found and IDirectPlay8Address objects identifying the location of the hosts.

To ensure better Network Address Translation (NAT) and proxy support when using the Transmission Control Protocol/Internet Protocol (TCP/IP) service provider or to prevent redialing with the modem service provider, keep the enumeration active when calling the IDirectPlay8Client::Connect method. To prevent the enumeration from completing, set the dwEnumCount parameter to INFINITE and do not use the IDirectPlay8Client::CancelAsyncOperation to terminate the enumeration before the connect operation has completed. You should also pass the pAddressSender and pAddressDevice address objects in the DPNMSG_ENUM_HOSTS_RESPONSE message without modification into the pHostAddr and pDeviceInfo parameters of the IDirectPlay8Client::Connect method. To pass the address objects to IDirectPlay8Client::Connect outside of the callback function, use IDirectPlay8Address::Duplicate or IDirectPlay8Address::AddRef to prevent the object from being destroyed and store the pointers using thread-safe code.

Any number of enumerations can be run concurrently. The pvUserContext value is provided in the message handler to help differentiate replies to different enumerations.

Because of the variation in the number of ways enumeration can happen, it is not recommended that an application attempt to specify dwEnumCount, dwRetryInterval, or dwTimeOut unless the application has some specific media knowledge. The only exception is if you want to have the enumeration continue until explicitly cancelled, then set dwEnumCount to INFINITE.

The default enumeration count and timeout values will cause IDirectPlay8Client::EnumHosts to complete within a reasonable amount of time. These values are set by the service provider, and can be obtained by calling IDirectPlay8Client::GetSPCaps. Asynchronous enumerations can be stopped at any time by calling IDirectPlay8Client::CancelAsyncOperation and either passing the handle returned in the pAsyncHandle parameter or setting the DPNCANCEL_ENUM flag in the dwFlags parameter. An enumeration can also be stopped by returning anything other than S_OK from the message handler when processing a DPN_MSGID_ENUM_HOSTS_RESPONSE message.

You might receive multiple DPN_MSGID_ENUM_HOSTS_RESPONSE messages from the same host during one enumeration session. The guidInstance member of the associated DPN_APPLICATION_DESC structure can be used to correlate these duplicate responses.

If you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag in dwFlags, the service provider might attempt to display a dialog box to ask the user to complete the address information. You must have a visible window present when the service provider tries to display the dialog box, or your application will lock.

Data Value Summary specifies the required addressing information for each service provider.

DPNERR_USERCANCEL will be returned if the enumeration is canceled by calling the IDirectPlay8Client::CancelAsyncOperation method or if DPN_OK is not returned when processing a DPN_MSGID_ENUM_HOSTS_RESPONSE message.