SetupDiGetClassDevsExA-Funktion (setupapi.h)

Artikel
08/26/2023

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

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
);

Parameter

[in, optional] ClassGuid

Ein Zeiger auf die GUID für eine Gerätesetupklasse oder eine Geräteschnittstellenklasse. Dieser Zeiger ist optional und kann NULL sein. Wenn kein GUID-Wert zum Auswählen von Geräten verwendet wird, legen Sie ClassGuid auf NULL fest. Weitere Informationen zur Verwendung 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 Enumerators oder um einen symbolischen Namen handeln. Beispielsweise kann "PCI" verwendet werden, um den PCI-PnP-Enumerator anzugeben. Weitere Beispiele für symbolische Namen für PnP-Enumeratoren sind "USB", "PCMCIA" und "SCSI".
Ein PnP-Gerät instance IDs. 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 Enumeratorwert 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 zum 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 bitweises OR eines oder mehrerer der folgenden Flags sein. Weitere Informationen zum Kombinieren dieser Steuerelementoptionen finden Sie im folgenden Abschnitt hinweise .

DIGCF_ALLCLASSES

Gibt eine Liste der installierten Geräte für die angegebenen Gerätesetupklassen oder 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 vorhanden sind.

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

Das Handle für einen vorhandenen Geräteinformationssatz , dem SetupDiGetClassDevsEx die angeforderten Geräteinformationselemente hinzufügt. Dieser Parameter ist optional und kann auf NULL festgelegt werden. Weitere Informationen zur Verwendung dieses Parameters finden Sie im folgenden Abschnitt hinweise .

[in, optional] MachineName

Ein Zeiger auf eine konstante Zeichenfolge, die den Namen eines Remotecomputers enthält, auf dem sich die Geräte befinden. Der Wert NULL für MachineName gibt an, dass das Gerät auf dem lokalen Computer installiert ist.

Achtung

Die Verwendung dieser Funktion für den Zugriff auf Remotecomputer wird ab Windows 8 und Windows Server 2012 nicht unterstützt, da diese Funktionalität entfernt wurde.

Reserved

Für die interne Verwendung reserviert. Dieser Parameter muss auf NULL festgelegt werden.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt SetupDiGetClassDevsEx 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 SetupDiGetClassDevsEx muss die zurückgegebenen Geräteinformationen löschen, die festgelegt werden, wenn sie nicht mehr benötigt werden, indem SetupDiDestroyDeviceInfoList aufgerufen wird.

Wenn DeviceInfoSetNULL ist, erstellt SetupDiGetClassDevsEx einen neuen Geräteinformationssatz, der die abgerufenen Geräteinformationselemente enthält, und gibt ein Handle für den neuen Geräteinformationssatz zurück. Wenn der Aufrufer anfordert, dass die Funktion Geräte für eine Gerätesetupklasse abruft, die vom ClassGuid-Parameter bereitgestellt wird, legt die Funktion die Gerätesetupklasse der neuen Geräteinformationen auf die angegebene Klassen-GUID fest.

Wenn DeviceInfoSet nicht auf NULL festgelegt ist, fügt die Funktion die abgerufenen Geräteinformationselemente dem Geräteinformationssatz hinzu, der dem angegebenen Handle zugeordnet ist, und gibt das angegebene Handle zurück. Wenn ClassGuid eine Gerätesetupklasse bereitstellt, muss die Gerätesetupklasse des angegebenen Geräteinformationssatzes auf die angegebene Klassen-GUID festgelegt werden.

Gerätesetup-Klassensteuerungsoptionen

Verwenden Sie die folgenden Filteroptionen, um zu steuern, ob SetupDiGetClassDevsEx 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 flag DIGCF_ALLCLASSES und den Parameter ClassGuid auf NULL fest.
Um Geräte nur für eine bestimmte Gerätesetupklasse zurückzugeben, legen Sie nicht DIGCF_ALLCLASSES fest, und verwenden Sie ClassGuid , um die GUID der Gerätesetupklasse anzugeben.

Darüber hinaus können Sie die folgenden Filteroptionen 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 SetupDiGetClassDevsEx Geräte für alle PnP-Enumeratoren zurück.

Geräteschnittstellen-Klassensteuerungsoptionen

Verwenden Sie die folgenden Filteroptionen, um zu steuern, ob SetupDiGetClassDevsEx Geräte zurückgibt, die eine beliebige 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, das flag DIGCF_ALLCLASSES und ClassGuid auf NULL fest. Die Funktion fügt dem Geräteinformationssatz ein Geräteinformationselement hinzu, das ein solches Gerät darstellt, und fügt dem Geräteinformationselement dann 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 Parameter 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 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 SetupDiGetClassDevsEx nur Geräte zurückgibt, die die Systemstandardschnittstelle für Geräteschnittstellenklassen unterstützen:

Um nur das Gerät zurückzugeben, das die Standardschnittstelle des Systems unterstützt, legen Sie bei einer bestimmten Geräteschnittstellenklasse das flag DIGCF_DEVICEINTERFACE fest, legen Sie das flag DIGCF_DEFAULT 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 flag DIGCF_DEVICEINTERFACE, das flag DIGCF_ALLCLASSES, das flag DIGCF_DEFAULT und 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 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 einzuschließen, legen Sie den Enumerator auf NULL fest.

Abrufen von Geräten in einer Gerätesetupklasse, die eine Geräteschnittstellenklasse unterstützen

Ein Installationsprogramm kann SetupDiGetClassDevsEx verwenden, um eine Liste von Geräten einer bestimmten Gerätesetupklasse abzurufen, die eine Geräteschnittstelle einer angegebenen Geräteschnittstellenklasse unterstützen. Um beispielsweise eine Liste aller Geräte auf einem lokalen Computer abzurufen, die eine Geräteschnittstelle in der Schnittstellenklasse "eingebundenes Gerät" unterstützen und Mitglieder der Gerätesetupklasse "Volume" sind, sollte ein Installationsprogramm die folgenden Vorgänge ausführen:

Rufen Sie SetupDiCreateDeviceInfoList auf, um einen leeren Geräteinformationssatz für die Gerätesetupklasse "Volume" zu erstellen. Legen Sie ClassGuid auf einen Zeiger auf die Klassen-GUID für die Geräteeinrichtungsklasse "Volume" fest, und legen Sie hwndParent entsprechend fest. Als Reaktion auf einen solchen Aufruf gibt die Funktion ein Handle zurück, um HDEVINFO in den Geräteinformationssatz einzugeben.
Rufen Sie SetupDiGetClassDevsEx mit den folgenden Einstellungen auf:
- Legen Sie ClassGuid auf einen Zeiger auf die Klassen-GUID der Geräteschnittstellenklasse "eingebundenes Gerät" fest.
- Legen Sie Flags auf DIGCF_DEVICEINTERFACE fest.
- Legen Sie DeviceInfoSet auf das IN Schritt (1) abgerufene HDEVINFO-Handle fest.
- Legen Sie hwndParent entsprechend fest, und legen Sie die verbleibenden Parameter auf NULL fest.

In einem Vorgang dieses Typs gibt SetupDiGetClassDevsEx ein Gerät zurück, wenn die Gerätesetupklasse des Geräts mit dem angegebenen Geräteinformationssatz identisch ist und wenn das Gerät eine Geräteschnittstelle unterstützt, deren Klasse mit der angegebenen Geräteschnittstellenklasse identisch ist.

Hinweis

Der Setupapi.h-Header definiert SetupDiGetClassDevsEx 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
Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	setupapi.h (einschließlich Setupapi.h)
Bibliothek	Setupapi.lib