Data Bypass Mode

The filter driver data bypass mode can provide improved system performance. NDIS does not call FilterXxx functions that are bypassed. For example, if the send and receive services are not required for a given filter application, the filter driver can bypass the send and receive functions.

A filter driver specifies the default entry points, for functions that can be bypassed, during driver initialization when it calls the NdisFRegisterFilterDriver function. The entry points are NULL for functions that are bypassed by default. For more information about initialization, see Initializing a Filter Driver.

To change the bypass state at runtime, the driver must specify an entry point for the FilterSetModuleOptions function during driver initialization. The driver can initialize an NDIS_FILTER_PARTIAL_CHARACTERISTICS structure and pass the new characteristics to the NdisSetOptionalHandlers function from within the context of FilterSetModuleOptions.

NDIS calls the FilterSetModuleOptions function, if any, at the start of a restart operation. A filter driver can set bypass mode independently for each filter module. For more information, see Starting a Filter Module.

Filter drivers can bypass the following optional FilterXxx functions that are specified in the NDIS_FILTER_DRIVER_CHARACTERISTICS structure:

FilterSendNetBufferLists

FilterSendNetBufferListsComplete

FilterCancelSendNetBufferLists

FilterReturnNetBufferLists

FilterReceiveNetBufferLists

To set a FilterXxx function to bypass mode, a filter driver specifies NULL for that function's entry point. However, if a driver calls any NDIS function that has an associated FilterXxx function, it must provide an entry point for that FilterXxx function. For example, if a driver calls the NdisFIndicateReceiveNetBufferLists function, it must provide a FilterReturnNetBufferLists function.

If a filter driver specifies a FilterSendNetBufferLists function and it queues send requests, it must also specify a FilterCancelSendNetBufferLists function.

If a filter driver specifies a FilterReceiveNetBufferLists or FilterReturnNetBufferLists function, the driver must also specify a FilterStatus function.

To change its bypass mode settings at run time, a filter driver can call the NdisFRestartFilter function. NdisFRestartFilter schedules a pause operation that is followed by a restart operation for the specified filter module. When NDIS calls FilterSetModuleOptions, the filter driver can change the functions for that filter module by calling NdisSetOptionalHandlers and specifying a new set of entry points.

Note  Pause and restart could cause some network packets to be dropped on the transmit path, or receive path, or both. Network protocols that provide a reliable transport mechanism might retry the network I/O operation in the case of a lost packet, but other protocols that do not guarantee reliability do not retry the operation.

A filter driver can register additional optional functions that support optional driver services. The driver registers these optional services in the FilterSetOptions function. For more information about these optional services, see Configuring Optional Filter Driver Services.