SetupDiGetClassDevs

Windows Driver Kit: Device Installation

SetupDiGetClassDevs

The SetupDiGetClassDevs function returns a handle to a device information set that contains requested device information elements for a local computer.

HDEVINFO
  SetupDiGetClassDevs(
    IN LPGUID  ClassGuid..OPTIONAL,
    IN PCTSTR  Enumerator..OPTIONAL,
    IN HWND  hwndParent..OPTIONAL,
    IN DWORD  Flags
    );

Parameters

ClassGuid

A pointer to the GUID for a device setup class or a device interface class. This pointer is optional and can be NULL. For more information about how to set ClassGuid, see the following Comments section.

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 value’s globally unique identifier (GUID) or symbolic name. For example, “PCI” can be used to specify the PCI PnP value. Other examples of symbolic names for PnP values include “USB,” “PCMCIA,” and “SCSI”.
A PnP device instance ID. When specifying a PnP device instance ID, DIGCF_DEVICEINTERFACE must be set in the Flags parameter.

This pointer is optional and can be NULL. If an enumeration value is not used to select devices, set Enumerator to NULL

For more information about how to set the Enumerator value, see the following Comments section.

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.

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 zero or more of the following flags. For more information about combining these flags, see the following Comments section.

DIGCF_ALLCLASSES: Return a list of installed devices for all device setup classes or all 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 in a system.
DIGCF_PROFILE: Return only devices that are a part of the current hardware profile.

Return Value

If the operation succeeds, SetupDiGetClassDevs 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.

Comments

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

Call SetupDiGetClassDevsEx to retrieve the devices for a class on a remote computer.

Device Setup Class Control Options

Use the following filtering options to control whether SetupDiGetClassDevs 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.

In addition, you can use the following filtering options in combination with one another to further restrict which devices are returned:

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 only for a specific PnP enumerator, use the Enumerator parameter to supply the GUID or symbolic name of the enumerator. If Enumerator is NULL, SetupDiGetClassDevs returns devices for all PnP enumerators.

Device Interface Class Control Options

Use the following filtering options to control whether SetupDiGetClassDevs 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 DIFCF_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 DIFCF_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.

In addition, you can use the following filtering options to control whether SetupDiGetClassDevs returns only devices that support the system default interface for device interface classes:

To return only the device that supports the system default interface, if one is set, for a specified device interface class, set the DIFCF_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 DIFCF_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.

You can also use the following options in combination with the other options to further restrict which devices are returned:

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

Examples

The following are some examples of how to use the SetupDiGetClassDevs function.

Example 1: Build a list of all devices in the system, including devices that are not currently present.: Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);
Example 2: Build a list of all devices that are present in the system.: Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);
Example 3: Build a list of all devices that are present in the system that are from the network adapter device setup class.: Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);
Example 4: Build a list of all devices that are present in the system that have enabled an interface from the storage volume device interface class.: Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);

Requirements

Versions: The SetupDiGetClassDevs function is available in Microsoft Windows 2000 and later versions of Windows.

Headers: Declared in Setupapi.h. Include Setupapi.h.

Library: Contained in Setupapi.lib. Link to Setupapi.lib.