CPNATFWT_PROVIDER_ADD_TRANSPORT_ID Function Pointer

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

The CPNATFWT_PROVIDER_ADD_TRANSPORT_ID function is called by the Connectivity Platform (CP) to associate a transport ID with the Provider instance.

Syntax

typedef HRESULT ( CALLBACK *CPNATFWT_PROVIDER_ADD_TRANSPORT_ID )(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in  PVOID providerInstanceUserContext,
  __in  CPNATFWT_TRANSPORT_ID *transportId,
  __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.

  • transportId [in]
    A pointer to the transport ID to associate with the Provider instance.

    A CPNATFWT_TRANSPORT_ID structure represents a binary data blob that is used as an identifier for data exchange between Provider instances. The Provider uses the transport ID to ensure that there are no duplicate addresses.

  • 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_ADD_TRANSPORT_ID function asynchronously .

    This parameter can be ignored if the Provider executes the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID 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_ADD_TRANSPORT_ID function asynchronously. In this case, the Provider returns HRESULT_FROM_WIN32(ERROR_IO_PENDING) to CP from the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID 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_ADD_TRANSPORT_ID function synchronously .

Return Value

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

If the Provider executes CPNATFWT_PROVIDER_ADD_TRANSPORT_ID 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_ADD_TRANSPORT_ID 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_DUP_NAME

A duplicate name exists on the network. This error is returned if a conflict was detected with the pointer to the transport ID in the transportId parameter and an existing transport ID of a peer reachable from the given Provider instance.

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_ADD_TRANSPORT_ID 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, ERROR_IO_PENDING, and ERROR_DUP_NAME as an indication of failure.

Remarks

The CPNATFWT_PROVIDER_ADD_TRANSPORT_ID 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_ADD_TRANSPORT_ID function is called by the Connectivity Platform to associate a transport ID with the Provider instance. A transport ID corresponds to assigning an IPv4 or IPv6 address to the associated network interface. Once the Provider instance is in an active state, CP can make one or more calls to the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID function to associate transport IDs with the Provider instance.

As part of the transport ID association, the Provider instance is assumed to perform some form of conflict detection to ensure that transport IDs of peers reachable from the given Provider instance (and potentially of their peers) do not conflict with the transport ID pointed to by the transportId parameter supplied by CP. If there is no conflict and the ID was successfully assigned, the call to the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID function should succeed. If there is a conflict, the Provider should return HRESULT_FROM_WIN32(ERROR_DUP_NAME) and CP will generate a new transport ID and retry the call. If the call fails for any other reason or all CP attempts to add a transport ID fail due to conflicts, the Provider will stay dormant.

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, HRESULT_FROM_WIN32(ERROR_DUP_NAME) for a transport ID conflict, or any other 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, HRESULT_FROM_WIN32(ERROR_DUP_NAME), or some error code on 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_ADD_TRANSPORT_ID function. This parameter is used by CP to identify the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID call that the completion routine is responding to.

status

This parameter contains the final completion status of the CPNATFWT_PROVIDER_ADD_TRANSPORT_ID 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.

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_REMOVE_TRANSPORT_ID
CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION
CPNATFWT_PROVIDER_TRANSITION_ACTIVE
CPNATFWT_PROVIDER_TRANSITION_DORMANT
CPNATFWT_TRANSPORT_ID
CPNatfwtCreateProviderInstance
CPNatfwtRegisterProviderInstance

Send comments about this topic to Microsoft

Build date: 2/3/2009