SetupDiGetClassDevsExA function (setupapi.h)
The SetupDiGetClassDevsEx function returns a handle to a device information set that contains requested device information elements for a local or a remote computer.
Syntax
WINSETUPAPI HDEVINFO SetupDiGetClassDevsExA(
[in, optional] const GUID *ClassGuid,
[in, optional] PCSTR Enumerator,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[in, optional] HDEVINFO DeviceInfoSet,
[in, optional] PCSTR MachineName,
PVOID Reserved
);
Parameters
[in, optional] ClassGuid
A pointer to the GUID for a device setup class or a device interface class. This pointer is optional and can be NULL. If a GUID value is not used to select devices, set ClassGuid to NULL. For more information about how to use ClassGuid, see the following Remarks section.
[in, optional] Enumerator
A pointer to a NULL-terminated string that specifies:
- An identifier (ID) of a Plug and Play (PnP) enumerator. This ID can either be the enumerator's globally unique identifier (GUID) or symbolic name. For example, "PCI" can be used to specify the PCI PnP enumerator. Other examples of symbolic names for PnP enumerators include "USB", "PCMCIA", and "SCSI".
- A PnP device instance IDs. When specifying a PnP device instance ID, DIGCF_DEVICEINTERFACE must be set in the Flags parameter.
For more information about how to set the Enumerator value, see the following Remarks section.
[in, optional] hwndParent
A handle to the top-level window to be used for a user interface that is associated with installing a device instance in the device information set. This handle is optional and can be NULL.
[in] Flags
A variable of type DWORD that specifies control options that filter the device information elements that are added to the device information set. This parameter can be a bitwise OR of one or more of the following flags. For more information about combining these control options, see the following Remarks section.
DIGCF_ALLCLASSES
Return a list of installed devices for the specified device setup classes or device interface classes.
DIGCF_DEVICEINTERFACE
Return devices that support device interfaces for the specified device interface classes. This flag must be set in the Flags parameter if the Enumerator parameter specifies a device instance ID.
DIGCF_DEFAULT
Return only the device that is associated with the system default device interface, if one is set, for the specified device interface classes.
DIGCF_PRESENT
Return only devices that are currently present.
DIGCF_PROFILE
Return only devices that are a part of the current hardware profile.
[in, optional] DeviceInfoSet
The handle to an existing device information set to which SetupDiGetClassDevsEx adds the requested device information elements. This parameter is optional and can be set to NULL. For more information about using this parameter, see the following Remarks section.
[in, optional] MachineName
A pointer to a constant string that contains the name of a remote computer on which the devices reside. A value of NULL for MachineName specifies that the device is installed 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
Reserved for internal use. This parameter must be set to NULL.
Return value
If the operation succeeds, SetupDiGetClassDevsEx returns a handle to a device information set that contains all installed devices that matched the supplied parameters. If the operation fails, the function returns INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
Remarks
The caller of SetupDiGetClassDevsEx must delete the returned device information set when it is no longer needed by calling SetupDiDestroyDeviceInfoList.
If DeviceInfoSet is NULL, SetupDiGetClassDevsEx creates a new device information set that contains the retrieved device information elements and returns a handle to the new device information set. If the caller requests that the function retrieve devices for a device setup class that is supplied by the ClassGuid parameter, the function sets the device setup class of the new device information set to the supplied class GUID.
If DeviceInfoSet is not set to NULL, the function adds the retrieved device information elements to the device information set that is associated with the supplied handle, and returns the supplied handle. If ClassGuid supplies a device setup class, the device setup class of the supplied device information set must be set to the supplied class GUID.
Device Setup Class Control Options
Use the following filtering options to control whether SetupDiGetClassDevsEx returns devices for all device setup classes or only for a specified device setup class:- To return devices for all device setup classes, set the DIGCF_ALLCLASSES flag and set the ClassGuid parameter to NULL.
- To return devices only for a specific device setup class, do not set DIGCF_ALLCLASSES and use ClassGuid to supply the GUID of the device setup class.
- To return only devices that are present in the system, set the DIGCF_PRESENT flag.
- To return only devices that are part of the current hardware profile, set the DIGCF_PROFILE flag.
- To return devices for a specific PnP enumerator only, use the Enumerator parameter to supply the GUID or symbolic name of the enumerator. If Enumerator is NULL, SetupDiGetClassDevsEx returns devices for all PnP enumerators.
Device Interface Class Control Options
Use the following filtering options to control whether SetupDiGetClassDevsEx returns devices that support any device interface class or only devices that support a specified device interface class:- To return devices that support a device interface of any class, set the DIGCF_DEVICEINTERFACE flag, set the DIGCF_ALLCLASSES flag, and set ClassGuid to NULL. The function adds to the device information set a device information element that represents such a device, and then adds to the device information element a device interface list that contains all the device interfaces that the device supports.
- To return only devices that support a device interface of a specified class, set the DIGCF_DEVICEINTERFACE flag and use the ClassGuid parameter to supply the class GUID of the device interface class. The function adds to the device information set a device information element that represents such a device, and then adds a device interface of the specified class to the device interface list for that device information element.
- To return only the device that supports the system default interface, if one is set, for a specified device interface class, set the DIGCF_DEVICEINTERFACE flag, set the DIGCF_DEFAULT flag, and use ClassGuid to supply the class GUID of the device interface class. The function adds to the device information set a device information element that represents such a device, and then adds the system default interface to the device interface list for that device information element.
- To return a device that supports a system default interface for an unspecified device interface class, set the DIGCF_DEVICEINTERFACE flag, set the DIGCF_ALLCLASSES flag, set the DIGCF_DEFAULT flag, and set ClassGuid to NULL. The function adds to the device information set a device information element that represents such a device, and then adds the system default interface to the device interface list for that device information element.
- To return only devices that are present in the system, set the DIGCF_PRESENT flag.
- To return only devices that are part of the current hardware profile, set the DIGCF_PROFILE flag.
- To return only a specific device, set the DIGCF_DEVICEINTERFACE flag and use the Enumerator parameter to supply the device instance ID of the device. To include all possible devices, set Enumerator to NULL.
Retrieving Devices in a Device Setup Class That Support a Device Interface Class
An installer can use SetupDiGetClassDevsEx to retrieve a list of devices of a particular device setup class that support a device interface of a specified device interface class. For example, to retrieve a list of all devices on a local computer that support a device interface in the "mounted device" interface class and that are members of the "Volume" device setup class, an installer should perform the following operations:- Call SetupDiCreateDeviceInfoList to create an empty device information set for the "Volume" device setup class. Set ClassGuid to a pointer to the class GUID for the "Volume" device setup class and set hwndParent as appropriate. In response to such a call, the function will return a handle to type HDEVINFO to the device information set.
- Call SetupDiGetClassDevsEx with the following settings:
- Set ClassGuid to a pointer to the class GUID of the "mounted device" device interface class.
- Set Flags to DIGCF_DEVICEINTERFACE.
- Set DeviceInfoSet to the HDEVINFO handle obtained in step (1).
- Set hwndParent as appropriate and the remaining parameters to NULL.
Note
The setupapi.h header defines SetupDiGetClassDevsEx 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 |