Device Installation Files
The software that is required to support a particular device depends on the kind of device and the ways in which the device is used. Typically, a vendor provides the following software in a driver package to support a device:
A device setup information file (INF file)
An INF file contains information that the system Windows components use to install support for the device. Windows copies this file to the %SystemRoot%\inf directory when it installs the driver. This file is required.
For more information, see Creating an INF File.
One or more drivers for the device
A .sys file is the driver’s image file. Windows copies this file to the %SystemRoot%\system32\drivers directory when the driver is installed. Drivers are required for most devices.
Digital signatures for the driver package (a driver catalog file)
A driver catalog file contains digital signatures. All driver packages should be signed.
A vendor obtains digital signatures by submitting its driver package to the Windows Hardware Quality Lab (WHQL) for testing and signing. WHQL returns the package with a catalog file (.cat file).
Other files
A driver package can contain other files, such as a custom device installation application, a device icon, or a driver library file (such as for video drivers).
Also, see the device-type-specific documentation in the WDK.
The WDK includes various sample installation files. For more information, see Sample Device Installation Files
Creating an INF file for a legacy file system filter driver
For optimal reliability and performance, use file system minifilter drivers with Filter Manager support instead of legacy file system filter drivers.
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 and Creating 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 for non-PnP drivers, including file system drivers, are not required to contain [Manufacturer] or [Models] sections.
The SignTool command-line tool, located in the \bin\SelfSign directory of the WDK installation directory, can be used to directly «embed sign» a driver SYS executable file. For performance reasons, boot-start drivers must contain an embedded signature.
Given an INF file, the Inf2Cat command-line tool can be used to create a catalog (.cat) file for a driver package. Only catalog files can receive WHQL logo signatures.
With Administrator privileges, an unsigned driver can still be installed on x64-based systems starting with Windows Vista. However, the driver will fail to load (and thus execute) because it is unsigned.
For detailed information about the driving signing process, including the driving signing process for 64-bit versions of Windows Vista, see Kernel-Mode Code Signing Walkthrough.
All kernel-mode components, including custom kernel-mode development tools, must be signed. For more information, see Signing Drivers during Development and Test (Windows Vista and Later).
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 InfVerif tool to check the syntax of your INF file.
An INF file for a file system filter driver generally contains the following sections.
Summary of INF Sections
The following summarizes the system-defined sections that can be used in INF files. System-defined section names are case-insensitive. For example, version, VERSION, and Version are equally valid section-names within an INF file.
This section describes the INF file sections in the same order that they generally appear in most device INF files. However, these sections actually can be specified in any arbitrary order. Windows finds all sections within each INF file by section name, not by sequential order, whether system-defined or INF-writer-defined.
Version Section
This is a required section for every INF file. For installation on Windows 2000 and later versions of Windows, this section must have a valid Signature entry.
SignatureAttributes Section
This section of the INF defines a set of files to be embedded-signed as part of Hardware Certification. These additional signatures are required for devices with certain special needs. Examples are Protected Environment media playback, Early Launch Antimalware, and third party HAL extensions.
SourceDisksNames Section
This section is required if the INF file has a corresponding SourceDisksFiles section. This section is required to install IHV/OEM-supplied devices and their drivers from distribution media included in packaged products. It is also required in such an INF file that installs either of the following:
A co-installer DLL to supplement the operations of a system-supplied device class installer or co-installers (see also DDInstall.CoInstallers later in this list)
A new class installer DLL to supplement the operations of the OS’s device installer (see also ClassInstall32)
This section identifies the individual source distribution disks or CD-ROM discs for the installation. By contrast, the system-supplied INF files each specify a LayoutFile entry in their Version sections and provide at least one other INF file detailing the source distribution contents and layout of all software components to be installed.
SourceDisksFiles Section
This section identifies the locations of files to be installed from the distribution media to the destinations on the target computer. An INF file that has this section must also have a SourceDisksNames section.
DestinationDirs Section
Device/driver INF files have a DestinationDirs section to specify a default destination directory for INF-specified copies of the files supplied on the distribution media or listed in the INF layout files. This section is required unless the INF file installs a device, such as a modem or display monitor, that has no files except its INF to be installed with it.
ControlFlags Section
This section controls whether an INF file is used only to transfer files from the distribution media.
Generally, most INF files for device drivers and for the system class installers have this section so they can exclude at least a subset of Models entries from the list of manually installable devices to be displayed to end-users. INF files that only install PnP devices suppress the display of all model-specific information.
Manufacturer Section
This section is required in INF files for devices and their drivers.
The Manufacturer section of a system device class INF is sometimes called a «Table of Contents,» because each of its entries references an INF-writer-defined Models section, which, in turn, references additional INF-writer-defined sections, such as a per-models-entry DDInstall section, DDInstall.Services section, and so forth.
Models Section (per Manufacturer entry)
This section is required to identify the devices for which the INF file installs drivers. It specifies a set of mappings between the generic name (string) for a device, the device ID, and the name of the DDInstall section, elsewhere in the INF file that contains the installation instructions for the device.
An INF file that installs one or more devices and drivers for a single provider would have only one Models section, but system INF files for device classes can have many INF-writer-defined Models sections.
DDInstall Section (per Models entry)
This section is required to actually install any devices that are listed in a Models section in the INF file, along with the drivers for each such device. A DDInstall section can be shared by more than one Models section.
DDInstall.Services Section
Starting with Microsoft Windows 2000, this section is required as an expansion of the DDInstall section for most kernel-mode device drivers. This includes any WDM drivers (exceptions are INF files for modems and display monitors). It controls how and when the services of a particular driver are started, its dependencies (if any) on underlying legacy, and so forth. This section also sets up event-logging services by a device driver if it supports event logging.
DDInstall.HW Section
This optional section adds device-specific (and typically, driver-independent) information to the registry or removes such information from the registry, possibly for a multifunction device or to install one or more PnP filter drivers.
DDInstall.CoInstallers Section
NoteВ В If you are building a universal or mobile driver package, this section is not valid. See Using a Universal INF File.
This optional section registers one or more device-specific co-installers supplied on the distribution media to supplement the operations of the system’s device installer or of an existing device class installer.
A co-installer is an IHV/OEM-provided Win32 DLL that typically writes additional configuration information to the registry or performs other installation tasks that require dynamically generated, machine-specific information that is not available when the device’s INF file is created. For more information, see Writing a Co-installer.
DDInstall.FactDef Section
NoteВ В If you are building a universal or mobile driver package, this section is not valid. See Using a Universal INF File.
This section should be included in the INF file of any manually installed non-PnP device. It specifies the factory default hardware configuration settings, such as the bus-relative I/O ports, IRQ (if any), and so forth, for the card.
DDInstall.LogConfigOverride Section
NoteВ В If you are building a universal or mobile driver package, this section is not valid. See Using a Universal INF File.
This section is used to create an override configuration, which overrides the hardware resource requirements that a Plug and Play device’s bus driver reports.
DDInstall.Interfaces Section
If a driver exports the functionality of a device interface class, therefore creating a new instance of the interface class, such as kernel-streaming still-image capture or data decompression, its INF file can have this section.
InterfaceInstall32 Section
If a to-be-installed component, such as a new class driver, provides one or more new device interface classes to higher-level components, its INF file has this section. In effect, this section bootstraps a set of device interfaces for a new class by setting up whatever is needed to use the functionality that the interface class provides.
DefaultInstall Section
An INF file’s DefaultInstall section will be accessed if a user selects the «Install» menu item after selecting and holding (or right-clicking) on the INF file name.
Strings Section
This section is required in every INF file to define each %strkey% token specified in the INF. By convention, the Strings section (or sections if the INF provides a set of locale-specific Strings sections) appears last in all system-supplied INF files for ease of maintenance and localization.
Some sections listed here, especially those with Install in their names, can contain directives that reference additional INF-writer-defined sections. Each directive causes particular operations to be performed on the items listed under the appropriate type of INF-writer-defined section during the installation process.
The set of valid entries and directives for any particular section in the previous list is section-specific and shown in the formal syntax of the reference for each of these sections. Additionally, see Summary of INF Directives for a summary of the most commonly used directives.
Optional entries and directives within each such section are shown enclosed in unbolded brackets, as for example:
[Version] . [Provider=%INF-creator%] . The Provider entry in a [Version] section is optional in the sense that it is not a mandatory entry in every INF file.
NtQueryInformationFile function (ntifs.h)
The NtQueryInformationFile routine returns various kinds of information about a file object. See also NtQueryInformationByName, which can be more efficiently used for a few file information classes.
Syntax
Parameters
[in] Handle to a file object. The handle is created by a successful call to NtCreateFile or NtOpenFile, or to an equivalent file create or open routine.
[out] Pointer to an IO_STATUS_BLOCK structure that receives the final completion status and information about the operation. The Information member receives the number of bytes that this routine actually writes to the FileInformation buffer.
[out] Pointer to a caller-allocated buffer into which the routine writes the requested information about the file object. The FileInformationClass parameter specifies the type of information that the caller requests.
[in] The size, in bytes, of the buffer pointed to by FileInformation.
[in] Specifies the type of information to be returned about the file, in the buffer that FileInformation points to. Device and intermediate drivers can specify any of the following FILE_INFORMATION_CLASS values (listed from lowest to highest enum value):
| FILE_INFORMATION_CLASS value | Type of information returned |
|---|---|
| FileBasicInformation (4) | A FILE_BASIC_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter. |
| FileStandardInformation (5) | A FILE_STANDARD_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess. |
| FileInternalInformation (6) | A FILE_INTERNAL_INFORMATION structure. This structure specifies a 64-bit file ID that uniquely identifies a file in NTFS. On other file systems, this file ID is not guaranteed to be unique. |
| FileEaInformation (7) | A FILE_EA_INFORMATION structure. This structure specifies the size of the extended attributes block that is associated with the file. |
| FileAccessInformation (8) | A FILE_ACCESS_INFORMATION structure. This structure contains an access mask. For more information about access masks, see ACCESS_MASK. |
| FileNameInformation (9) | A FILE_NAME_INFORMATION structure. The structure can contain the file’s full path or only a portion of it. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess. For more information about the file-name syntax, see the Remarks section later in this topic. |
| FilePositionInformation (14) | A FILE_POSITION_INFORMATION structure. The caller must have opened the file with the DesiredAccess FILE_READ_DATA or FILE_WRITE_DATA flag specified in the DesiredAccess parameter, and with the FILE_SYNCHRONOUS_IO_ALERT or FILE_SYNCHRONOUS_IO_NONALERT flag specified in the CreateOptions parameter. |
| FileModeInformation (16) | A FILE_MODE_INFORMATION structure. This structure contains a set of flags that specify the mode in which the file can be accessed. These flags are a subset of the options that can be specified in the CreateOptions parameter of the IoCreateFile routine. |
| FileAlignmentInformation (17) | A FILE_ALIGNMENT_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess. This information is useful if the file was opened with the FILE_NO_INTERMEDIATE_BUFFERING flag specified in the CreateOptions parameter. |
| FileAllInformation (18) | A FILE_ALL_INFORMATION structure. By combining several file-information structures into a single structure, FILE_ALL_INFORMATION reduces the number of queries required to obtain information about a file. |
| FileAlternateNameInformation (21) | A FILE_ALL_INFORMATION structure in which to return the alternate name information for a file (its 8.3 format name). |
| FileStreamInformation (22) | A buffer of FILE_STREAM_INFORMATION structures in which to enumerate the data streams of a file or a directory. |
| FileCompressionInformation (28) | A FILE_COMPRESSION_INFORMATION structure in which to return compression information for a file. |
| FileNetworkOpenInformation (34) | A FILE_NETWORK_OPEN_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter. |
| FileAttributeTagInformation (35) | A FILE_ATTRIBUTE_TAG_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter. |
| FileIoPriorityHintInformation (43) | A FILE_IO_PRIORITY_HINT_INFORMATION structure. The caller must have opened the file with the FILE_READ_DATA flag specified in the DesiredAccess parameter. |
| FileSfioReserveInformation (44) | A FILE_SFIO_RESERVE_INFORMATION structure. |
| FileHardLinkInformation (46) | A FILE_LINKS_INFORMATION structure. |
| FileNormalizedNameInformation (48) | A FILE_NAME_INFORMATION structure in which to return the normalized name of a file. |
| FileIsRemoteDeviceInformation (51) | A FILE_IS_REMOTE_DEVICE_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess. |
| FileStandardLinkInformation (54) | A FILE_STANDARD_LINK_INFORMATION structure. |
| FileIdInformation (59) | A FILE_ID_INFORMATION structure. |
| FileDesiredStorageClassInformation (67) | A FILE_DESIRED_STORAGE_CLASS_INFORMATION structure. |
| FileStatInformation (68) | FILE_STAT_INFORMATION |
| FileStatLxInformation (70) | FILE_STAT_LX_INFORMATION |
| FileCaseSensitiveInformation (71) | A FILE_CASE_SENSITIVE_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter. This value is available starting with Windows 10, version 1803. |
| FileStorageReserveIdInformation (74) | A FILE_STORAGE_RESERVE_ID_INFORMATION structure. |
| FileCaseSensitiveInformationForceAccessCheck (75) | A FILE_CASE_SENSITIVE_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter. This is a special version of the FileCaseSensitiveInformation operation that is used to force the IOManager to perform access checks for the kernel-mode driver, similar to the checks that apply to a user-mode caller. This operation is only recognized by the IOManager and a file system should never receive it. This value is available starting with Windows 10, version 1803. |
Return value
NtQueryInformationFile returns STATUS_SUCCESS or an appropriate NTSTATUS error code.
Remarks
NtQueryInformationFile returns information about the specified file object. Note that it returns zero in any member of a FILE_XXX_INFORMATION structure that is not supported by a particular device or file system.
When FileInformationClass = FileNameInformation, the file name is returned in the FILE_NAME_INFORMATION structure. The precise syntax of the file name depends on a number of factors:
If you opened the file by submitting a full path to NtCreateFile, NtQueryInformationFile returns that full path.
If the ObjectAttributes->RootDirectory handle was opened by name in a call to NtCreateFile, and subsequently the file was opened by NtCreateFile relative to this root-directory handle, NtQueryInformationFile returns the full path.
If the ObjectAttributes->RootDirectory handle was opened by file ID (using the FILE_OPEN_BY_FILE_ID flag) in a call to NtCreateFile, and subsequently the file was opened by NtCreateFile relative to this root-directory handle, NtQueryInformationFile returns the relative path.
However, if the user has SeChangeNotifyPrivilege (described in the Microsoft Windows SDK documentation), NtQueryInformationFile returns the full path in all cases.
If only the relative path is returned, the file name string will not begin with a backslash.
If the full path and file name are returned, the string will begin with a single backslash, regardless of its location. Thus the file C:\dir1\dir2\filename.ext will appear as \dir1\dir2\filename.ext, while the file \server\share\dir1\dir2\filename.ext will appear as \server\share\dir1\dir2\filename.ext.
If NtQueryInformationFile fails because of a buffer overflow, drivers that implement FileNameInformation should return as many WCHAR characters of the file name as will fit in the buffer and specify the full length that is required in the FileNameLength parameter of the FILE_NAME_INFORMATION structure. You should reissue the query by using the file name length so that you can retrieve the full file name. Drivers that do not follow this pattern might require a gradual increase in length until they retrieve the full file name. For more information about working with files, see Using Files in a Driver.
Callers of NtQueryInformationFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.
If the call to this function occurs in user mode, you should use the name «NtQueryInformationFile» instead of «ZwQueryInformationFile«.
For calls from kernel-mode drivers, the NtXxx and ZwXxx versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
