Configuring an INF File for a Monitoring Filter Driver
The following NDIS filter driver installation issues are associated with monitoring filter drivers:
- Set the
Class INF file entry to
NetService in the INF file. The following example shows a sample
Class entry for the INF file.
Class = NetService
DDInstall section in a filter driver INF file must have a
Characteristics entry. The following example shows how you should define the
Characteristics entry in your filter INF file.
The 0x40000 value indicates that NCF_LW_FILTER (0x40000) is set. Filter drivers must not set the NCF_FILTER (0x400) flag. The values of the NCF_ Xxx flags are defined in Netcfgx.h. For more information about NCF_ Xxx flags, see DDInstall Section in a Network INF File.
- Set the
NetCfgInstanceId INF file entry in the INF file, as the following example shows.
You can use the Uuidgen.exe tool to create the GUID for the NetCfgInstanceId entry.
The DDInstall section of the INF file for a filter driver must include an Addreg directive for an Ndi key. The INF file must specify the Service entry under the Ndi key. The ServiceBinary entry in the service-install section of the INF file specifies the path to the binary for the filter driver. For more information, see Adding Service-Related Values to the Ndi Key and DDInstall.Services Section in a Network INF File.
DDInstall section in a filter driver INF file must have
FilterRunType entries. To specify a monitoring filter, define the
FilterType entry in your INF file, as the following example shows.
HKR, Ndi,FilterType,0x00010001 ,0x00000001
The FilterType value 0x00000001 indicates that the filter is a monitoring filter.
- Define the
FilterRunType entry in your INF file, as the following example shows.
HKR, Ndi,FilterRunType,0x00010001 ,0x00000002
The 0x00000002 value in the preceding example indicates that the filter module is optional. To install a mandatory filter module, set the FilterRunType entry to 0x00000001. For more information, see Mandatory Filter Drivers.
Note We highly recommend that a monitoring lightweight filter (LWF) driver should not be mandatory, unless it is to be used in a controlled environment where there will be no optional modifying LWF drivers. This is because a mandatory monitoring LWF driver can cause optional modifying LWF drivers to fail FilterAttach. A monitoring LWF driver is bound over every modifying filter and binding by design to facilitate monitoring of networking traffic at all levels. Consider the following scenario:
- An instance of a mandatory monitoring LWF driver is installed over an optional modifying LWF driver.
- The lower modifying optional LWF driver fails to attach to a lower component. This will cause the mandatory monitoring LWF driver’s FilterAttach handler not to be called.
- Because now an instance of a mandatory LWF driver is not loaded, NDIS will not bind any protocols (such as TCP/IP) to the interface or NIC, thus rendering the interface to be unusable.
- The following example shows how a filter driver INF file specifies the name of the service.
In this example, "NdisMon" is the name of the driver's service as it is reported to NDIS. Note that the name of a filter driver's service can be different from the name of the binary for the driver, but typically they are the same.
- The following example shows how the filter INF file references the name of the filter driver's
service when it adds that service.
[Install.Services] AddService=NdisMon,,NdisMon_Service_Inst [NdisMon_Service_Inst] DisplayName = %NdisMon_Desc% ServiceType = 1 ;SERVICE_KERNEL_DRIVER StartType = 1 ;SERVICE_SYSTEM_START ErrorControl = 1 ;SERVICE_ERROR_NORMAL ServiceBinary = %12%\ndisMon.sys LoadOrderGroup = NDIS Description = %NdisMon_Desc% AddReg = Common.Params.Reg
- A filter INF file must specify at least the primary service name of the filter for the
CoServices attribute, as the following example shows.
For more information about the CoServices attribute, see Adding Service-Related Values to the Ndi Key.
The FilterClass value in the INF file for a filter driver determines its order in a stack of modifying filters. However, monitoring filter drivers do not define the FilterClass key. Instead the monitoring filter module that is installed first is closest to the miniport adapter.
- You must define the following entries in the monitoring filter driver INF file to control the
HKR, Ndi\Interfaces,UpperRange,,"noupper" HKR, Ndi\Interfaces,LowerRange,,"nolower" HKR, Ndi\Interfaces, FilterMediaTypes,,"ethernet"
For more information about controlling the driver bindings, see Specifying Filter Driver Binding Relationships.
- A monitoring filter INF file should specify common parameter definitions for the filter driver,
parameters that are associated with a specific adapter, and parameters that are associated with a
particular instance (filter module). The following example shows some common parameter definitions.
[Common.Params.reg] HKR, FilterDriverParams\DriverParam, ParamDesc, ,"Driverparam for filter" HKR, FilterDriverParams\DriverParam, default, ,"5" HKR, FilterDriverParams\DriverParam, type, ,"int" HKR, FilterAdapterParams\AdapterParam, ParamDesc, ,"Adapterparam for filter" HKR, FilterAdapterParams\AdapterParam, default, ,"10" HKR, FilterAdapterParams\AdapterParam, type, ,"int" HKR, FilterInstanceParams\InstanceParam, ParamDesc, ,"Instance param for filter" HKR, FilterInstanceParams\InstanceParam, default, ,"15" HKR, FilterInstanceParams\InstanceParam, type, ,"int"