Microsoft DirectX 9.0

IDirectPlay8Server::GetLocalHostAddresses Method

Retrieves the local addresses being used to host the session.


HRESULT GetLocalHostAddresses(      

    IDirectPlay8Address **const prgpAddress,     DWORD *const pcAddress,     const DWORD dwFlags );


[out] Address of a pointer to an array of IDirectPlay8Address objects that specify the local host addresses. You must release these objects when you no longer need them or you will create memory leaks.
[in, out] Maximum number of address objects that can be contained in the array pointed to by prgpAddress. If the buffer is too small, the method returns DPNERR_BUFFERTOOSMALL, and pcAddress will be set to the required value.
[in] The following flag can be specified when using the Transmission Control Protocol/Internet Protocol (TCP/IP) service provider. This method will return DPNERR_UNSUPPORTED if this flag is used with any other service provider.
Return all listening addresses combined into one IDirectPlay8Address object.

Return Value

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

DPNERR_INVALIDOBJECTThe Microsoft?DirectPlay?object pointer is invalid.
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.
DPNERR_INVALIDPOINTERPointer specified as a parameter is invalid.
DPNERR_UNINITIALIZEDThe requested object has not been initialized.
DPNERR_UNSUPPORTEDThe function or feature is not available in this implementation or on this service provider.


The most robust way to use this method is to first call it with pcAddress set to 0. When the method returns, pcAddress will point to the required value. You can use that value when you call the method for a second time to retrieve the information.

If DPNGETLOCALHOSTADDRESSES_COMBINED is specified, the address object returned will contain all listening server addresses. For example, the server might have multiple addresses if it is behind a Network Address Translation (NAT) device or if it has multiple network cards. In this case, players can connect to the server faster if they can try all of the addresses simultaneously. The application must provide its own mechanism for passing the combined address object to the connecting players. One way to do this is by using IDirectPlay8Address::GetURLA or IDirectPlay8Address::GetURLW and IDirectPlay8Address::BuildFromURLA or IDirectPlay8Address::BuildFromURLW to create a string to pass using a Web page or lobby mechanism.

© 2002 Microsoft Corporation. All rights reserved.