Initializing a Filter Driver
Filter driver initialization occurs immediately after the system loads the driver. Filter drivers load as system services. The system can load the filter drivers at any time before, during, or after the miniport drivers load. NDIS can attach a filter module to a miniport adapter after a miniport adapter of the type supported by the filter driver becomes available and the filter driver initialization is complete.
While a driver stack is starting, the system loads the filter drivers if they are not already loaded. For more information about starting a driver stack that includes filter modules, see Starting a Driver Stack.
After a filter driver loads, the system calls the driver's DriverEntry routine.
The system passes two arguments to DriverEntry:
A pointer to the driver object, which was created by the I/O system.
A pointer to the registry path, which specifies where driver-specific parameters are stored.
DriverEntry returns STATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver successfully registered as an NDIS filter driver. If DriverEntry fails initialization by propagating an error status returned by an NdisXxx function or by a kernel-mode support routine, the driver will not remain loaded. DriverEntry must execute synchronously; that is, it cannot return STATUS_PENDING or its equivalent NDIS_STATUS_PENDING.
The filter driver passes the driver object to the NdisFRegisterFilterDriver function when it registers with NDIS as a filter driver. The driver can use the registry path to obtain configuration information. For more information about how to access filter driver configuration information, see Accessing Configuration Information for a Filter Driver.
A filter driver calls NdisFRegisterFilterDriver from its DriverEntry routine. Filter drivers export a set of FilterXxx functions by passing an NDIS_FILTER_DRIVER_CHARACTERISTICS structure to NdisFRegisterFilterDriver at the FilterCharacteristics parameter.
The NDIS_FILTER_DRIVER_CHARACTERISTICS structure specifies entry points for mandatory and optional FilterXxx functions. Some optional functions can be bypassed. For more information about bypassing functions, see Data Bypass Mode.
Drivers that call NdisFRegisterFilterDriver must be prepared for an immediate call to any of their FilterXxx functions.
The NDIS_FILTER_DRIVER_CHARACTERISTICS structure specifies the entry points for these mandatory FilterXxx functions:
The NDIS_FILTER_DRIVER_CHARACTERISTICS structure specifies the entry points for these optional, and not changeable at run-time, FilterXxx functions:
FilterCancelSendNetBufferLists
The NDIS_FILTER_DRIVER_CHARACTERISTICS structure specifies the default entry points for these optional, and changeable at run-time, FilterXxx functions:
FilterSendNetBufferListsComplete
The preceding four functions are also defined in the NDIS_FILTER_PARTIAL_CHARACTERISTICS structure. This structure specifies the functions that can be changed at a run time by calling the NdisSetOptionalHandlers function from the FilterSetModuleOptions function. If a filter driver will change these partial characteristics at runtime, it must provide the entry point for FilterSetModuleOptions. The partial characteristics can be different for each filter module. For more information, see Starting a Filter Module.
NDIS calls the FilterSetOptions function within the context of the call to NdisFRegisterFilterDriver. FilterSetOptions registers optional services with NDIS. For more information, see Configuring Optional Filter Driver Services.
If the call to NdisFRegisterFilterDriver succeeds, NDIS fills the variable at NdisFilterDriverHandle with a filter driver handle. The filter driver saves this handle and later passes this handle to NDIS functions, such as NdisFDeregisterFilterDriver, that require a filter driver handle as an input parameter. When the driver unloads, it must call the NdisFDeregisterFilterDriver function to release the driver resources allocated by NdisFRegisterFilterDriver.
After FilterSetOptions returns, the filter modules are in the Detached state. NDIS can call the filter driver's FilterAttach function at any time after the call to FilterSetOptions returns. The driver performs filter module-specific initialization in the FilterAttach function. For more information about attaching a filter module to a driver stack, see Attaching a Filter Module.
A filter driver also performs any other driver-specific initialization that it requires in DriverEntry. The filter driver must release the driver-specific resources that it allocates in its FilterDriverUnload routine. For more information, see Unloading a Filter Driver.