Sample NDIS 6.0 Filter Driver

Description

The Ndislwf sample is currently a do-nothing pass-through NDIS 6 filter driver that demonstrates the basic principles of an NDIS 6.0 Filter driver. The sample replaces the NDIS 5 Sample Intermediate Driver (Passthru driver). This driver exposes a virtual device to handle IOCTLs from user applications.

Although the filter driver is a modifying filter driver, the filter driver currently does not modify the send data and it only re-packages and sends down all requests and sends submitted requests to one of the filter modules in this filter driver. The filter driver can be modified to change the data before passing it along or generate new send data and send it down. For example, it could encrypt or compress outgoing and decrypt or decompress incoming data.Ndislwf also indicates up all received data and status indications that it receives. It can be modified to change the data or status indications before indicating it up, and also the filter driver can generate status indications and receive data.Note This sample provides an example of minimal driver intended for education purposes. The driver and its sample test programs are not intended for use in a production environment.

Theory of Operation

The following steps describe attaching and detaching an Ndislwf driver:

1. During DriverEntry, the Ndislwf driver registers as an NDIS 6 filter driver.

2. Later on, NDIS calls Ndislwf FilterAttach handler, for each underlying NDIS adapter on which it is configured to attach.

3. In the context of the FilterAttach Handler, the filter driver call NdisFAttribute to register its filter module context with NDIS. After that, the filter driver can read its own settings in registry by calling NdisOpenConfigurationEx, and calls NdisXXX functions.

4. After FilterAttach successfully returns, NDIS restarts the filter later by calling FilterRestart handler. FilterRestart should prepare to handle send and receive data. After the restart returns successfully, filter driver should be able to process send and receive data.

5. All requests and sends coming from overlying drivers for the Ndislwf filter driver are repackaged if necessary and sent down to NDIS, to be passed to the underlying NDIS driver.

6. All indications that arrive from an underlying NDIS driver are forwarded up by Ndislwf filter driver.

7. NDIS call FilterPause handler when NDIS needs to detach the filter from the stack or there is some configuration changes in the stack. In processing the pause request from NDIS, the Ndislwf driver waits for all its own outstanding requests to be completed before it completes the pause request.

8. NDIS calls the Ndislwf driver's FilterDetach entry point when NDIS needs to detach a filter module from NDIS stack. FilterDetach handler should free all of the memory allocation done in FilterAttach, and undo the operations it did in FilterAttach Handler.

Building the Sample

1. Click the free build environment or checked build environment icon under your Development Kits program group to set basic environment variables needed by the build utility.

2. Change to the directory that contains the device source code, such as

   CD src\network\ndis\filter

3. Run build -ceZ, or use the macro BLD. This behavior calls the Microsoft make routines that produce log files called "Buildxxx_yyy_zzz.log", and also "Buildxx_yyy_zzz.wrn" and "Buildxx_yyy_zzz.err" if there are any warnings or errors. xxx stands for fre or chk depending on the environment chosen, yyy stands for the operating system version (Wlh), and zzz stands for platform version (x86, IA64, or AMD64).

If the build succeeds, the driver, ndislwf.sys, will be placed in a platform-specific subdirectory of your %TargetPath% directory that is specified in the Sources file. This procedure builds an NDIS 6.0 Light Weight Filter driver.

Installation

General

Ndislwf is installed as a service (called "NDIS Sample LightWeight Filter" in the supplied INF file). To install, follow these steps:

1. Prepare a floppy disk (or installation directory) that contains these files: "netlwf.inf" and "ndislwf.sys".

2. Open Control Panel, double-click Network and Internet Connections, double-click Network Connections, right-click the relevant Local Area Connection icon, and then click Properties.

3. Click Install, click Service, click Add, and then click Have Disk.

4. Browse to the drive or directory that contains the files listed in step 1, and click OK.

5. Select "NDIS Sample LightWeight Filter" in a list of Network Services, and click OK. This step should install the Ndislwf filter driver.

6. Click OK or Yes each time if the system prompts with a warning regarding installation of unsigned files. This action is necessary because binaries that are generated through the WDK build environment are not signed.

Code Tour

File Manifest

Send comments about this topic to Microsoft

Build date: 4/3/2012