IDirectPlayNATHelp::GetCaps Method

Retrieves the capabilities of the Internet gateway server(s) and information about leased ports.

Syntax

HRESULT GetCaps(      

    PPDPNHCAPS *const pdpnhcaps,
    const DWORD dwFlags
);

Parameters

pdpnhcaps

[in] Pointer to a DPNHCAPS structure to be filled with Network Address Translation (NAT) helper's capabilities. The dwSize member of the structure must be set.

dwFlags

[in] May be the following value.

DPNHGETCAPS_UPDATESERVERSTATUS

Automatically extend expiring leases and detect changes in the server status.

Return Value

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

DPNHERR_GENERIC	An error occurred while closing.
DPNHERR_INVALIDFLAGS	Invalid flags were specified.
DPNHERR_INVALIDOBJECT	The interface object is invalid.
DPNHERR_INVALIDPARAM	An invalid parameter was specified.
DPNHERR_INVALIDPOINTER	An invalid pointer was specified.
DPNHERR_NOTINITIALIZED	The object has not been initialized.
DPNHERR_OUTOFMEMORY	There is not enough memory to perform this operation.
DPNHERR_REENTRANT	The interface has been re-entered on the same thread.

Remarks

This method should be called periodically with the DPNHGETCATS_UPDATESERVERSTATUS flag set to automatically extend port leases that are about to expire. The DPNHGETCATS_UPDATESERVERSTATUS flag also causes detection of changes in the status of the servers since the last call to IDirectPlayNATHelp::GetCaps. If a new server becomes available, an existing server becomes unavailable, or a server's public address changes in a way that affects an existing registered port mapping, then DPNHSUCCESS_ADDRESSESCHANGED is returned instead of DPNH_OK.

If DPNHSUCCESS_ADDRESSESCHANGED is returned, the user should call IDirectPlayNATHelp::GetRegisteredAddresses to update port binding information.

When the DPNHGETCATS_UPDATESERVERSTATUS flag is set, this method may stall while attempts are made to communicate with the server.

This method must be called with the DPNHGETCATS_UPDATESERVERSTATUS flag set at least once before calling IDirectPlayNATHelp::GetRegisteredAddresses or IDirectPlayNATHelp::QueryAddress.