Device Information Sets

In user mode, devices that belong to either device setup classes or device interface classes are managed by using device information elements and device information sets. A device information set consists of device information elements for all the devices that belong to some device setup class or device interface class.

Each device information element contains a handle to the device’s devnode, and a pointer to a linked list of all the device interfaces associated with the device described by that element. If a device information set describes members of a setup class, the element might not point to any device interfaces, since setup class members are not necessarily associated with an interface.

The following diagram shows the internal structure of a device information set.

Creating a Device Information Set

After creating a device information set with SetupDiCreateDeviceInfoList, device information elements can be created and added to the list one at a time using SetupDiCreateDeviceInfo. Alternatively, SetupDiGetClassDevs can be called to create a device information set composed of all devices associated with a specified device setup class or device interface class.

Enumerating Device Information

Once a device information set is created, both the devices and the device interfaces that belong to the set can be enumerated, but different operations are required for each type of enumeration. SetupDiEnumDeviceInfo enumerates all devices that belong to the information set that meet certain criteria. Each call to SetupDiEnumDeviceInfo extracts a SP_DEVINFO_DATA structure that roughly corresponds to a device information element. SP_DEVINFO_DATA contains the GUID of the class that the device belongs to and a device instance handle that points to the devnode for the device. The principal difference between an SP_DEVINFO_DATA structure and a complete device element is that SP_DEVINFO_DATA does not contain the linked list of interfaces associated with the device. Therefore, SetupDiEnumDeviceInfo cannot be used to enumerate the interfaces in the device information set.

To enumerate the device interfaces in a device information set, call SetupDiEnumDeviceInterfaces. This routine steps through all the device information elements in the device information set, extracts the interfaces in the interface list of each element, and returns one interface with each call. If SetupDiEnumDeviceInterfaces is passed an SP_DEVINFO_DATA structure as input in its second parameter, it constrains the enumeration to only those interfaces that are associated with the device indicated by SP_DEVINFO_DATA.

SetupDiEnumDeviceInterfaces returns an SP_DEVICE_INTERFACE_DATA structure. SP_DEVICE_INTERFACE_DATA contains the interface class GUID and other information about the interface, including a reserved field that has encoded information that can be used to obtain the name of the interface. To get the interface name, one further step is required: SetupDiGetDeviceInterfaceDetail must be called. SetupDiGetDeviceInterfaceDetail returns a structure of type SP_DEVICE_INTERFACE_DETAIL_DATA that contains the path in the system object tree that defines the interface.

General Syntax Rules for INF Files

An INF file is a text file organized into named sections. Some sections have system-defined names and some sections have names determined by the writer of the INF file.

Each section contains section-specific entries that are interpreted by device installation components (class installers, co-installers, SetupAPI). Some entries begin with a predefined keyword. These entries are called directives.

Some INF file entries are basically pointers from one section to another, for a specific purpose. For example, an INF AddReg directive identifies a section that contains entries that instruct Windows to modify the registry. These entries sometimes include additional arguments (required or optional) for Windows to interpret during installation.

Other INF file entries do not point to other sections, but supply information that Windows uses during installation, such as file names, registry values, hardware configuration information, flags, and so on. For example, an INF DriverVer directive supplies driver version information.

When Windows begins an installation, it first looks for an INF Version section to verify the validity of the INF file and to determine where installation files are located. Then it starts the installation by finding an INF Manufacturer section. This section contains directives to INF Models sections, which in turn provide directives leading to various INF DDInstall sections, based on the hardware ID of the device being installed.

The following syntax rules govern the required and optional contents of INF files, the format of section names by using string tokens, and line format, continuation, and comments.

Case Sensitivity

• Section names, entries, and directives are case-insensitive. For example, version, VERSION, and Version are equally valid section name specifications within an INF file.

Required and Optional Contents

The set of required and optional sections, entries, and directives in any particular INF file depends on the type of device/driver or component (such as an application or device class installer DLL) to be installed.

The set of sections, section-specific entries, and directives required to install any particular device and its drivers also depends somewhat on the corresponding class installer. For more information about how the system-supplied class installers handle device-type-specific INF files, see the device-type specific documentation in the WDK.

Within syntax definitions, optional entries are delimited by unbolded brackets ([,]). On the other hand, bold brackets ([, ]) are required elements of the entry in which they are contained. In the following example, the brackets around Version are required, while the brackets around Class=class-name indicate this entry is optional.

Section Names

Sections can be specified in any order. Most INF files list sections in a particular order, by convention, but Windows finds sections by name, not by location within the INF file.

Each section in an INF file begins with the section name enclosed in brackets ([ ]). The section name can be system-defined or INF-writer-defined.

For example, [Manufacturer] specifies the start of the system-named Manufacturer section, while [Std.Mfg] represents a particular INF-writer-defined Models section name.

A section name has a maximum length of 255 characters on Windows 2000 and later versions of Windows.

Each section ends at the beginning of a new [section-name] or at the end-of-file mark.

If more than one section in an INF file has the same name, the system merges their entries and directives into a single section.

