Edit

Starting a Filter Module

  • Article

To start a paused filter module, NDIS calls the filter driver's FilterSetModuleOptions function, if any, followed by a call to the FilterRestart function. The filter module enters the Restarting state at the start of execution in the FilterRestart function.

If the driver provided an entry point for FilterSetModuleOptions, the driver can change the partial characteristic for a filter module. For more information, see Data Bypass Mode.

When it calls a filter driver's FilterRestart function, NDIS passes a pointer to an NDIS_RESTART_ATTRIBUTES structure to filter driver in the RestartAttributes member of the NDIS_FILTER_RESTART_PARAMETERS structure. Filter drivers can modify the restart attributes that are specified by underlying drivers. For more information about how to modify restart attributes, see FilterRestart.

Note  NDIS calls FilterSetModuleOptions for all filter modules in a stack before NDIS calls the FilterRestart function for any filter module in the stack.

NDIS starts a filter module as part of a Plug and Play operation to restart a driver stack. For an overview of restarting the driver stack, see Restarting a Driver Stack.

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

  • Completes any operations that are required to restart normal send and receive operations.

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

  • Can read or write configurable parameters for the filter module.

  • Can receive network data indications. The driver can copy and queue such data and indicate it to overlying drivers later, or it can discard the data.

  • Should not initiate any new receive indications.

  • Should reject all new send requests made to its FilterSendNetBufferLists function immediately by calling the NdisFSendNetBufferListsComplete function. It should set the complete status in each NET_BUFFER_LIST 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 OID requests in the FilterOidRequest function.

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

  • Should not initiate any new send requests.

  • Should return new receive indications to NDIS immediately by calling the NdisFReturnNetBufferLists function. If necessary, the driver can copy such receive indications before it returns them.

  • Can make OID requests to the underlying drivers to set or query updated configuration information.

  • Should handle status indications in its FilterStatus function.

  • Should Indicate NDIS_STATUS_SUCCESS or a failure status. If a filter module does not restart, NDIS will detach it and if it is a mandatory filter, NDIS terminates the entire driver stack.

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

If the driver returns NDIS_STATUS_PENDING, it must call the NdisFRestartComplete function after it completes the restart operation. In this case, the driver passes the final status of the restart operation to NdisFRestartComplete.

After the restart operation is complete, the filter module is in the Running state. The driver resumes normal send and receive processing.

NDIS does not initiate other Plug and Play operations, such as, attach, detach, or pause requests, while the filter driver is in the Restarting state. NDIS can initiate pause requests after a filter driver is in the Running state. For more information about pausing a filter module, see Pausing a Filter Module.