Creating an INF File for a File System Filter Driver

Download EaseFilter Filter Driver SDK Setup File
Download EaseFilter Filter Driver SDK Zip File

The Windows Setup and Device Installer Services, known collectively as SetupAPI, provide the functions that control Windows setup and driver installation. The installation process is controlled by INF files.

A file system filter driver's INF file provides instructions that SetupAPI uses to install the driver. The INF file is a text file that specifies the files that must be present for your driver to run and the source and destination directories for the driver files. An INF file also contains driver configuration information that SetupAPI stores in the registry, such as the driver's start type and load order group.

For more information about INF files and how they are created, see Creating an INF File and INF File Sections and Directives. For general information about signing drivers, see Driver Signing.

You can create a single INF file to install your driver on multiple versions of the Windows operating system. For more information about creating such an INF file, see Creating INF Files for Multiple Platforms and Operating Systems andCreating International INF Files.

Starting with 64-bit versions of Windows Vista, all kernel-mode components, including non-PnP (Plug and Play) drivers such as file system drivers (file system, legacy filter, and minifilter drivers), must be signed in order to load and execute. For these versions of the Windows operating system, the following list contains information that is relevant to file system filter drivers.

INF files cannot be used to read information from the registry or to launch a user-mode application.

After creating an INF file, you will typically write the source code for your setup application. The setup application calls user-mode setup functions to access the information in the INF file and perform installation operations.

To construct your own filter driver INF file, use the INF files for the sample file system filter drivers as a template. You can use the ChkINF tool to check the syntax of your INF file.

An INF file for a file system filter driver generally contains the following sections.

Version Section (required)

The Version section specifies a class and GUID that are determined by the type of filter, as shown in the following code example.

[Version]  
Signature   = "$WINDOWS NT$"  
Class       = "ActivityMonitor"  
ClassGuid   = {b86dff51-a31e-4bac-b3cf-e8cfe75c9fc2}  
Provider    = %Msft%  
DriverVer   = 08/28/2000,1.0.0.1  
CatalogFile =   

The following table shows the values that file system filter drivers should specify in the Version section.

Entry Value

Signature

"$WINDOWS NT$"

Class

See File System Filter Driver Classes and Class GUIDs.

ClassGuid

See File System Filter Driver Classes and Class GUIDs.

Provider

In your own INF file, you should specify a provider other than Microsoft.

DriverVer

See INF DriverVer directive.

CatalogFile

Leave this entry blank. In the future, it will contain the name of a WHQL-supplied catalog file for signed drivers.

 

DestinationDirs Section (optional but recommended)

The DestinationDirs section specifies the directories where filter driver and application files will be copied.

In this section and in the ServiceInstall section, you can specify well-known system directories by using system-defined numeric values. For a list of these values, see INF DestinationDirs Section. In the following code example, the value "12" refers to the Drivers directory (%windir%\system32\drivers), and the value "10" refers to the Windows directory (%windir%).

[SourceDisksNames]  
1 = %Disk1%  

SourceDisksFiles Section (required)

The SourceDisksFiles section specifies the location and names of the files to be copied.

In the following code example, the SourceDisksFiles section lists the files to be copied for the driver and specifies that the files can be found on the media whose unique identifier is 1 (This identifier is defined in the SourceDisksNamessection of the INF file.)

[SourceDisksFiles]  
myLegacyFilter.exe = 1  
myLegacyFilter.sys = 1

DefaultInstall Section (required)

In the DefaultInstall section, a CopyFiles directive copies the file system filter driver's driver files and user-application files to the destinations that are specified in the DestinationDirs section.

Note  The CopyFiles directive should not refer to the catalog file or the INF file itself; SetupAPI copies these files automatically.

You can create a single INF file to install your driver on multiple versions of the Windows operating system. This type of INF file is created by creating additional DefaultInstallDefaultInstall.ServicesDefaultUninstall, andDefaultUninstall.Services sections for each operating system version. Each section is labeled with a decoration (for example, .ntx86, .ntia64, or .nt) that specifies the operating system version to which it applies. For more information about creating this type of INF file, see Creating INF Files for Multiple Platforms and Operating Systems.

In the following code example, the CopyFiles directive copies the files that are listed in the MyLegacyFilter.DriverFiles and MyLegacyFilter.UserFiles sections of the INF file.

[DefaultInstall]  
OptionDesc = %MyLegacyFilterServiceDesc%  
CopyFiles = MyLegacyFilter.DriverFiles, MyLegacyFilter.UserFiles  

DefaultInstall.Services Section (required)

The DefaultInstall.Services section contains an AddService directive that controls how and when the services of a particular driver are loaded.

In the following code example, the AddService directive adds the MyLegacyFilter service to the operating system. The %MyLegacyFilterServiceName% token contains the service name string, which is defined in the Strings section of the INF file. MyLegacyFilter.Service is the name of the example driver's ServiceInstall section.

[DefaultInstall.Services]  
AddService = %MyLegacyFilterServiceName%,,MyLegacyFilter.Service

ServiceInstall Section (required)

The ServiceInstall section adds subkeys or value names to the registry and sets values. The name of the ServiceInstallsection must appear in an AddService directive in the DefaultInstall.Services section.

The following code example shows the ServiceInstall section for the MyLegacyFilter example driver.

