CPNATFWT_PROVIDER_TRANSITION_ACTIVE Function Pointer

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

The CPNATFWT_PROVIDER_TRANSITION_ACTIVE function is called by the Connectivity Platform (CP) to transition the Provider to the active state.

Syntax

typedef HRESULT ( CALLBACK *CPNATFWT_PROVIDER_TRANSITION_ACTIVE )(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in  PVOID providerInstanceUserContext,
  __in  PVOID completionContext,
  __in  CPNATFWT_PLATFORM_COMPLETION_ROUTINE completionRoutine
);

Parameters

  • providerInstance [in]
    A handle to the Provider instance object previously returned to the Provider by the CPNatfwtCreateProviderInstance function and used by the Provider to register 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.

  • completionContext [in]
    Context data supplied by CP that is passed to the completion routine pointed to by the completionRoutine parameter if the Provider executes the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function asynchronously .

    This parameter can be ignored if the Provider executes the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function synchronously .

  • completionRoutine [in]
    A pointer to the completion routine supplied by CP that the Provider calls to complete this call if the Provider executes the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function asynchronously. In this case, the Provider returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) to CP from the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function to pend the call and indicate to CP that the call will be completed asynchronously.

    This parameter can be ignored if the Provider executes the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function synchronously .

Return Value

If the Provider executes CPNATFWT_PROVIDER_TRANSITION_ACTIVE synchronously, this function returns S_OK if the call succeeds.

If the Provider executes CPNATFWT_PROVIDER_TRANSITION_ACTIVE asynchronously, this function returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) to indicate the operation is in progress. The results of the function are supplied later when the completion routine pointed to by the completionRoutine parameter is called by the Provider. The results are returned to CP in the status parameter passed to the completion routine. If the function succeeds, S_OK should be returned in the status parameter. If the function fails, the specific error code should be returned in the status parameter. The specific error may be determined from the HRESULT returned.

If the Provider executes CPNATFWT_PROVIDER_TRANSITION_ACTIVE synchronously and the function fails, the return value in the HRESULT indicates the error. The specific error may be determined from the HRESULT returned.

For Windows system errors, the HRESULT returned by the Provider should be generated using the HRESULT_FROM_WIN32 inline function or macro defined in the Winerror.h header file. When the HRESULT indicates a FACILITY_WIN32 error, the lower 16 bits should contain the Windows system error.

Return code Description

ERROR_IO_PENDING

An operation is in progress.

This value is returned if the Provider executes the function asynchronously. The results of the function are supplied later when the completion routine pointed to by the completionRoutine parameter is called by the Provider. In this case, the Provider returns without waiting for the associated activities to complete for processing the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function.

Other

The Provider may return a variety of error codes on failure (E_FAIL, for example). CP treats any return value other than S_OK or ERROR_IO_PENDING as an indication of failure.

Remarks

The CPNATFWT_PROVIDER_TRANSITION_ACTIVE 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_TRANSITION_ACTIVE function is called by the Connectivity Platform to transition the Provider to an active state. This can be a caused by an outgoing packet sent over any of the CP interfaces, by a listening application with permitting edge traversal policy, or by a notification from the NotifyStableUnicastIpAddressTable function. By default, the Provider instance is assumed to be in a dormant state that implies it might lack an active connection to its infrastructure.

Depending on the usage pattern by network applications leveraging CP, the CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION function is called followed later by the call to CPNATFWT_PROVIDER_TRANSITION_ACTIVE.

If the Provider is unable to perform the minimal initialization required to establish a session, the Provider should fail a transition to active state when it receives a call to the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function.

The Provider is not required to implement anything specific for dormancy. However the presence of active and dormant transition notifications from CP may allow advanced Providers to utilize applicable server and network infrastructure more efficiently

If the Provider implements the notion of being dormant or active, the Provider instance can implement any required actions to transition to active state when the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function is called by CP. These actions might include opening a control channel with its cloud infrastructure or scheduling to do so asynchronously (return with ERROR_IO_PENDING and complete the call later). If the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function eventually completes with success, the Provider should be able to send and receive traffic to peers.

The CPNATFWT_PROVIDER_TRANSITION_ACTIVE function is normally expected to succeed. If the Provider fails the call for any reason, CP will interpret this as some issue with Provider infrastructure. If this function fails, CP will initiate session termination and calls the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION function.

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.

Many of callback functions exposed by the Provider via dispatch table have completionContext and completionRoutine parameters, which allow the Provider to return from that function asynchronously before the associated activities actually complete. The Provider can inform CP about their completion later by calling the corresponding completion routine with corresponding completion context to provide CP a return value.

The Provider is allowed to complete a call in any of the following ways:

  • Complete the call synchronously and return any HRESULT except for HRESULT_FROM_WIN32(ERROR_IO_PENDING). The Provider returns S_OK for success or an error code for failure. In this case, it is illegal for the Provider to later call the completion routine passed in the completionRoutine parameter.
  • Complete the call asynchronously and return HRESULT_FROM_WIN32(ERROR_IO_PENDING). In parallel or later, the Provider calls the completion routine passed in the completionRoutine parameter and provides the completion status (S_OK for success or an error code for failure).

Note  Note if the Provider pends the call by returning HRESULT_FROM_WIN32(ERROR_IO_PENDING), all function parameters that are pointers (all input parameters that are pointers) will remain valid until the Provider calls the corresponding completion routine. The Provider must never assume availability of these parameters once it invokes completion routine.

The CP completion routine pointed to by the completionRoutine is defined as a function of type VOID with the following syntax:

typedef
VOID 
(WINAPI *CPNATFWT_PLATFORM_COMPLETION_ROUTINE) (
    __in PVOID completionContext,
    __in HRESULT status
    );

The parameters passed to the completion routine include the following:

Parameter Description

completionContext

The completionContext parameter passed to the CPNATFWT_PROVIDER_TRANSITION_ACTIVE function. This parameter is used by CP to identify the CPNATFWT_PROVIDER_TRANSITION_ACTIVE call that the completion routine is responding to.

status

This parameter contains the final completion status of the CPNATFWT_PROVIDER_TRANSITION_ACTIVE operation by the Provider.

The goal of supporting asynchronous call completion is to minimize blockage of threads that make the calls.

Independently of whether a call exited synchronously or was completed asynchronously, if the call completion from the Provider doesn’t occur in a timely manner, CP will initiate a session termination with the Provider (call the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION). This action is designed to prevent excessive resource consumption by a Provider.

Note  The CPNatfwtIndicateReceivedBuffers function will return an error if the Provider instance is not in an active state (returned success to 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)

See Also

CPNATFWT_PROVIDER_ESTABLISH_SESSION_INDICATION
CPNATFWT_PROVIDER_INSTANCE_DISPATCH_TABLE
CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION
CPNatfwtCreateProviderInstance
CPNatfwtRegisterProviderInstance
NotifyStableUnicastIpAddressTable

Send comments about this topic to Microsoft

Build date: 2/3/2009