Installing a Filter Driver

Installing a Filter Driver

There are only two truly easy ways to install a filter driver: when the filter is for an entire class of device, or when it s part of a package that includes the function driver. To install a filter driver for an existing device, you need to locate and modify the right registry entries more or less by hand. I ll discuss these installation issues in this section.

Figure 2-7 illustrates the layering of device and class filters. To recapitulate what Chapter 2 says about the order of driver loading, the PnP Manager first loads device and class lower filters, then the function driver, and finally device and class upper filters. The lowest driver in the stack (apart from the bus driver, that is) will be the first driver mentioned in the hardware key s LowerFilters value. The highest driver in the stack will be the last driver mentioned in the class key s UpperFilters value.

Installing a Class Filter

To install a class filter along with the class, add some syntax to the [ClassInstall32] section:

[ClassInstall32] AddReg=ClassInstall32AddReg CopyFiles=CopyClassFilters [ClassInstall32AddReg] HKR,,UpperFilters,0x00010000,foo,bar [ClassInstall32.Services] AddService=FOO,,FooAddService AddService=BAR,,BarAddService [CopyClassFilters] foo.sys,,,2 bar.sys,,,2

The AddReg section defines a REG_MULTI_SZ value containing two strings: foo and bar, which specify the service names of two filter drivers. The [ClassInstall32.Services] section defines these services using the same service-definition syntax that I showed in Chapter 15 for a function driver. The [CopyClassFilters] section relies on a [DestinationDirs] directive (not shown) to put the driver files into the drivers directory.

To define class lower filters, simply define a value named LowerFilters using similar syntax.

Once the class has been defined, you can add filter drivers to the end of the list of filters in Windows 2000 and later systems by using an INF like this one. (Compare the CLASFILT sample in the DDK, which has a bit more syntax than you actually need.)

[Version] Signature=$CHICAGO$ [DefaultInstall] CopyFiles=CopyClassFilters AddReg=FilterAddReg [DefaultInstall.Services] AddService=JUNKOLA,,FilterAddService [SourceDisksFiles] junkola.sys=1 [SourceDisksNames] 1="Filter install disk" [DestinationDirs] DefaultDestDir=12 [CopyClassFilters] junkola.sys,,,2 [FilterAddService] ServiceType=1 ErrorControl=1 StartType=3 ServiceBinary=%12%\junkola.sys [FilterAddReg] HKLM,%CLASSKEY%,UpperFilters,0x00010008,junkola [Strings] CLASSKEY=System\CurrentControlSet\Class\{<class-GUID>}

The only interesting thing in this sample INF is the [FilterAddReg] section, which uses the FLG_ADDREG_APPEND flag to cause the new filter service to be appended to the existing UpperFilters value unless it s already in the list of upper filters. Note that you need to spell out the setup class globally unique identifier (GUID) for the class you re overriding in this way.

NOTE
The DDK documentation is a bit sparse when it comes to the REG_MULTI_SZ value syntax. If you want to completely overwrite a REG_MULTI_SZ value with one or more string values, specify the flag 0x00010000 and specify the strings with commas between them, as in the first example in this subsection. If you want to append a value, specify the flag 0x00010008, as in the second example. You can append just one value with one directive in the AddReg section. You can, however, have more than one directive that applies to the same value, and they ll be executed in the order they appear. The comparison to see whether a given string is already in the value is not case sensitive. There is no syntax for putting a new string elsewhere than at the end of the value.

To actually install the filter by hand, right-click on the INF file and select the INSTALL choice. Alternatively, use RUNDLL32 to execute the InstallHinfSection function in setupapi.dll with an argument string composed by concatenating DefaultInstall (notice the trailing space) with the name of the INF file.

Microsoft hasn t provided a way to extend the list of class filters in Windows 98/Me. You need to write an installation program to directly modify the class key.

Installing a Device Filter with the Function Driver

To install a device upper or lower filter along with the function driver in Windows 2000 and later systems, you need merely to define an UpperFilters or LowerFilters value in the hardware key, copy the filter driver files to the driver directory, and define the filter services. Here s an example of the additional syntax you need:

[DriverCopyFiles] foo.sys,,,2
 [DriverInstall.ntx86.Services] AddService=whatever,2,DriverService ; <== for the function driver AddService=foo,,FooService
 [FooService] ServiceType=1 ErrorControl=1 StartType=3 ServiceBinary=%12%\foo.sys [DriverInstall.ntx86.hw] AddReg=FilterAddReg.ntx86 [FilterAddReg.ntx86] HKR,,UpperFilters,0x00010000,foo

To specify a lower filter, define a LowerFilters value in the hardware key. To specify more than one filter, use commas to separate the service names in the directive or directives in the AddReg section.

Installing a Device Filter for an Existing Device

Microsoft hasn t provided a way to install a filter driver for an existing device. The problem you face when you try to do this is determining the name of the hardware key in the registry, and there s no general way to do that.

The FILTJECT.DLL code in the companion content illustrates a scheme for installing a device filter after the fact. You invoke FILTJECT by means of the system RUNDLL32 utility, which makes it usable in a RunOnce key installed by an INF file. (See the FILTER sample s INF file for an example.) FILTJECT parses command-line options that include the exact device description or friendly name string of the device you want to filter. Then it enumerates all installed devices to locate all instances of that device, and it modifies the UpperFilters or LowerFilters values as specified by other command-line options.

NOTE
The FILTER.HTM file describing the FILTER sample also describes the syntax for FILTJECT.DLL.

The POWTRACE sample shows another scheme for after-the-fact filtering. POWTRACE s INF file merely defines the POWTRACE service. You can then hand-edit the registry to add a LowerFilters value to any device you want to filter.