CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION Function Pointer

Article
02/03/2009

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

The CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function is called by the Connectivity Platform (CP) to terminate a session with a Provider instance.

Syntax

typedef VOID ( CALLBACK *CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION )(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in  PVOID providerInstanceUserContext,
  __in  CPNATFWT_SESSION_TERMINATION_REASON terminationReason
);

Parameters

providerInstance [in]
A rhandle to the Provider instance object previously obtained using the CPNatfwtCreateProviderInstance function and registered with the CP using the CPNatfwtRegisterProviderInstance function.
providerInstanceUserContext [in]
A pointer to context data supplied by the Provider when the Provider instance was created using the CPNatfwtCreateProviderInstance function.
terminationReason [in]
The reason that the Connectivity Platform is terminating a session with the Provider instance. This parameter can be one of the values from the CPNATFWT_SESSION_TERMINATION_REASON enumeration type defined in the Iphlpapi.h header file.

Return Value

This function pointer does not return a value.

Remarks

The CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function is used for 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.

The CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function is called by the Connectivity Platform to terminate a previously establish session with a Provider instance. A session can be terminated as a result of a Provider request or for other reasons. This can include the following reasons:

The Connectivity Platform becoming unavailable.
A communication error.
A Non-timely completion of the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION call to the Provider.

This function is called by CP after a Provider has successfully created a Provider Instance object using the CPNatfwtCreateProviderInstance function and successfully registered with CP using the CPNatfwtRegisterProviderInstance function.

When CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION is called, the Provider can perform any relevant state changes and cleanup operations needed on the Provider instance. The Provider should ensure that no new calls to CP functions are initiated on this Provider instance when this call returns.

When CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION is called, CP makes sure that no further calls are made to the Provider. However, there may be some calls already initiated and in progress. These calls may include some calls which have not yet been delivered to the Provider by the operating system when CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION was invoked. The Provider is expected to immediately complete these outstanding calls and any delayed calls that might come later. The CPNatfwtDeregisterProviderInstance function will not complete until all outstanding and delayed calls finish.

A number of possible scenarios are discussed below that describe the relationship of this function and the CPNatfwtDeregisterProviderInstance function to deregister the Provider instance.

The Provider might have a dedicated message-loop like thread, which originally created and registered the Provider instance. The message-loop thread requested provider deregistration possibly based on user input which has lead to session termination, or some problem in interaction with CP occurred, which in turn has lead to the session termination. The CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function will be called, and the Provider can signal the message-loop thread that the Provider session is now terminated. In all cases, the Provider has to call the CPNatfwtDeregisterProviderInstance function in order to deregister this Provider instance.

If the Provider calls the CPNatfwtDeregisterProviderInstance function to deregister the Provider instance, CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION will be called by CP. After CPNatfwtDeregisterProviderInstance returns control, the Provider message-loop thread can either free the Provider instance or reuse it.

In case CP forces deregistration, the provider will need to call the CPNatfwtDeregisterProviderInstance function after CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION was called by CP, in order to be able to free or reuse the Provider instance. This must not be done from the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function directly, however. Instead, CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION would signal the message-loop thread or schedule a work item on a new thread, which would call CPNatfwtDeregisterProviderInstance. The CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function will not be called again in such cases, because it has already been called.

The Provider may perform some internal termination actions when CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION is called or after the Provider called CPNatfwtDeregisterProviderInstance and this function returned control. These actions may include the following:

Release previously allocated memory.
Close a control channel to cloud services.

CP specifies the reason for the session termination in the terminationReason parameter.

The call by CP to the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function to terminate a session is always expected to succeed. So this function has no return value.

Requirements

Minimum supported client	Windows 7
Minimum supported server	None supported
Header	Iphlpapi.h (include Iphlpapi.h)