?/TD>
Microsoft DirectX 9.0

IDirectPlay8Peer::GetLocalHostAddresses Method


Retrieves the local addresses being used to host the session.

Syntax

HRESULT GetLocalHostAddresses(      

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

Parameters

prgpAddress
[out] 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.
pcAddress
[in, out] Maximum number of address objects that can be returned in the array pointed to by prgpAddress. If the buffer is too small, this method returns DPNERR_BUFFERTOOSMALL and this parameter contains the required size.
dwFlags
[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.
DPNGETLOCALHOSTADDRESSES_COMBINED
Return all listening addresses combined into one IDirectPlay8Address object.

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_INVALIDOBJECTThe Microsoft?DirectPlay?object pointer is invalid.
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.
DPNERR_NOTHOSTThe client attempted to connect to a nonhost computer. Additionally, this error value may be returned by a nonhost that tried to set the application description.


Remarks

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

If the caller is not the session host, the method returns DPNERR_NOTHOST. Use IDirectPlay8Peer::GetPeerAddress to retrieve the address of a remote player.

If DPNGETLOCALHOSTADDRESSES_COMBINED is specified, the address object returned will contain all listening host addresses. For example, the host 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 host 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.