Expand Minimize

FwpsCalloutRegister0 function

The FwpsCalloutRegister0 function registers a callout with the filter engine.

Note  FwpsCalloutRegister0 is the specific version of FwpsCalloutRegister used in Windows Vista and later. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information. For Windows 8, FwpsCalloutRegister2 is available. For Windows 7, FwpsCalloutRegister1 is available.

Syntax


NTSTATUS NTAPI FwpsCalloutRegister0(
  _Inout_    void *deviceObject,
  _In_       const FWPS_CALLOUT0 *callout,
  _Out_opt_  UINT32 *calloutId
);

Parameters

deviceObject [in, out]

A pointer to a device object that was previously created by the callout driver. For more information about how a callout driver creates a device object, see Creating a Device Object.

callout [in]

A pointer to a constant FWPS_CALLOUT0 structure that contains the data that is required to register the callout with the filter engine.

calloutId [out, optional]

A pointer to a UINT32-typed variable that receives a run-time identifier that identifies the callout in the filter engine. The callout driver passes this identifier to the FwpsCalloutUnregisterById0 function when unregistering the callout from the filter engine. If a callout driver is filtering a data flow, it also passes this identifier to the FwpsFlowAssociateContext0 and FwpsFlowRemoveContext0 functions. If a callout driver injects data into data streams, it also passes this identifier to the FwpsStreamInjectAsync0 function. The filter engine also passes this identifier to the callout driver's flowDeleteFn callout function. This parameter is optional and can be NULL.

Return value

The FwpsCalloutRegister0 function returns one of the following NTSTATUS codes.

Return codeDescription
STATUS_SUCCESS

The callout was successfully registered with the filter engine.

STATUS_FWP_ALREADY_EXISTS

The callout could not be registered with the filter engine. A callout is already registered in the filter engine with an identifier identical to the GUID specified in the calloutKey member of the FWPS_CALLOUT0 structure pointed to by the callout parameter.

Other status codes

An error occurred.

 

Remarks

A callout driver calls the FwpsCalloutRegister0 function to register a callout with the filter engine. A callout driver can register a callout with the filter engine at any time, even if the filter engine is not currently running.

A callout and filters that specify the callout for the filter's action can be added to the filter engine before a callout driver registers the callout with the filter engine. In this situation, filters with an action type of FWP_ACTION_CALLOUT_TERMINATING or FWP_ACTION_CALLOUT_UNKNOWN are treated as FWP_ACTION_BLOCK, and filters with an action type of FWP_ACTION_CALLOUT_INSPECTION are ignored until the callout is registered with the filter engine.

A callout driver unregisters a callout from the filter engine by calling either the FwpsCalloutUnregisterById0 function or the FwpsCalloutUnregisterByKey0 function. A callout driver cannot be unloaded until all of the callouts that were previously registered with the filter engine have been successfully unregistered.

Requirements

Version

Available starting with Windows Vista.

Header

Fwpsk.h (include Fwpsk.h)

Library

Fwpkclnt.lib

IRQL

PASSIVE_LEVEL

See also

FWPS_CALLOUT0
FwpsCalloutUnregisterById0
FwpsCalloutUnregisterByKey0
FwpsFlowAssociateContext0
FwpsFlowRemoveContext0
FwpsStreamInjectAsync0
IoCreateDevice
flowDeleteFn
Creating a Device Object
Types of Callouts

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft