SetupDiGetClassDevsExA-Funktion (setupapi.h)

Artikel
11/20/2024

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äteeinrichtungsklasse 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 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 Enumerators oder der symbolische Name sein. Beispielsweise kann "PCI" verwendet werden, um den PCI-PnP-Enumerator anzugeben. Weitere Beispiele für symbolische Namen für PnP-Enumerationen sind "USB", "PCMCIA" und "SCSI".
Eine PnP-Geräteinstanz-IDs. 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 Enumerator- Wert 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 einer 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 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 vorhanden sind.

DIGCF_PROFILE

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

[in, optional] DeviceInfoSet

Das Handle zu einem 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, 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.

Vorsicht

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

Reserviert für die interne Verwendung. 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. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

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

Wenn DeviceInfoSet-NULL-ist, erstellt SetupDiGetClassDevsEx einen neuen Geräteinformationssatz, der die abgerufenen Geräteinformationselemente enthält, und gibt ein Handle an 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äteeinrichtungsklasse 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 Dem bereitgestellten Handle zugeordneten Geräteinformationssatz hinzu und gibt den bereitgestellten Handle zurück. Wenn ClassGuid eine Geräteeinrichtungsklasse bereitstellt, muss die Geräteeinrichtungsklasse des angegebenen Geräteinformationssatzes auf die angegebene Klassen-GUID festgelegt werden.

Optionen für die Geräteeinrichtungsklassensteuerung

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 DIGCF_ALLCLASSES Flag fest, und legen Sie den parameter ClassGuid auf NULL-fest.
Um Geräte nur für eine bestimmte Gerätesetupklasse zurückzugeben, 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 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.
Wenn Sie Geräte nur für einen bestimmten PnP--Enumerator zurückgeben möchten, verwenden Sie den Enumerator Parameter, um die GUID oder den symbolischen Namen des Enumeratorsanzugeben. Wenn Enumerator-NULL-ist, gibt SetupDiGetClassDevsEx- 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 SetupDiGetClassDevsEx- 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 mithilfe der folgenden Filteroptionen steuern, ob SetupDiGetClassDevsEx 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.

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

Ein Installationsprogramm kann SetupDiGetClassDevsEx- verwenden, um eine Liste der Geräte einer bestimmten Geräteeinrichtungsklasse abzurufen, die eine Geräteschnittstelle einer angegebenen Geräteschnittstellenklasse unterstützt. 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 Setupklasse "Volume" sind, sollte ein Installationsprogramm die folgenden Vorgänge ausführen:

Rufen Sie SetupDiCreateDeviceInfoList- auf, um einen leeren Geräteinformationssatz für die Setupklasse "Volume" zu erstellen. Legen Sie ClassGuid- auf einen Zeiger auf die Klassen-GUID für die Setupklasse "Volume" fest, und legen Sie hwndParent entsprechend fest. Als Reaktion auf einen solchen Aufruf gibt die Funktion ein Handle zurück, um HDEVINFO an 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 "mounted device" fest.
- Legen Sie Flags auf DIGCF_DEVICEINTERFACE fest.
- Legen Sie DeviceInfoSet- auf den HDEVINFO-Handle fest, der in Schritt (1) abgerufen wurde.
- Legen Sie hwndParent entsprechend fest und die verbleibenden Parameter auf NULL-.

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

Anmerkung

Der Header setupapi.h definiert SetupDiGetClassDevsEx 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 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-	Desktop
Header-	setupapi.h (include Setupapi.h)
Library	Setupapi.lib