SetupDiCreateDeviceInfoListExW function (setupapi.h)

Article
02/09/2023

The SetupDiCreateDeviceInfoList function creates an empty device information set on a remote or a local computer and optionally associates the set with a device setup class .

Syntax

WINSETUPAPI HDEVINFO SetupDiCreateDeviceInfoListExW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] HWND       hwndParent,
  [in, optional] PCWSTR     MachineName,
                 PVOID      Reserved
);

Parameters

[in, optional] ClassGuid

A pointer to the GUID of the device setup class to associate with the newly created device information set. If this parameter is specified, only devices of this class can be included in this device information set. If this parameter is set to NULL, the device information set is not associated with a specific device setup class.

[in, optional] hwndParent

A handle to the top-level window to use for any user interface that is related to non-device-specific actions (such as a select-device dialog box that uses the global class driver list). This handle is optional and can be NULL. If a specific top-level window is not required, set hwndParent to NULL.

[in, optional] MachineName

A pointer to a NULL-terminated string that contains the name of a computer on a network. If a name is specified, only devices on that computer can be created and opened in this device information set. If this parameter is set to NULL, the device information set is for devices on the local computer.

Caution

Using this function to access remote machines is not supported beginning with Windows 8 and Windows Server 2012, as this functionality has been removed.

Reserved

Must be NULL.

Return value

The function returns a handle to an empty device information set if it is successful. Otherwise, it returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The caller of this function must delete the returned device information set when it is no longer needed by calling SetupDiDestroyDeviceInfoList.

If the device information set is for devices on a remote computer (MachineName is not NULL), all subsequent operations on this set or any of its elements must use routines that support device information sets with remote elements. The SetupDiXxx routines that do not provide this support, such as SetupDiCallClassInstaller, have a statement to that effect in their reference page.

Note

The setupapi.h header defines SetupDiCreateDeviceInfoListEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 2000 and later versions of Windows.
Target Platform	Desktop
Header	setupapi.h (include Setupapi.h)
Library	Setupapi.lib