SetupDiGetClassDevsW-Funktion (setupapi.h)

Artikel
08/26/2023

Die SetupDiGetClassDevs-Funktion gibt ein Handle an einen Geräteinformationssatz zurück, der angeforderte Geräteinformationselemente für einen lokalen Computer enthält.

Syntax

WINSETUPAPI HDEVINFO SetupDiGetClassDevsW(
  [in, optional] const GUID *ClassGuid,
  [in, optional] PCWSTR     Enumerator,
  [in, optional] HWND       hwndParent,
  [in]           DWORD      Flags
);

Parameter

[in, optional] ClassGuid

Ein Zeiger auf die GUID für eine Geräteeinrichtungsklasse oder eine Geräteschnittstellenklasse. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen zum Festlegen von ClassGuid finden Sie im folgenden Abschnitt hinweise .

[in, optional] Enumerator

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die Folgendes angibt:

Ein Bezeichner (ID) eines Plug & Play (PnP)-Enumerators. Bei dieser ID kann es sich entweder um den global eindeutigen Bezeichner (GUID) des Werts oder um einen symbolischen Namen handeln. Beispielsweise kann "PCI" verwendet werden, um den PCI-PnP-Wert anzugeben. Weitere Beispiele für symbolische Namen für PnP-Werte sind "USB", "PCMCIA" und "SCSI".
Ein PnP-Gerät instance ID. Wenn Sie ein PnP-Gerät instance ID angeben, muss DIGCF_DEVICEINTERFACE im Flags-Parameter festgelegt werden.

Dieser Zeiger ist optional und kann NULL sein. Wenn kein Enumerationswert zum Auswählen von Geräten verwendet wird, legen Sie Enumerator auf NULL fest.

Weitere Informationen zum Festlegen des Enumeratorwerts finden Sie im folgenden Abschnitt Hinweise .

[in, optional] hwndParent

Ein Handle für das Fenster der obersten Ebene, das für eine Benutzeroberfläche verwendet werden soll, die der Installation eines Geräts instance im Geräteinformationssatz zugeordnet ist. Dieses Handle ist optional und kann NULL sein.

[in] Flags

Eine Variable vom Typ DWORD, die Steuerungsoptionen angibt, die die Geräteinformationselemente filtern, die dem Geräteinformationssatz hinzugefügt werden. Dieser Parameter kann ein bitweiser OR mit 0 oder mehr der folgenden Flags sein. Weitere Informationen zum Kombinieren dieser Flags finden Sie im folgenden Abschnitt mit den Anmerkungen .

DIGCF_ALLCLASSES

Gibt eine Liste der installierten Geräte für alle Geräteeinrichtungsklassen oder alle Geräteschnittstellenklassen zurück.

DIGCF_DEVICEINTERFACE

Gibt Geräte zurück, die Geräteschnittstellen für die angegebenen Geräteschnittstellenklassen unterstützen. Dieses Flag muss im Flags-Parameter festgelegt werden, wenn der Enumerator-Parameter ein Gerät instance ID angibt.

DIGCF_DEFAULT

Gibt nur das Gerät zurück, das der Systemstandardgeräteschnittstelle zugeordnet ist, sofern festgelegt, für die angegebenen Geräteschnittstellenklassen.

DIGCF_PRESENT

Gibt nur Geräte zurück, die derzeit in einem System vorhanden sind.

DIGCF_PROFILE

Gibt nur Geräte zurück, die Teil des aktuellen Hardwareprofils sind.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt SetupDiGetClassDevs ein Handle an einen Geräteinformationssatz zurück, der alle installierten Geräte enthält, die den angegebenen Parametern entsprechen. Wenn der Vorgang fehlschlägt, gibt die Funktion INVALID_HANDLE_VALUE zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Der Aufrufer von SetupDiGetClassDevs muss die zurückgegebenen Geräteinformationen löschen, wenn sie nicht mehr benötigt werden, indem SetupDiDestroyDeviceInfoList aufgerufen wird.

Rufen Sie SetupDiGetClassDevsEx auf, um die Geräte für eine Klasse auf einem Remotecomputer abzurufen.

Gerätesetupklassensteuerungsoptionen

Verwenden Sie die folgenden Filteroptionen, um zu steuern, ob SetupDiGetClassDevs Geräte für alle Gerätesetupklassen oder nur für eine angegebene Gerätesetupklasse zurückgibt:

Um Geräte für alle Geräteeinrichtungsklassen zurückzugeben, legen Sie das DIGCF_ALLCLASSES-Flag fest, und legen Sie den ClassGuid-Parameter auf NULL fest.
Um Geräte nur für eine bestimmte Geräteeinrichtungsklasse zurückzugeben, legen Sie nicht DIGCF_ALLCLASSES fest, und verwenden Sie ClassGuid , um die GUID der Geräteeinrichtungsklasse anzugeben.

Darüber hinaus können Sie die folgenden Filteroptionen in Kombination miteinander verwenden, um die zurückgegebenen Geräte weiter einzuschränken:

Um nur Geräte zurückzugeben, die im System vorhanden sind, legen Sie das Flag DIGCF_PRESENT fest.
Um nur Geräte zurückzugeben, die Teil des aktuellen Hardwareprofils sind, legen Sie das flag DIGCF_PROFILE fest.
Um Geräte nur für einen bestimmten PnP-Enumerator zurückzugeben, verwenden Sie den Enumerator-Parameter, um die GUID oder den symbolischen Namen des Enumerators anzugeben. Wenn EnumeratorNULL ist, gibt SetupDiGetClassDevs Geräte für alle PnP-Enumeratoren zurück.

Steuerungsoptionen der Geräteschnittstellenklasse

Verwenden Sie die folgenden Filteroptionen, um zu steuern, ob SetupDiGetClassDevs Geräte zurückgibt, die eine beliebige Geräteschnittstellenklasse unterstützen oder nur Geräte, die eine angegebene Geräteschnittstellenklasse unterstützen:

Um Geräte zurückzugeben, die eine Geräteschnittstelle einer beliebigen Klasse unterstützen, legen Sie das DIGCF_DEVICEINTERFACE-Flag fest, legen Sie das DIGCF_ALLCLASSES-Flag fest, und legen Sie ClassGuid auf NULL fest. Die Funktion fügt dem Geräteinformationssatz ein Geräteinformationselement hinzu, das ein solches Gerät darstellt, und fügt dann dem Geräteinformationselement eine Geräteschnittstellenliste hinzu, die alle vom Gerät unterstützten Geräteschnittstellen enthält.
Um nur Geräte zurückzugeben, die eine Geräteschnittstelle einer angegebenen Klasse unterstützen, legen Sie das DIGCF_DEVICEINTERFACE-Flag fest, und verwenden Sie den ClassGuid-Parameter , um die Klassen-GUID der Geräteschnittstellenklasse anzugeben. Die Funktion fügt dem Geräteinformationssatz ein Geräteinformationselement hinzu, das ein solches Gerät darstellt, und fügt dann der Geräteschnittstellenliste für dieses Geräteinformationselement eine Geräteschnittstelle der angegebenen Klasse hinzu.

Darüber hinaus können Sie die folgenden Filteroptionen verwenden, um zu steuern, ob SetupDiGetClassDevs nur Geräte zurückgibt, die die Systemstandardschnittstelle für Geräteschnittstellenklassen unterstützen:

Wenn Sie nur das Gerät zurückgeben möchten, das die Systemstandardschnittstelle unterstützt, legen Sie , falls festgelegt, für eine angegebene Geräteschnittstellenklasse das DIGCF_DEVICEINTERFACE-Flag fest, legen Sie das DIGCF_DEFAULT-Flag fest, und verwenden Sie ClassGuid , um die Klassen-GUID der Geräteschnittstellenklasse anzugeben. Die Funktion fügt dem Geräteinformationssatz ein Geräteinformationselement hinzu, das ein solches Gerät darstellt, und fügt dann die Systemstandardschnittstelle der Geräteschnittstellenliste für dieses Geräteinformationselement hinzu.
Um ein Gerät zurückzugeben, das eine Systemstandardschnittstelle für eine nicht angegebene Geräteschnittstellenklasse unterstützt, legen Sie das DIGCF_DEVICEINTERFACE-Flag fest, legen Sie das DIGCF_ALLCLASSES-Flag fest, legen Sie das DIGCF_DEFAULT-Flag fest, und legen Sie ClassGuid auf NULL fest. Die Funktion fügt dem Geräteinformationssatz ein Geräteinformationselement hinzu, das ein solches Gerät darstellt, und fügt dann die Systemstandardschnittstelle der Geräteschnittstellenliste für dieses Geräteinformationselement hinzu.

