FwpsPendOperation0 (Compact 2013)

3/26/2014

This function suspends packet processing, pending completion of another operation.

Syntax

NTSTATUS NTAPI
  FwpsPendOperation0(
    IN HANDLE  completionHandle,
    OUT HANDLE  *completionContext
    );

Parameters

• completionHandle
  A completion handle that is required to pend the current filtering operation. This parameter is obtained from the completionHandle member of the FWPS_INCOMING_METADATA_VALUES0 structure that is passed into the callout's classifyFn function.

• completionContext
  The handle to the completion context of this pend operation. When the callout is ready to resume packet processing, it calls the FwpsCompleteOperation0 function with the value of this parameter.

Return Value

The FwpsPendOperation0 function returns one of the following NTSTATUS codes:

Value	Description
STATUS_SUCCESS	Packet processing was successfully pended.
STATUS_FWP_CANNOT_PEND	A call was made to FwpsPendOperation0 in a reauthorization classify operation.
STATUS_FWP_NULL_POINTER	One or more parameters is invalid
STATUS_FWP_TCPIP_NOT_READY	The TCP/IP network stack is not ready to allow this operation
Other status codes	An error occurred

Remarks

The callout should keep the completionContext parameter value until it resumes packet processing. When the operation that prompted the call to this function has finished, the callout should call the FwpsCompleteOperation0 function, passing it the completionContext parameter value.

A callout can call this function to pend a packet that originates from the FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_Xxx, FWPM_LAYER_ALE_AUTH_LISTEN_Xxx, or FWPM_LAYER_ALE_AUTH_CONNECT_Xxx filtering layers only. A callout can pend the current processing operation on a packet when the callout must perform processing on one of these layers that may take a long interval to complete or that should occur at IRQL = PASSIVE_LEVEL if the current IRQL > PASSIVE_LEVEL.

To complete a connection that was previously pended at the FWPS_LAYER_ALE_AUTH_RECV_ACCEPT_Xxx layer, the callout must reinject the packet that was cloned at that layer and call the FwpsCompleteOperation0 function.

To pend packet processing, the callout's classifyFn function should set the actionType member of the FWPS_CLASSIFY_OUT0 structure to FWP_ACTION_BLOCK and the Flags member to FWPS_CLASSIFY_OUT_FLAG_ABSORB.

Pended connections are reauthenticated after the FwpsCompleteOperation0 function executes. TCP connections, if they are allowed, are created by completing the handshake operation. Non-TCP connections create state entries. Any pended packet data is flushed from memory when the FwpsPendOperation0 function is completed. Applications must retransmit those packets after FwpsCompleteOperation0 executes. Callouts can buffer such data and reinject the data on behalf of the applications.

Only an initial ALE flow authorization can be postponed by calling FwpsPendOperation0 and FwpsCompleteOperation0. If an ALE flow is reauthorized, the FWP_CONDITION_FLAG_IS_REAUTHORIZE flag is set. A call to FwpsPendOperation0 from the FWPM_LAYER_ALE_AUTH_CONNECT_Xxx or FWPM_LAYER_ALE_AUTH_RECV_ACCEPT_Xxx filtering layers will fail if the FWP_CONDITION_FLAG_IS_REAUTHORIZE flag is set, and the STATUS_FWP_CANNOT_PEND status code will be returned.

Requirements

Header

fwpsk.h

See Also

Reference

Functions Called by Callout Drivers
FWPS_CLASSIFY_OUT0
FWPS_INCOMING_METADATA_VALUES0
classifyFn
FwpsCompleteOperation0
WFP Callout Driver Functions