Device Identification Strings

The Plug and Play (PnP) manager and other device installation components use device identification strings to identify devices that are installed in a computer.

Windows uses the following device identification strings to locate the information (INF) file that best matches the device. These strings are reported by a device’s enumerator, a system component that discovers PnP devices based on a PnP hardware standard. These tasks are carried out by PnP Bus Drivers in partnership with the PnP manager. A device is typically enumerated by its parent bus driver, such as the PCI or PCMCIA bus driver. Some devices are enumerated by a bus filter driver, such as the ACPI Driver.

Windows tries to find a match for one of the hardware IDs or compatible IDs. For more information about how Windows uses these IDs to match a device to an INF file, and how to specify IDs in an INF file, see How Windows Selects Drivers.

In addition to using the preceding IDs to identify devices, the PnP manager uses the following IDs to uniquely identify instances of each device that are installed in a computer:

Starting with Windows 7, the PnP manager uses the Container ID device identification string to group one or more device nodes (devnodes) that were enumerated from each instance of a physical device installed in a computer.

Each enumerator customizes its device IDs, hardware IDs, and compatible IDs to uniquely identify the device that it enumerates. In addition, each enumerator has its own policy to identify hardware IDs and compatible IDs. For more information about hardware ID and compatible ID formats for most of the system buses, see Device Identifier Formats.

Device identification strings should not be parsed. They are meant only for string comparisons and should be treated as opaque strings.

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.

ZwQueryInformationFile function (wdm.h)

The ZwQueryInformationFile routine returns various kinds of information about a file object.

Syntax

Parameters

[in] Handle to a file object. The handle is created by a successful call to ZwCreateFile or ZwOpenFile.

