Edit

Pausing a Filter Module

  • Article

To pause a running filter module, NDIS calls the filter driver's FilterPause function. The filter module enters the Pausing state at the start of execution in the FilterPause function.

NDIS pauses a filter module as part of a Plug and Play operation to pause a driver stack. For an overview of pausing the driver stack, see Pausing a Driver Stack.

On behalf of a filter module that is in the Pausing state, the filter driver:

  • Should not originate any new receive indications.

    For more information about send and receive operations, see Filter Module Send and Receive Operations.

  • If there are receive operations that the filter driver originated and that NDIS has not completed, the filter driver must wait for NDIS to complete such operations. The pause operation is not complete until NDIS calls the FilterReturnNetBufferLists function for all such outstanding receive indications.

  • Should return any outstanding receive indications that underlying drivers originated to NDIS immediately. The pause operation is not complete until the driver calls the NdisFReturnNetBufferLists function for such outstanding receive indications. These outstanding receive indications can exist if the driver queues the buffers that it receives from underlying drivers.

  • Should return new receive indications that underlying drivers originate to NDIS immediately by calling the NdisFReturnNetBufferLists function. If necessary, the driver can copy receive indications and queue them before it returns them.

    Note  NdisFReturnNetBufferLists should not be called for NBLs indicated with NDIS_RECEIVE_FLAGS_RESOURCES flag set in a corresponding FilterReceiveNetBufferLists call. Such NBLs are returned to NDIS synchronously by returning from the FilterReceiveNetBufferLists routine.

  • Should not originate any new send requests.

  • If there are send operations that the filter driver originated and that NDIS has not completed, the filter driver must wait for NDIS to complete such operations. The pause operation is not complete until NDIS calls the FilterSendNetBufferListsComplete function for all such outstanding send requests.

  • Should return all new send requests made to its FilterSendNetBufferLists function immediately by calling the NdisFSendNetBufferListsComplete function. The filter driver should set the Status member in each NET_BUFFER_LIST structure to NDIS_STATUS_PAUSED.

  • Can provide status indications with the NdisFIndicateStatus function.

    For more information about status indications, see Filter Module Status Indications.

  • Should handle status indications in its FilterStatus function.

  • Should handle OID requests in the FilterOidRequest function.

    For more information about OID requests, see Filter Module OID Requests.

  • Can initiate OID requests.

  • Should not free the resources the driver allocated during the attach operation.

  • Should cancel timers, if required to stop send and receive operations.

    For more information about timers, see NDIS 6.0 Timer Services.

After the filter driver successfully pauses the send and receive operations, it must complete the pause operation. The filter driver can complete the pause operation synchronously or asynchronously by returning NDIS_STATUS_SUCCESS or NDIS_STATUS_PENDING respectively from FilterPause.

If the driver returns NDIS_STATUS_PENDING, it must call the NdisFPauseComplete function after it completes the pause operation.

On behalf of a filter module that is in the Paused state, the filter driver:

  • Should not originate new receive indications.

  • Should return new receive indications that underlying drivers originate to NDIS immediately by calling the NdisFReturnNetBufferLists function. If necessary, the driver can copy receive indications and queue them before it returns them.

  • Should not originate new send requests.

  • Should return all new send requests made to its FilterSendNetBufferLists function immediately by calling the NdisFSendNetBufferListsComplete function. The filter driver should set the Status member in each NET_BUFFER_LIST structure to NDIS_STATUS_PAUSED.

  • Can provide status indications with the NdisFIndicateStatus function.

  • Should handle status indications in its FilterStatus function.

  • Should handle OID requests in the FilterOidRequest function.

  • Can initiate OID requests.

NDIS does not initiate other Plug and Play operations, such as, attach, detach, or a restart requests, while the filter driver is in the Pausing state. NDIS can initiate detach or restart requests after a filter driver is in the Paused state. For more information about how to detach a filter module, see Detaching a Filter Module. For more information about how to restart a filter module, see Starting a Filter Module.