FILTER_PAUSE callback function (ndis.h)

Article
11/25/2021

NDIS calls a filter driver's FilterPause function to initiate a pause operation for the specified filter module.

Note You must declare the function by using the FILTER_PAUSE type. For more information, see the following Examples section.

Syntax

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Parameters

[in] FilterModuleContext

A handle to the context area for the filter module that the filter driver should pause. The filter driver created and initialized this context area in the FilterAttach function.

[in] PauseParameters

A pointer to an NDIS_FILTER_PAUSE_PARAMETERS structure that defines the pause parameters for the filter module.

Return value

NDIS drivers cannot fail a pause request. The filter driver should call the NdisWriteEventLogEntry function together with parameters that specify the reason for any errors that occur.

Return code	Description
NDIS_STATUS_SUCCESS	FilterPause successfully paused the specified filter module.
NDIS_STATUS_PENDING	The filter driver will complete the request asynchronously with a call to the NdisFPauseComplete function.

Remarks

FilterPause is a required function. NDIS can call FilterPause when the filter module is in the Running state. The filter module enters the Pausing state at the start of execution in the FilterPause function.

A filter driver performs the following operations when NDIS calls FilterPause:

Must call the NdisFSendNetBufferListsComplete function for any queued send buffers that an overlying driver created.
Must call the NdisFReturnNetBufferLists function for any queued receive buffers that an underlying driver created.
Must wait for NDIS to return all outstanding send requests that the driver originated to the FilterSendNetBufferListsComplete function.
Must wait for NDIS to return all outstanding receive indications that the driver originated to the FilterReturnNetBufferLists function.

After the filter driver returns NDIS_STATUS_SUCCESS from FilterPause or calls the NdisFPauseComplete function, the pause operation is complete. The filter module is in the Paused state.

In the Pausing or Paused states, a filter driver should continue to handle OID requests or status indications. The driver should reject calls to its FilterSendNetBufferLists function. The driver can pass on calls to its FilterReceiveNetBufferLists function. However, the driver cannot pass any buffers that it created. The driver must not originate any receive indications or send requests.

In the Paused state, the filter module must not generate send requests or receive indications.

NDIS calls the FilterRestart function to initiate a restart request for a filter module that is in the Paused state.

NDIS calls FilterPause at IRQL = PASSIVE_LEVEL.

Examples

To define a FilterPause function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a FilterPause function that is named "MyPause", use the FILTER_PAUSE type as shown in this code example:

FILTER_PAUSE MyPause;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

The FILTER_PAUSE function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the FILTER_PAUSE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL