CPNatfwtIndicateReceivedBuffers Function

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

The CPNatfwtIndicateReceivedBuffers function is called by a Provider instance to indicate that received buffers are available to the Connectivity Platform (CP).

Syntax

HRESULT WINAPI CPNatfwtIndicateReceivedBuffers(
  __in      CPNATFWT_PROVIDER_INSTANCE providerInstance,
  __in      CPNATFWT_TRANSPORT_ID *localTransportId,
  __in      CPNATFWT_TRANSPORT_ID *remoteTransportId,
  __in      CPNATFWT_BUFFER *bufferChain,
  __in_opt  PVOID completionContext,
  __in_opt  CPNATFWT_PROVIDER_COMPLETION_ROUTINE completionRoutine
);

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.

  • localTransportId [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 instance. In the context of this function, the destination 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 source address in the data exchange between the local Provider instance and the remote Provider instance. In the context of this function, the source 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.

  • 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 instance.

  • completionContext [in, optional]
    An optional completion context that is to be passed back to the Provider’s completion routine when the Connectivity Platform completes processing the data buffers. This parameter is ignored if the completionRoutine parameter is NULL.

  • completionRoutine [in, optional]
    An optional completion routine provided by the Provider instance that is to be called by the Connectivity Platform when the CP completes processing the data buffers.

    If this parameter is NULL, CP will complete data processing before returning from the CPNatfwtIndicateReceivedBuffers call.

Return Value

When called synchronously (the completionRoutine parameter is NULL), the CPNatfwtIndicateReceivedBuffers function returns S_OK if the call succeeds.

When called asynchronously (the completionRoutine parameter points to a completion routine supplied by the Provider), the CPNatfwtIndicateReceivedBuffers function returns ERROR_IO_PENDING to indicate the operation is in progress. The results can be retrieved later when the completion routine pointed to by the completionRoutine parameter is called.

If the function fails, the return value indicates the error. The specific error may be determined from the HRESULT returned. For Windows system errors, the returned HRESULT is 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 contain the Windows system error. The possible errors returned in the HRESULT may be one of the following return codes.

Return code Description

ERROR_GEN_FAILURE

A device attached to the system is not functioning.

This error is returned if an RPC error occurred or a general failure occurred.

ERROR_INVALID_PARAMETER

A parameter is incorrect. This error is returned if any of the following conditions occur:

  • The providerInstance parameter is NULL.
  • The localTransportId parameter is NULL.
  • The remoteTransportId parameter is NULL.
  • The bufferChain parameter is NULL.
  • The size member of the CPNATFWT_TRANSPORT_ID structure pointed to by the localTransportId parameter is greater than 16.

ERROR_IO_PENDING

An operation is in progress.

This value is returned if the Provider instance passed a pointer to a completion routine in the completionRoutine parameter. In this case, the CP returns without waiting for completion of processing by CP components from the CPNatfwtIndicateReceivedBuffers call and later calls the completion routine in the completionRoutine parameter when the CP has finished processing data.

ERROR_NOT_ENOUGH_MEMORY

Not enough storage is available to process this command.

Remarks

The CPNatfwtIndicateReceivedBuffers function is used by 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 CPNatfwtIndicateReceivedBuffers function is called by a Provider instance when it receives data from a peer to indicate that received buffers are available to the Connectivity Platform (CP).

To minimize the blockage of threads that make the CPNatfwtIndicateReceivedBuffers calls on the receive data path, the Provider can supply CP with a pointer to a completion routine in the completionRoutine parameter that will be called back asynchronously when CP is done processing the data buffers. If the completionRoutine parameter is not NULL, CP will return from the call with the HRESULT_FROM_WIN32(ERROR_IO_PENDING) return code. The Provider must guarantee that the localTransportId, remoteTransportId, and bufferChain parameters are valid until the completion routine is called back. Upon asynchronous completion of data processing, CP will call the completion routine and pass the context pointed to by the completionContext parameter to the Provider.

A typical implementation of the completion routine by the Provider can use the completionContext parameter to obtain pointers to the indicated data buffers and reclaim them.

If the completionRoutine parameter is NULL, CP will complete processing data synchronously before returning from the CPNatfwtIndicateReceivedBuffers function to the Provider.

The CPNatfwtIndicateReceivedBuffers call can fail with an appropriate error code (for example, a memory allocation was required and it failed). If the CPNatfwtIndicateReceivedBuffers call fails, the HRESULT returned indicates the error. It is up to the discretion of the Provider how to handle such failures (whether to ignore the error as a transient condition, or initiate deregistration using CPNatfwtDeregisterProviderInstance).

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

typedef
VOID 
(CALLBACK *CPNATFWT_PROVIDER_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 CPNatfwtIndicateReceivedBuffers function. This parameter can be used by the Provider instance to identify the CPNatfwtIndicateReceivedBuffers call that the completion routine is responding to.

status

This parameter contains the final completion status of the CPNatfwtIndicateReceivedBuffers operation by the Connectivity Platform.

The invocation of this completion routine may happen in the same thread as the original indication, or in a different thread. The Provider must be able to handle both cases.

The Provider should return control from this completion routine as soon as possible. For efficiency this completion routine may be executed from the internal CP data dispatch routines and delays will affect the maximum data throughput. If necessary, a Provider can schedule a work item when the completion routine is called (effectively treating this completion routine similar to an interrupt service routine).

Requirements

Minimum supported client Windows 7
Minimum supported server None supported
Header Iphlpapi.h (include Iphlpapi.h)
Library Iphlpapi.lib
DLL Iphlpapi.dll

See Also

CPNATFWT_BUFFER
CPNATFWT_TRANSPORT_ID
CPNatfwtCreateProviderInstance
CPNatfwtDeregisterProviderInstance
CPNatfwtRegisterProviderInstance

Send comments about this topic to Microsoft

Build date: 2/3/2009