CPNatfwtDestroyProviderInstance Function

[This documentation is preliminary and is subject to change.]

The CPNatfwtDestroyProviderInstance function is called by a Provider to free system resources associated with a Provider instance by the Connectivity Platform (CP).

Syntax

VOID WINAPI CPNatfwtDestroyProviderInstance(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance
);

Parameters

Return Value

This function does not return a value.

Remarks

The CPNatfwtDestroyProviderInstance function is used by the Connectivity Platform feature supported on Windows 7 and later.

The Connectivity Platform (CP) provides a mechanism for specialized applications and services to provide custom network traversal of network address translation (NAT) and firewalls on Windows 7 and later. A Provider registers with the Connectivity Platform to provide network traversal for other applications that use standard Windows networking APIs such as Windows Sockets.

If a Provider attempts a registration using CPNatfwtRegisterProviderInstance and registration fails, depending on the particular failure code returned by the registration call the Provider has several options. The Provider can change parameters, wait for some timeout to expire, and try to register again. Instead, the Provider can call the CPNatfwtDestroyProviderInstance function to free resources.

In the case where registration succeeded, the Provider eventually has to either deregister the provider instance using the CPNatfwtDeregisterProviderInstance function, or wait for the Connectivity Platform to initiate the instance deregistration so the Provider calls CPNatfwtDeregisterProviderInstance, before calling the CPNatfwtDestroyProviderInstance function to free the resources associated with the Provider instance.

The CPNatfwtDestroyProviderInstance function doesn’t have reference counting semantics and must not be called more than once for the same Provider instance. The suggested usage of this function together with the deregistration function is described in more detail in the Remarks for CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function supplied by the Provider as a session termination handler.

In the case where the Iphlpapi.dll is loaded by a Provider dynamically, the Provider can safely unload iphlpapi.dll only after all the created Provider instances have been destroyed using the CPNatfwtDestroyProviderInstance function.

Requirements

Minimum supported client Windows 7
Minimum supported server None supported
Header Iphlpapi.h (include Iphlpapi.h)
Library Iphlpapi.lib
DLL Iphlpapi.dll

See Also

CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION
CPNatfwtCreateProviderInstance
CPNatfwtDeregisterProviderInstance
CPNatfwtRegisterProviderInstance

Send comments about this topic to Microsoft

Build date: 2/3/2009