IDirectPlay8Client::EnumHosts

Enumerates applications that host Microsoft® DirectPlay® games. 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.

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 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 DPENUM_CANCEL 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.

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 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. DirectPlay makes a copy of this data when EnumHosts is called and therefore the application can modify or change the data when EnumHosts returns, regardless or whether the call is made synchronously or asynchronously.

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, phAsyncHandle 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 Values

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.

Remarks

To ensure better network address translation (NAT) and proxy support when using the 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 Connect method. To pass the address objects to 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.

You may receive multiple DPN_MSGID_ENUM_HOSTS_RESPONSE messages from the same host during one EnumHosts 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 may 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.

Requirements

  Windows NT/2000/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dplay8.h.