## The FILTER Sample

The FILTER Sample accompanies Chapter 16 and illustrates the mechanics of writing a WDM filter driver.

The sample includes two components:

- FILTER.SYS (SYS subdirectory) is a WDM filter driver.
- FILTJECT.DLL (FILTJECT subdirectory) is user-mode DLL for installing a filter for an existing device.

### Building FILTER

To build FILTER.SYS, follow the general instructions for building a WDM sample. The Microsoft Visual C++ project file is named SYS\FILTER.DSP.

To build FILTJECT.DLL, follow the general instructions for building user-mode programs. The Microsoft Visual C++ project file is named FILTJECT\FILTJECT.DSP.

### Testing FILTER

First select an existing device that uses a WDM driver. An easy way to proceed is to install one of the sample devices for this book. Then open SYS\FILTER.INF in a text editor and replace the string "IOCTL Sample Device" with the name of the device you've selected. This string appears twice, by the way. Also, if you happen to pick the IOCTL sample, you won't need to change a thing in the INF file.

Right-click on the SYS\FILTER.INF file and select the Install choice from the context menu. Setup will copy FILTER.SYS and FILTJECT.DLL into the Drivers and System or System32 directory, respectively, and it will execute FILTJECT to insert FILTER as an upper filter for your device. Note that you should not use FASTINST or the Add New Hardware wizard to install FILTER.SYS.

The next time you start the device you modified, FILTER.SYS will print a debugging message for each IRP sent to the device. You’ll need to be running a debugger or DbgView to see these messages. You can restart most devices in Windows XP by disabling and then reenabling them. In Windows 98/Me, you generally need to reboot the computer.

To remove the filter, execute the following command at a command prompt:

C:>rundll32 filtject,InjectFilter "IOCTL Sample Device" -remove filter[.sys]

Substitute the name of your own device for "IOCTL Sample Device". Include ".sys" in Windows 98/Me; leave ".sys" out in Windows XP.

# About FILTJECT.DLL

FILTJECT.DLL allows you add and remove filter drivers for an existing hardware device whose FriendlyName or DeviceDesc you happen to know. You use this DLL in conjunction with RUNDLL32 like this:

C:>rundll32 filtject,InjectFilter devname filtname [options]

Where:

devname

is the name of an existing device. Use either the FriendlyName or the DeviceDesc of a device. FILTJECT will add or remove a filter from all devices having this name.

filtname

is the name of the service (Windows XP) or driver (Windows 98/Me) that you want to inject or remove. In the FILTER sample, this is either FILTER or FILTER.SYS.

options

specify the exact operation you want to perform:

-ADD or -REMOVE indicates whether you're adding or removing a filter. -ADD is the default if you don't mention either of these options.

-FIRST, -LAST, -BEFORE xxx, or -AFTER xxx indicates where you want a new filter positioned in the list of existing filters. Specify the exact name, except for upper and lower case, of any existing filter if you use -BEFORE or -AFTER. -FIRST is the default if you don't mention any of these options.

-UPPER or -LOWER indicates whether you're adding or removing an upper filter or a lower filter. -UPPER is the default if you don't mention either of these options.

Since FILTJECT.DLL is intended for use with RUNDLL32 during a setup program, it doesn't produce any error messages or interact with the end user in any other way. If something goes wrong, you might see a terse error message in a debug window, but that's about it.

### What to look for

DriverEntry.cpp (sys directory) contains all the code for a basic filter driver.