IDirectPlay8Server::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] 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.

pcAddress

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

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_INVALIDOBJECT	The Microsoft?DirectPlay?object pointer is invalid.
DPNERR_BUFFERTOOSMALL	The supplied buffer is not large enough to contain the requested data.
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.

Remarks

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.