CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION Function Pointer

Article
02/03/2009

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

The CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function is called by the Connectivity Platform (CP) after a successful Provider registration to establish a session with a Provider instance and notify the Provider.

Syntax

typedef VOID ( CALLBACK *CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION )(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in  PVOID providerInstanceUserContext
);

Parameters

providerInstance [in]
A handle 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 Provider when the Provider instance was created using the CPNatfwtCreateProviderInstance function.

Return Value

This function pointer does not return a value.

Remarks

The CPNATFWT_PROVIDER_ESTABLISH_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_ESTABLISH_SESSION_INDICATION function is called by the Connectivity Platform to establish a session with a Provider instance and notify the Provider. This function is called by CP after a Provider has successfully creating a Provider Instance object using the CPNatfwtCreateProviderInstance function and successfully registered with CP using the CPNatfwtRegisterProviderInstance function.

The CP calls the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function after the successful Provider requested registration of the Provider instance with CP, but before the registration call might have completed.

The Provider may perform or schedule to be performed asynchronously some initialization actions when CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION is called. These initialization actions may include the following:

Allocate any memory needed, which may be delayed.
Open a control channel to cloud services, if the Provider chooses to ignore dormancy notifications.

The call by CP to CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION to establish a session is always expected to succeed. So this function has no return value. If the Provider is unable to perform the minimal initialization required, the Provider can fail a transition to active state later when it receives a call to the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function.

CP provides the following guarantees when CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION is called:

The CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function is called only if registration succeeded and the call to the CPNatfwtRegisterProviderInstance function will return or has returned success (S_OK).
Other calls from CP to the Provider will be made only after the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function has returned.
The Provider can call other CP functions after receiving a call to CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION. These calls to CP can be made before the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function returns. However, these calls to other CP functions may be pended and executed after the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION returns.

Note The CPNatfwtIndicateReceivedBuffers function will return an error if the Provider instance is not in an active state (has received a call from CP to the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function).

Requirements

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