SetupDiGetClassDevsW-Funktion (setupapi.h)

Artikel
11/20/2024

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 MIT NULL beendete Zeichenfolge, die Folgendes angibt:

Ein Bezeichner (ID) eines Plug and Play (PnP) Enumerator. Diese ID kann entweder der GUID (Globally Unique Identifier) des Werts oder der symbolische Name sein. 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".
Eine PnP-Geräteinstanz-ID. Wenn Sie eine PnP-Geräteinstanz-ID angeben, muss DIGCF_DEVICEINTERFACE im Parameter "Flags" festgelegt werden.

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

Weitere Informationen zum Festlegen des Enumerator--Werts 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 einer Geräteinstanz im Geräteinformationssatz zugeordnet ist. Dieses Handle ist optional und kann NULL-werden.

[in] Flags

Eine Variable vom Typ DWORD, die Steuerelementoptionen angibt, die die Geräteinformationselemente filtern, die dem Geräteinformationssatz hinzugefügt werden. Dieser Parameter kann ein bitweiser OR von Null oder mehr der folgenden Flags sein. Weitere Informationen zum Kombinieren dieser Kennzeichnungen finden Sie im folgenden abschnitt Hinweise.

DIGCF_ALLCLASSES

Gibt eine Liste der installierten Geräte für alle Gerätesetupklassen 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 parameter Flags festgelegt werden, wenn der Enumerator Parameter eine Geräteinstanz-IDangibt.

DIGCF_DEFAULT

Gibt nur das Gerät zurück, das der Standardmäßigen Geräteschnittstelle des Systems zugeordnet ist, falls vorhanden, 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. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

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

Optionen für die Geräteeinrichtungsklassensteuerung

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ätesetupklassen zurückzugeben, legen Sie das DIGCF_ALLCLASSES Flag fest, und legen Sie den ClassGuid- parameter auf NULL-fest.
Wenn Sie Geräte nur für eine bestimmte Gerätesetupklasse zurückgeben möchten, legen Sie DIGCF_ALLCLASSES nicht fest, und verwenden Sie ClassGuid-, um die GUID der Gerätesetupklasse anzuzeigen.

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

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

Optionen für die Geräteschnittstellen-Klassensteuerung

Verwenden Sie die folgenden Filteroptionen, um zu steuern, ob SetupDiGetClassDevs Geräte zurückgibt, die geräteschnittstellenklasse oder nur Geräte unterstützen, 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 eine Geräteschnittstelle der angegebenen Klasse zur Geräteschnittstellenliste für dieses Geräteinformationselement 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 Standardschnittstelle des Systems unterstützt, legen Sie bei einer angegebenen 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 Standardschnittstelle des Systems zur 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 Standardschnittstelle des Systems zur Geräteschnittstellenliste für dieses Geräteinformationselement hinzu.

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

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

Beispiele

Im Folgenden sind einige Beispiele für die Verwendung der SetupDiGetClassDevs-Funktion aufgeführt.

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

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

Beispiel 2: Erstellen einer 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, aus dem Netzwerkadapter Gerätesetupklasse.

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

Beispiel 4: Erstellen Sie eine Liste aller Geräte, die im System vorhanden sind, die eine Schnittstelle aus dem Speichervolume Geräteschnittstellenklasseaktiviert 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, gehören jedoch nicht zu einer bekannten Gerätesetupklasse (Windows Vista und höhere Versionen von Windows).

Hinweis Sie können den parameter ClassGuid 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);
    }

Anmerkung

Der Header setupapi.h definiert SetupDiGetClassDevs als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, 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
mindestens unterstützte Client-	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform-	DesktopFor universal, call CM_Get_Device_ID_ListFor universal, call CM_Get_Device_Interface_List
Header-	setupapi.h (include SetupAPI.h)
Library	SetupAPI.lib
DLL-	SetupAPI.dll
API-Satz	ext-ms-win-setupapi-classinstallers-l1-1-0 (eingeführt in Windows 8)