SetupDiGetClassDevsEx

The SetupDiGetClassDevsEx function retrieves a device information set that contains all devices of a specified class on a local or remote computer.

HDEVINFO SetupDiGetClassDevsEx(
  CONST LPGUID ClassGuid, 
  PCTSTR Enumerator, 
  HWND hwndParent, 
  DWORD Flags,
  HDEVINFO DeviceInfoSet, 
  PCTSTR MachineName, 
  PVOID Reserved
);

Parameters

ClassGuid

[in] An optional pointer to a class GUID for a setup class or an interface class. If the DIGCF_DEVICEINTERFACE flag is set, ClassGuid represents an interface class; otherwise, ClassGuid represents a setup class.

If the DIGCF_ALLCLASSES flag is set, this parameter is ignored and the resulting list contains devices of all installed classes.

Enumerator

[in] An optional pointer to a string that filters the devices that are returned.

If the DIGCF_DEVICEINTERFACE flag is set, this parameter is an optional pointer to a string representing the PnP name of a particular device. This function examines this particular device only to determine whether it exposes any interfaces of the requested interface class.

If the DIGCF_DEVICEINTERFACE flag is not set, this parameter optionally specifies the name of the PnP enumerator that enumerates the devices of interest. (The names of system-supplied enumerators appear in the DDK header file Register.h.) This function examines only device instances of this enumerator. If this parameter is NULL, this function retrieves device information for all device instances on the system.

hwndParent

[in] Specifies the handle to the top-level window to be used for any user interface relating to the members of this set.

Flags

[in] Specifies control options used in building the device information set. This parameter can be one or more of the following values.

Value	Meaning
DIGCF_ALLCLASSES	Return a list of installed devices for all classes. If this flag is set, the ClassGuid parameter is ignored.
DIGCF_DEVICEINTERFACE	Return devices that expose interfaces of the interface class specified by ClassGuid. If this flag is not set, ClassGuid specifies a setup class.
DIGCF_PRESENT	Return only devices that are currently present.
DIGCF_PROFILE	Return only devices that are a part of the current hardware profile.

DeviceInfoSet

[in] Optionally specifies a handle to an existing device information set to which these new device information elements will be added. If the Flags parameter includes the value DIGCF_DEVICEINTERFACE, device interfaces will also be added.

If this parameter is specified, the same handle is returned upon success, with the new elements and interfaces added. If this parameter is zero, a new device information set is created and its handle is returned.

MachineName

[in] Optionally specifies the name of a remote computer on which the device resides. A value of NULL for MachineName specifies that the device resides on the local computer.

Reserved

Reserved; must be NULL.

Return Values

If the function succeeds, the return value is a handle to a device information set containing all devices matching the specified parameters.

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

To destroy the device information set when you have finished, call the SetupDiDestroyDeviceInfoList function.

If DIGCF_DEVICEINTERFACE is set, ClassGuid (if used) must point to a device interface class GUID, and Enumerator (if used) must point to a PnP device name. The returned device information set contains devices that expose interfaces of the requested interface class. Enumerate the interfaces of the devices using the SetupDiEnumDeviceInterfaces function.

If DIGCF_DEVICEINTERFACE is not set, ClassGuid (if used) must point to a setup class GUID, and Enumerator (if used) must specify the name of the PnP enumerator that enumerates the devices of interest.

If the DeviceInfoSet parameter is specified, the associated class of this device information set (if any) must match the ClassGuid specified, if it is a setup class. If the DIGCF_DEVICEINTERFACE flag is set, the device interfaces retrieved are filtered based on whether their corresponding device's setup class matches that of the device information set. This feature can be used to retrieve a list of device interfaces of a particular interface class, but only if those interfaces are exposed by devices of a particular setup class. For example, suppose there is a device information set whose associated setup class is Volume. To retrieve a list of all device interfaces of interface class Mounted Device, call SetupDiGetClassDevsEx passing in the handle to the device information set. The result is a device information set containing all devices of interface class Mounted Device that are exposed by devices of setup class Volume.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Setupapi.h.
  Library: Use Setupapi.lib.

See Also

Device Management Overview, Device Management Functions, SetupDiDestroyDeviceInfoList, SetupDiEnumDeviceInterfaces