FwpsCalloutRegister2 function (fwpsk.h)
The FwpsCalloutRegister2 function registers a callout with the filter engine.
Syntax
NTSTATUS FwpsCalloutRegister2(
[in, out] void *deviceObject,
[in] const FWPS_CALLOUT2 *callout,
[out, optional] UINT32 *calloutId
);
Parameters
[in, out] deviceObject
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.
[in] callout
A pointer to a constant FWPS_CALLOUT2 structure that contains the data that is required to register the callout with the filter engine.
[out, optional] calloutId
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 FwpsCalloutRegister2 function returns one of the following NTSTATUS codes.
| Return code | Description |
|---|---|
|
The callout was successfully registered with the filter engine. |
|
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_CALLOUT2 structure pointed to by the callout parameter. |
|
An error occurred. |
Remarks
A callout driver calls the FwpsCalloutRegister2 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.
This function is essentially identical to the previous version, FwpsCalloutRegister1. The only difference is the updated FWPS_CALLOUT2 structure pointed to by the callout parameter.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available starting with Windows 8. |
| Target Platform | Universal |
| Header | fwpsk.h (include Fwpsk.h) |
| Library | Fwpkclnt.lib |
| IRQL | PASSIVE_LEVEL |