Expand Minimize

FwpmBfeStateSubscribeChanges0 function

The FwpmBfeStateSubscribeChanges0 function registers a callback function that is called whenever there is a change to the state of the filter engine.

Note  FwpmBfeStateSubscribeChanges0 is a specific version of FwpmBfeStateSubscribeChanges. See WFP Version-Independent Names and Targeting Specific Versions of Windows for more information.

Syntax


NTSTATUS NTAPI FwpmBfeStateSubscribeChanges0(
  _Inout_   void *deviceObject,
  _In_      FWPM_SERVICE_STATE_CHANGE_CALLBACK0 callback,
  _In_opt_  void *context,
  _Out_     HANDLE *changeHandle
);

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.

callback [in]

A pointer to a callout driver-provided service state change callback function. The filter engine calls this function whenever there is a change in the state of the filter engine.

A service-state-change callback function is declared as follows.


VOID NTAPI
callback(
    IN OUT void  *context,
    IN FWPM_SERVICE_STATE  newState
    );

Context

The pointer that was passed in the Context parameter when the callout driver called the FwpmBfeStateSubscribeChanges0 function.

newState

The new state of the filter engine. This parameter contains one of the following values:

FWPM_SERVICE_STOPPED

The filter engine is not running.

FWPM_SERVICE_START_PENDING

The filter engine is starting.

FWPM_SERVICE_STOP_PENDING

The filter engine is stopping.

FWPM_SERVICE_RUNNING

The filter engine is running.

context [in, optional]

A pointer to a callout driver-provided context that is passed to the callback function specified in the Callback parameter.

changeHandle [out]

A pointer to a variable that receives a handle that is associated with the registration of the callback function. A callout driver passes this handle to the FwpmBfeStateUnsubscribeChanges0 function to deregister the callback function.

Return value

The FwpmBfeStateSubscribeChanges0 function returns one of the following NTSTATUS codes:

Return codeDescription
STATUS_SUCCESS

The callback function was successfully registered.

Other status codes

An error occurred.

 

Remarks

A callout driver calls the FwpmBfeStateSubscribeChanges0 function to register a callback function that is called whenever there is a change to the state of the filter engine.

For example, a callout driver cannot open a session to the filter engine by calling the FwpmEngineOpen0 function unless the filter engine is currently running. A callout driver can use the FWPM_SERVICE_RUNNING notification to open a session to the filter engine so that it can make calls to the other Windows Filtering Platform management functions. Similarly, a callout driver can use the FWPM_SERVICE_STOP_PENDING notification to perform any cleanup before the filter engine is stopped.

A callout driver must call FwpmBfeStateSubscribeChanges0 before calling the FwpmBfeStateGet0 function to retrieve the current state of the filter engine. After the call to FwpmBfeStateSubscribeChanges0 returns, the callout driver can call FwpmBfeStateGet0 at any time.

A callout driver must deregister the callback function by calling the FwpmBfeStateUnsubscribeChanges0 function before the callout driver can be unloaded.

Note  

Do not call FwpmBfeStateUnsubscribeChanges0 from the callback function that you passed in the callback parameter. Doing so can cause a deadlock.

Requirements

Version

Available starting with Windows Vista.

Header

Fwpmk.h (include Fwpmk.h)

IRQL

PASSIVE_LEVEL

See also

FwpmBfeStateGet0
FwpmBfeStateUnsubscribeChanges0
FwpmEngineOpen0

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.