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_BUFFERTOOSMALL	The supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDOBJECT	The Microsoft® DirectPlay® object pointer is invalid.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_INVALIDPOINTER	Pointer specified as a parameter is invalid.
DPNERR_UNINITIALIZED	The requested object has not been initialized.
DPNERR_UNSUPPORTED	The function or feature is not available in this implementation or on this service provider.
DPNERR_NOTHOST	The 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 calling application 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.