FILTER_PAUSE callback function

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(
  NDIS_HANDLE FilterModuleContext,
  PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

Parameters

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.

PauseParameters

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:

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

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

See Also

FilterAttach

FilterReceiveNetBufferLists

FilterRestart

FilterReturnNetBufferLists

FilterSendNetBufferLists

FilterSendNetBufferListsComplete

NDIS_FILTER_PAUSE_PARAMETERS

NDIS_OBJECT_HEADER

NdisFPauseComplete

NdisFReturnNetBufferLists

NdisFSendNetBufferListsComplete

NdisWriteEventLogEntry