Unless it is enclosed in double quotation marks characters («), an INF-writer-defined section name must be a unique-to-the-INF unquoted string of explicitly visible characters, excluding certain characters with INF-specific meanings. In particular, an unquoted section name referenced by a section entry or directive cannot have leading or trailing spaces, a linefeed character, a return character, or any invisible control character, and it should not contain tabs. In addition, it cannot contain either of the bracket ([ ]) characters, a single percent (%) character, a semicolon (;), or any internal double quotation marks («) characters, and it cannot have a backslash (\) as its last character.

For example, Std.Mfg and Std_Mfg are unique and valid section names when referenced by an INF file entry or directive, but Std;Mfg (with its internal semicolon) is invalid unless it is enclosed by double quotation marks («).

Specifying an INF-writer-defined section name as a «quoted string« overrides most of the restrictions that were previously described on characters in referenced section names. Such a delimited section name can contain almost any explicitly or implicitly visible characters except the closing bracket (]) as long as the corresponding section in the INF file matches this «quoted string« exactly.

For example, «;; Std Mfg « is a valid section-name reference if the corresponding section declaration in the INF file exactly matches the name inside the double quotation marks with respect to its space and semicolon characters as [;; Std Mfg ].

Using String Tokens

Many values in an INF file, including INF-writer-defined section names, can be expressed as string key tokens of the form %strkey%. In the INF Strings section of the INF file, each string key must be associated with a string value that consists of a sequence of explicitly visible characters. If necessary, the setup code converts the string value, into Unicode.

For more information about how to define %strkey% tokens and their respective values, see the description of the INF Strings section.

Line Format, Continuation, and Comments

Each entry and directive in a section ends with a return or linefeed character. Therefore, the text editor used to create an INF file must not insert return or linefeed characters after some arbitrary, editor-determined number of characters.

The backslash character (\) can be used as an explicit line continuator in an entry or directive. However, backslash characters are used also in path specifications. To ensure that a backslash character that appears in a path specification is not misinterpreted as a line continuator, use the following strategy:

For a directive that spans two lines, one of which is an entry that contains a backslash, use quotation marks to delimit the entry that contains the backslash.

Avoid using the backslash character in the manner shown in the following example. Windows ignores the first backslash and interprets the second backslash as a line continuator.

The following syntax is valid and is equivalent to CopyFiles = «SomeDirectory\»,SomeFile ; comment .

Because text after a semicolon is ignored, CopyFiles = «SomeDirectory\» ; comment ,SomeFile does not work.

Comments begin with a semicolon (;) character. When parsing and interpreting an INF file, the system assumes that the following have no relevance to the installation process:

• Any characters following a semicolon on the same line, unless the semicolon appears within a «quoted string« or %strkey% token
• Any empty line that contains nothing except a linefeed or return character

Commas separate the values supplied in section entries and directives.

An INF file entry or directive can omit an optional value in the middle of a list of values, but the commas must remain. INF files can omit trailing commas.

For example, consider the syntax for a SourceDisksFiles section entry:

filename=diskid[,[subdir][,size]]

An entry that omits the subdir value but supplies the size value must specify the comma delimiters for both values, as shown in the following example:

filename=diskid,,size

An entry in an INF file that omits the two optional values can have this format:

filename=diskid

In order to include a percent (%) character in values supplied in section entries and directives, escape the percent character with another percent character.

For example, consider this statement in an [add-registry-section] section:

The registry value will be set with the following value:

In order to include a double quote («) character in values supplied in section entries and directives, escape the double quote character with another double quote character. Note that the string must be within a «quoted string«.

For example, consider this statement in an [add-registry-section] section:

HKR,,Example,,»Display an «»example»» string»

The registry value will be set with the following value:

Display an «example» string

INF Size Limits

The maximum length, in characters, of an INF file field, before string substitution and including a terminating NULL character, is 4096.

After string substitution, the maximum length, in characters, of an INF file string is 4096, which includes a terminating NULL character.

However, be aware that Plug and Play (PnP) may impose a more restrictive limit for certain INF file fields that it recognizes or uses, such as device description, driver provider, and device manufacturer.

NT Device Names

A named device object has a name of the form \Device\DeviceName. This is known as the NT device name of the device object.

Device Names for WDM Drivers

WDM drivers do not name their device objects directly. Instead, the system imposes a uniform naming scheme that ensures that device names do not conflict between drivers. The naming scheme for WDM drivers is as follows.

The PDO for a device is named. The bus driver requests named PDOs for the devices it enumerates. The bus driver specifies the FILE_AUTOGENERATED_DEVICE_NAME device characteristic when it creates the device object. For more information, see Specifying Device Characteristics. The system then automatically generates the device name.

FDOs and filter DOs are not named. Function and filter drivers do not request a name when creating the device object.

Any I/O request to a named device object automatically goes to the top object in that device object’s stack. Thus, only the PDO is required to be named. User-mode applications do not refer to WDM device objects by name; instead, applications access the device object through its device interface. For more information, see Device Interface Classes.

Driver writers must not name more than one object in a device stack. The operating system checks security settings based on the named object. If two different objects are named and have different security descriptors, the I/O requests that are sent to the object with the weaker security descriptor can reach the device object with the stronger security descriptor.

Device Names for non-WDM Drivers

A non-WDM driver must explicitly specify a name for any named device objects. The driver must create at least one named device object in the \Device object directory to receive I/O requests. The driver specifies the device name as the DeviceName parameter to IoCreateDeviceSecure when creating the device object.