[MyLegacyFilter.Service]  
DisplayName    = %MyLegacyFilterServiceName%  
Description    = %MyLegacyFilterServiceDesc%  
ServiceBinary  = %12%\myLegacyFilter.sys  
ServiceType    = 2 ;SERVICE_FILE_SYSTEM_DRIVER  
StartType      = 3 ;    SERVICE_DEMAND_START  
ErrorControl   = 1 ;    SERVICE_ERROR_NORMAL  
LoadOrderGroup = "FSFilter Activity Monitor"  
AddReg         = MyLegacyFilter.AddRegistry

  

The DisplayName entry specifies the name for the service. In the preceding example, the service name string is specified by the %MyLegacyFilterServiceName% token, which is defined in the Strings section of the INF file.

The Description entry specifies a string that describes the service. In the preceding example, this string is specified by the %MyLegacyFilterServiceDesc% token, which is defined in the Strings section of the INF file.

The ServiceBinary entry specifies the path to the executable file for the service. In the preceding example, the value 12 refers to the Drivers directory (%windir%\system32\drivers).

The ServiceType entry specifies the type of service. The following table lists the possible values for ServiceType and their corresponding service types.

Value Description

0x00000001

SERVICE_KERNEL_DRIVER (Device driver service)

0x00000002

SERVICE_FILE_SYSTEM_DRIVER (File system or file system filter driver service)

0x00000010

SERVICE_WIN32_OWN_PROCESS (Microsoft Win32 service that runs in its own process)

0x00000020

SERVICE_WIN32_SHARE_PROCESS (Win32 service that shares a process)

 

The ServiceType entry should always be set to SERVICE_FILE_SYSTEM_DRIVER for a file system filter driver.

The StartType entry specifies when to start the service. The following table lists the possible values for StartType and their corresponding start types.

Value Description

0x00000000

SERVICE_BOOT_START

0x00000001

SERVICE_SYSTEM_START

0x00000002

SERVICE_AUTO_START

0x00000003

SERVICE_DEMAND_START

0x00000004

SERVICE_DISABLED

 

For detailed descriptions of these start types, see What Determines When a Driver Is Loaded.

If your driver's start type is SERVICE_BOOT_START (that is, the driver is a boot-start driver), you should also ensure that the LoadOrderGroup entry is appropriate for the type of filter you are developing. To choose a load order group, seeLoad Order Groups for File System Filter Drivers. Additionally, starting with x64-based Windows Vista systems, the binary image file of a boot-start driver must contain an embedded signature. This requirement ensures optimal system boot performance. For more information, see Kernel-Mode Code Signing Walkthrough.

For information about how the StartType and LoadOrderGroup entries determine when the driver is loaded, see What Determines When a Driver Is Loaded.

The ErrorControl entry specifies the action to be taken if the service fails to start during system startup. The following table lists the possible values for ErrorControl and their corresponding error control values.

Value Action

0x00000000

SERVICE_ERROR_IGNORE (Log the error and continue system startup.)

0x00000001

SERVICE_ERROR_NORMAL (Log the error, display a message to the user, and continue system startup.)

0x00000002

SERVICE_ERROR_SEVERE (Switch to the registry's LastKnownGood control set and continue system startup.)

0x00000003

SERVICE_ERROR_CRITICAL (If system startup is not using the registry's LastKnownGood control set, switch to LastKnownGood and try again. If startup still fails, run a bug-check routine. Only the drivers that are needed for the system to startup should specify this value in their INF files.)

 

The LoadOrderGroup entry should be set to a load order group that is appropriate for the type of file system filter driver that you are developing. To choose a load order group, see Load Order Groups for File System Filter Drivers.

The AddReg directive refers to one or more INF writer-defined AddRegistry sections that contain any information to be stored in the registry for the newly installed service.

Note   If the INF file will also be used for upgrading the driver after the initial install, the entries that are contained in the AddRegistry section should specify the 0x00000002 (FLG_ADDREG_NOCLOBBER) flag. Specifying this flag preserves the registry entries in HKLM\CurrentControlSet\Services when subsequent files are installed. For example:

[ExampleFileSystem.AddRegistry] 
HKR,Parameters,ExampleParameter,0x00010003,1  

DefaultUninstall Section (optional)

The DefaultUninstall section is optional but recommended if your driver can be uninstalled. It contains DelFiles andDelReg directives to remove files and registry entries.

In the following code example, the DelFiles directive removes the files that are listed in the MyLegacyFilter.DriverFiles and MyLegacyFilter.UserFiles sections of the driver's INF file:

[DefaultUninstall.Services]  
DelService = MyLegacyFilter,0x200  

  

Note   The DelService directive should always specify the 0x200 (SPSVCINST_STOPSERVICE) flag to stop the service before it is deleted.

Strings Section (required)

The Strings section defines each %strkey% token that is used in the INF file, as shown in the following example.

[Strings]  
Msft                      = "Microsoft Corporation"  
MyLegacyFilterServiceDesc = "MyLegacyFilterFilter Driver"  
MyLegacyFilterServiceName = "MyLegacyFilter"  
MyLegacyFilterRegistry    = "system\currentcontrolset\services\MyLegacyFilter"  
MyLegacyFilterMaxRecords  = "MaxRecords"  
MyLegacyFilterMaxNames    = "MaxNames"  
MyLegacyFilterDebugFlags  = "DebugFlags"  
Disk1                     = "MyLegacyFilter Source Media"