CPNATFWT_PROVIDER_SEND_BUFFERS Function Pointer

Article
02/03/2009

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

The CPNATFWT_PROVIDER_SEND_BUFFERS function is called by the Connectivity Platform (CP) to send data when there is outgoing traffic generated by an application to a destination transport ID reachable over the Provider instance.

Syntax

typedef HRESULT ( CALLBACK *CPNATFWT_PROVIDER_SEND_BUFFERS )(
  __in  CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in  PVOID providerInstanceUserContext,
  __in  CPNATFWT_TRANSPORT_ID *localTransportId,
  __in  CPNATFWT_TRANSPORT_ID *remoteTransportId,
  __in  UINT64 endpointLuid,
  __in  CPNATFWT_BUFFER bufferChain,
  __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.
localTransportId [in]
A pointer to the transport ID that represents the source address in the data exchange between the local and remote Provider instances. In the context of this function, the source address represents the address of the local Provider instance.

A CPNATFWT_TRANSPORT_ID structure represents a binary data BLOB that is used as an identifier for data exchange between Provider instances.
remoteTransportId [in]
A pointer to the transport ID that represents the destination address in the data exchange between the local Provider instance and the remote provider. In the context of this function, the destination address represents the address of the remote Provider instance.

A CPNATFWT_TRANSPORT_ID structure represents a binary data BLOB that is used as an identifier for data exchange between Provider instances.
endpointLuid [in]
The LUID of the application endpoint in Windows Filtering Platform.

This parameter is an identifier of application endpoint that originated the data sent. This identifier can be used by the Provider to call FwpsAleEndpointGetById0 and FwpsOpenToken0 functions, which are new functions added to the Windows Filtering Platform API on Windows 7 and later. Using these functions, the Provider can retrieve the access token of the application, and use it to retrieve run-time application-specific information such as the user SID. This can be used by the Provider to implement different level of services for different clients (applications or users, if the corresponding IP interface was configured to be usable by multiple users).
bufferChain [in]
A pointer to a buffer or a chain of buffers that is used for the data exchange between the local Provider instance and the remote provider.
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_SEND_BUFFERS function asynchronously .

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

Return Value

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

If the Provider executes CPNATFWT_PROVIDER_SEND_BUFFERS 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_SEND_BUFFERS 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_SEND_BUFFERS 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.

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_SEND_BUFFERS 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_SEND_BUFFERS 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_SEND_BUFFERS function is called by the Connectivity Platform when there is outgoing traffic generated by an application and the Connectivity Platform has determined that the destination transport ID is unambiguously reachable over the Provider instance. The CPNATFWT_PROVIDER_SEND_BUFFERS function attempts to send data buffers to the destination transport ID.

The Provider instance is expected to complete the CPNATFWT_PROVIDER_SEND_BUFFERS with success. The successful completion however doesn’t necessarily mean that the passed buffer chain has been transferred to the peer. Instead, the Provider instance is expected to implement IP-protocol style semantics. The delivery of data shall be performed in the best effort manner. However there are no guarantees that a particular buffer is actually delivered to the destination.

If data is delivered, however, the buffers are expected to be delivered to the peer in the same order and with the same message boundaries as passed to the CPNATFWT_PROVIDER_SEND_BUFFERS function. Reordering will not cause session termination, however depending on the application traffic patterns, it can limit maximum achievable data throughput.

Depending on the characteristics of the underlying data channel, the Provider instance may decide to perform the data transfer synchronously, or it can queue the buffers and pend the call as asynchronous. If the Provider instance can’t perform the data transfer due to a temporary failure condition, but this condition may recover in the future, the Provider instance should drop buffers, rather than completing the call with failure. Completing this call with failure will initiate session termination.

In case some failure happens, the Provider instance has discretion to decide whether a failure in a particular packet transmission is permanent and justifies deregistration from CP, or may be transient and the communication channel is likely to recover soon, and hence the CPNATFWT_PROVIDER_SEND_BUFFERS call shall be completed with success.

If due to communication channel conditions the Provider expects that transmission of packet may take longer than allowed by CP for the CPNATFWT_PROVIDER_SEND_BUFFERS call to complete, the Provider can make a copy of buffers and return success to CP.

If the CPNATFWT_PROVIDER_SEND_BUFFERS function fails, the Provider may return an appropriate error code. CP considers this a Provider infrastructure failure and will initiate session termination by calling the CPNATFWT_PROVIDER_TERMINATE_SESSION_INDICATION 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_SEND_BUFFERS function. This parameter is used by CP to identify the CPNATFWT_PROVIDER_SEND_BUFFERS call that the completion routine is responding to.
status	This parameter contains the final completion status of the CPNATFWT_PROVIDER_SEND_BUFFERS 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)