[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.

FILE_INFORMATION_CLASS value	Type of information returned
FileAccessInformation	A FILE_ACCESS_INFORMATION structure. This structure contains an access mask. For more information about access masks, see ACCESS_MASK.
FileAlignmentInformation	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	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.
FileAttributeTagInformation	A FILE_ATTRIBUTE_TAG_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.
FileBasicInformation	A FILE_BASIC_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.
FileEaInformation	A FILE_EA_INFORMATION structure. This structure specifies the size of the extended attributes block that is associated with the file.
FileInternalInformation	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.
FileIoPriorityHintInformation	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.
FileModeInformation	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.
FileNameInformation	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.
FileNetworkOpenInformation	A FILE_NETWORK_OPEN_INFORMATION structure. The caller must have opened the file with the FILE_READ_ATTRIBUTES flag specified in the DesiredAccess parameter.
FilePositionInformation	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.
FileStandardInformation	A FILE_STANDARD_INFORMATION structure. The caller can query this information as long as the file is open, without any particular requirements for DesiredAccess.
FileIsRemoteDeviceInformation	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.

Return value

ZwQueryInformationFile returns STATUS_SUCCESS or an appropriate NTSTATUS error code.

Remarks

ZwQueryInformationFile 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 ZwCreateFile, ZwQueryInformationFile returns that full path.
• If the ObjectAttributes->RootDirectory handle was opened by name in a call to ZwCreateFile, and subsequently the file was opened by ZwCreateFile relative to this root-directory handle, ZwQueryInformationFile 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 ZwCreateFile, and subsequently the file was opened by ZwCreateFile relative to this root-directory handle, ZwQueryInformationFile returns the relative path.
• However, if the user has SeChangeNotifyPrivilege (described in the Microsoft Windows SDK documentation), ZwQueryInformationFile 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 ZwQueryInformationFile 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 ZwQueryInformationFile must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

Windows Device Portal for Desktop

Windows Device Portal (WDP) is a device management and debugging tool that lets you configure and manage device settings and view diagnostic information over HTTP from a web browser. For WDP details on other devices, see Windows Device Portal overview.

You can use the WDP for the following:

• Manage device settings (similar to the Windows Settings app)
• See and manipulate a list of running processes
• Install, delete, launch, and terminate apps
• Change Wi-Fi profiles, view signal strength, and see ipconfig details
• View live graphs of CPU, memory, I/O, network, and GPU usage
• Collect process dumps
• Collect ETW traces
• Manipulate the isolated storage of sideloaded apps

Set up Windows Device Portal on a Desktop device

Turn on developer mode

Starting in Windows 10, version 1607, some of the newer features for desktop are only available when developer mode is enabled. For information about how to enable developer mode, see Enable your device for development.

Sometimes, due to network or compatibility issues, developer mode won’t install correctly on your device. See the relevant section of Enable your device for development for help troubleshooting these issues.

Turn on Windows Device Portal

You can enable WDP in the For developers section of Settings. When you enable it, you must also create a corresponding username and password. Do not use your Microsoft account or other Windows credentials.

Once WDP is enabled, you will see web links at the bottom of the section. Take note of the port number appended to the end of the listed URLs: this number is randomly generated when WDP is enabled but should remain consistent between reboots of the desktop.

These links offer two ways to connect to WDP: over the local network (including VPN) or through the local host. Once you connect, it should look something like this:

Turn off Windows Device Portal

You can disable WDP in the For developers section of Windows Settings.

Connect to Windows Device Portal

To connect through local host, open a browser window and enter the one of the URIs shown here (based on the connection type you’re using).

Local Network: https:// :

HTTPS is required for authentication and secure communication.

If you are using WDP in a protected environment, for example, in a test lab, in which you trust everyone on your local network, have no personal information on the device, and have unique requirements, you can disable the Authentication option. This enables unencrypted communication, and allows anyone with the IP address of your computer to connect to and control it.

Windows Device Portal content

WDP provides the following set of pages.

• Apps manager
• Xbox Live
• File explorer
• Running Processes
• Performance
• Debug
• ETW (Event Tracing for Windows) logging
• Performance tracing
• Device manager
• Bluetooth
• Networking
• Crash data
• Features
• Mixed Reality
• Streaming Install Debugger
• Location
• Scratch

Using Windows Device Portal to test and debug MSIX apps

More Windows Device Portal options

Registry-based configuration

If you would like to select port numbers for WDP (such as 80 and 443), you can set the following regkeys:

• Under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\WebManagement\Service
  • UseDynamicPorts : A required DWORD. Set this to 0 in order to retain the port numbers you’ve chosen.
  • HttpPort : A required DWORD. Contains the port number on which WDP listens for HTTP connections.
  • HttpsPort : A required DWORD. Contains the port number on which WDP listens for HTTPS connections.

Under the same regkey path, you can also turn off the authentication requirement:

• UseDefaultAuthorizer — 0 for disabled, 1 for enabled.
  • This controls both the basic auth requirement for each connection and the redirect from HTTP to HTTPS.

Command line options for Windows Device Portal

From an administrative command prompt, you can enable and configure parts of WDP. To see the latest set of commands supported on your build, you can run webmanagement /?

• sc start webmanagement or sc stop webmanagement
  • Turn the service on or off. This still requires developer mode to be enabled.
• -Credentials
  • Set a username and password for WDP. The username must conform to Basic Auth standards, so cannot contain a colon (:) and should be built out of standard ASCII characters for example, [a-zA-Z0-9] as browsers do not parse the full character set in a standard way.
• -DeleteSSL
  • This resets the SSL certificate cache used for HTTPS connections. If you encounter TLS connection errors that cannot be bypassed (as opposed to the expected certificate warning), this option may fix the problem for you.
• -SetCert
  • See Provisioning Windows Device Portal with a custom SSL certificate for details.
  • This allows you to install your own SSL certificate to fix the SSL warning page that is typically seen in WDP.
• -Debug
  • Run a standalone version of WDP with a specific configuration and visible debug messages. This is most useful for building a packaged plugin.
  • See the MSDN Magazine article for details on how to run this as System to fully test your packaged plugin.

Troubleshooting

Below are some common errors that you may encounter when setting up Windows Device Portal.

WindowsUpdateSearch returns invalid number of updates (0x800f0950 CBS_E_INVALID_WINDOWS_UPDATE_COUNT)

You may get this error when trying to install the developer packages on a pre-release build of Windows 10. These Feature-on-Demand (FoD) packages are hosted on Windows Update, and downloading them on pre-release builds requires that you opt into flighting. If your installation is not opted into flighting for the right build and ring combination, the payload will not be downloadable. Double-check the following:

Navigate to Settings > Update & Security > Windows Insider Program and confirm that the Windows Insider account section has your correct account info. If you don’t see that section, select Link a Windows Insider account, add your email account, and confirm that it shows up under the Windows Insider account heading (you may need to select Link a Windows Insider account a second time to actually link a newly added account).

Under What kind of content would you like to receive?, make sure Active development of Windows is selected.

Under What pace do you want to get new builds?, make sure Windows Insider Fast is selected.

You should now be able to install the FoDs. If you’ve confirmed that you’re on Windows Insider Fast and still cannot install the FoDs, please provide feedback and attach the log files under C:\Windows\Logs\CBS.

[SC] StartService: OpenService FAILED 1060: The specified service does not exist as an installed service

You may get this error if the developer packages aren’t installed. Without the developer packages, there is no web management service. Try installing the developer packages again.

CBS cannot start download because the system is on metered network (CBS_E_METERED_NETWORK)

You may get this error if you’re on a metered internet connection. You won’t be able to download the developer packages on a metered connection.