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.
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 dwEnumPeriod, dwRetryInterval, or dwTimeOut unless the application has some specific media knowledge.
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.
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
- 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
- Pointer to an IDirectPlay8Address object that specifies the address of the computer that is hosting the application. If you specify NULL. DirectPlay will create an address. By default, DirectPlay will create the address from the pdpaddrDeviceInfo parameter. If you set the DPNENUMHOSTS_OKTOQUERYFORADDRESSING flag in dwFlags, the user can be queried for address information.
- pdpaddrDeviceInfo
- Pointer to an IDirectPlay8Address object that specifies the service provider and local device settings to use when enumerating.
- pvUserEnumData
- 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
- Variable of type DWORD that specifies the size of the data pointed at in the pvUserEnumData parameter.
- dwEnumCount
- 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
- 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
- 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
- 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
- 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
- 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. If the request is processed asynchronously, S_OK can return if the method is instantly processed. By default, this method is run asynchronously and generally returns DPNSUCCESS_PENDING or one of the following error values.
Remarks
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.
Windows NT/2000: Available as a redistributable for Windows 2000 and later.
Windows 95/98: Available as a redistributable for Windows 95 and later.
Header: Declared in Dplay8.h.