Sie können auch die folgenden Optionen in Kombination mit den anderen Optionen verwenden, um die zurückgegebenen Geräte weiter einzuschränken:

Um nur Geräte zurückzugeben, die im System vorhanden sind, legen Sie das Flag DIGCF_PRESENT fest.
Um nur Geräte zurückzugeben, die Teil des aktuellen Hardwareprofils sind, legen Sie das flag DIGCF_PROFILE fest.
Um nur ein bestimmtes Gerät zurückzugeben, legen Sie das flag DIGCF_DEVICEINTERFACE fest, und verwenden Sie den Enumerator-Parameter, um das Gerät instance ID des Geräts anzugeben. Um alle möglichen Geräte einzubeziehen, legen Sie Enumerator auf NULL fest.

Beispiele

Im Folgenden finden Sie einige Beispiele für die Verwendung der SetupDiGetClassDevs-Funktion .

Beispiel 1: Erstellen Sie eine Liste aller Geräte im System, einschließlich geräten, die derzeit nicht vorhanden sind.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES);

Beispiel 2: Erstellen Sie eine Liste aller Geräte, die im System vorhanden sind.

Handle = SetupDiGetClassDevs(NULL, NULL, NULL, DIGCF_ALLCLASSES | DIGCF_PRESENT);

Beispiel 3: Erstellen Sie eine Liste aller Geräte, die im System vorhanden sind und von der Geräteeinrichtungsklasse des Netzwerkadapters stammen.

Handle = SetupDiGetClassDevs(&GUID_DEVCLASS_NET, NULL, NULL, DIGCF_PRESENT);

Beispiel 4: Erstellen Sie eine Liste aller Geräte, die im System vorhanden sind und eine Schnittstelle aus der Geräteschnittstellenklasse des Speichervolumes aktiviert haben.

Handle = SetupDiGetClassDevs(&GUID_DEVINTERFACE_VOLUME, NULL, NULL, DIGCF_PRESENT | DIGCF_DEVICEINTERFACE);

Beispiel 5: Erstellen Sie eine Liste aller Geräte, die im System vorhanden sind, aber keiner bekannten Geräteeinrichtungsklasse (Windows Vista und neuere Versionen von Windows) angehören.

Hinweis Sie können den ClassGuid-Parameter nicht auf GUID_DEVCLASS_UNKNOWN festlegen, um Geräte mit einer unbekannten Setupklasse zu erkennen. Stattdessen müssen Sie diesem Beispiel folgen.

DeviceInfoSet = SetupDiGetClassDevs(
                                    NULL,
                                    NULL,
                                    NULL,
                                    DIGCF_ALLCLASSES | DIGCF_PRESENT);

ZeroMemory(&DeviceInfoData, sizeof(SP_DEVINFO_DATA));
DeviceInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
DeviceIndex = 0;
    
while (SetupDiEnumDeviceInfo(
                             DeviceInfoSet,
                             DeviceIndex,
                             &DeviceInfoData)) {
    DeviceIndex++;

    if (!SetupDiGetDeviceProperty(
                                  DeviceInfoSet,
                                  &DeviceInfoData,
                                  &DEVPKEY_Device_Class,
                                  &PropType,
                                  (PBYTE)&DevGuid,
                                  sizeof(GUID),
                                  &Size,
                                  0) || PropType != DEVPROP_TYPE_GUID) {

        Error = GetLastError();

        if (Error == ERROR_NOT_FOUND) {
            \\
            \\ This device has an unknown device setup class.
            \\
            }
        }                 
    }

if (DeviceInfoSet) {
    SetupDiDestroyDeviceInfoList(DeviceInfoSet);
    }

Hinweis

Der setupapi.h-Header definiert SetupDiGetClassDevs als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	DesktopFür universal rufen Sie CM_Get_Device_ID_ListFor universal auf, rufen Sie CM_Get_Device_Interface_List
Kopfzeile	setupapi.h (einschließlich SetupAPI.h)
Bibliothek	SetupAPI.lib
DLL	SetupAPI.dll
APIs	ext-ms-win-setupapi-classinstallers-l1-1-0 (eingeführt in Windows 8)