IoGetDeviceInterfaces-Funktion (wdm.h)

Artikel
08/08/2023

Die IoGetDeviceInterfaces-Routine gibt eine Liste der Geräteschnittstelleninstanzen einer bestimmten Geräteschnittstellenklasse zurück (z. B. alle Geräte im System, die eine HID-Schnittstelle unterstützen).

Syntax

NTSTATUS IoGetDeviceInterfaces(
  [in]           const GUID     *InterfaceClassGuid,
  [in, optional] PDEVICE_OBJECT PhysicalDeviceObject,
  [in]           ULONG          Flags,
  [out]          PZZWSTR        *SymbolicLinkList
);

Parameter

[in] InterfaceClassGuid

Zeiger auf eine Klassen-GUID, die die Geräteschnittstellenklasse angibt. Die GUIDs für eine Klasse sollten sich in einer gerätespezifischen Headerdatei befinden.

[in, optional] PhysicalDeviceObject

Zeiger auf ein optionales PDO, das die Suche nur auf die Geräteschnittstelleninstanzen des geräts einschränkt, das vom PDO dargestellt wird.

[in] Flags

Gibt Flags an, die die Suche nach Geräteschnittstellen ändern. Derzeit ist nur ein Flag definiert, das in der folgenden Tabelle beschrieben wird.

Flag	Bedeutung
DEVICE_INTERFACE_INCLUDE_NONACTIVE	Gibt zusätzlich zu aktivierten Schnittstelleninstanzen deaktivierte Geräteschnittstelleninstanzen zurück.

Bei der Suche nach einem Gerät, das eine bestimmte Schnittstellenklasse unterstützt, benötigt der Aufrufer eine aktivierte Schnittstelle instance und legt daher nicht das DEVICE_INTERFACE_INCLUDE_NONACTIVE-Flag fest.

Ein Treiber legt in der Regel das DEVICE_INTERFACE_INCLUDE_NONACTIVE-Flag fest, um deaktivierte Schnittstelleninstanzen zu suchen, die der Treiber aktivieren muss. Beispielsweise könnte der Klasseninstallationsprogramm für das Gerät von der INF-Datei angewiesen worden sein, eine oder mehrere Schnittstelleninstanzen für das Gerät zu registrieren. Die Schnittstelleninstanzen werden zwar registriert, sind aber erst dann verwendbar, wenn sie vom Treiber (mithilfe von IoSetDeviceInterfaceState) aktiviert werden. Um die Liste der Schnittstelleninstanzen einzuschränken, die nur auf diejenigen zurückgegeben werden, die von einem bestimmten Gerät verfügbar gemacht werden, kann ein Treiber ein PhysicalDeviceObject angeben.

[out] SymbolicLinkList

Ein Zeiger auf einen Breitzeichenzeiger, auf den die Routine bei erfolgreicher Ausführung die Basisadresse eines Puffers schreibt, der eine Liste von Unicode-Zeichenfolgen enthält. Diese Zeichenfolgen sind symbolische Linknamen, die die Geräteschnittstelleninstanzen identifizieren, die den Suchkriterien entsprechen. Jede Unicode-Zeichenfolge in der Liste ist NULL-beendet. das Ende der gesamten Liste wird durch ein zusätzliches NULL-Zeichen markiert. Die Routine weist den Puffer für diese Zeichenfolgen aus dem ausgelagerten Systemspeicher zu. Der Aufrufer ist für das Freigeben des Puffers (durch Aufrufen der ExFreePool-Routine ) verantwortlich, wenn er nicht mehr benötigt wird.

Wenn keine Geräteschnittstelleninstanzen den Suchkriterien entsprechen, gibt diese Routine STATUS_SUCCESS zurück, und die Zeichenfolge enthält ein einzelnes NULL-Zeichen.

Rückgabewert

IoGetDeviceInterfaces gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Mögliche Fehlerrückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Gibt möglicherweise an, dass PhysicalDeviceObject kein gültiger PDO-Zeiger war.

Hinweise

IoGetDeviceInterfaces gibt eine Liste von Geräteschnittstelleninstanzen zurück, die den Suchkriterien entsprechen. Eine Kernelmoduskomponente ruft diese Routine in der Regel auf, um eine Liste aller aktivierten Geräteschnittstelleninstanzen einer bestimmten Geräteschnittstellenklasse abzurufen. Eine solche Komponente kann einen Zeiger auf das Dateiobjekt und/oder das Geräteobjekt für eine Schnittstelle abrufen, indem die IoGetDeviceObjectPointer - oder ZwCreateFile-Routine aufgerufen wird. Der von IoGetDeviceObjectPointer zurückgegebene Geräteobjektzeiger zeigt auf den oberen Rand des Gerätestapels für das Gerät und kann in Aufrufen der IoCallDriver-Routine verwendet werden.

Wenn eine Standardschnittstelle für die angeforderte Geräteschnittstellenklasse vorhanden ist, wird sie zuerst in SymbolicLinkList aufgeführt. Standardschnittstellen können im Benutzermodus, nicht aber im Kernelmodus festgelegt werden.

Das Format eines symbolischen Linknamens ist undurchsichtig. Der Aufrufer sollte nicht versuchen, einen symbolischen Linknamen zu analysieren.

Symbolische Links für Geräteschnittstelleninstanzen können über Systemboote hinweg verwendet werden.

Um benachrichtigt zu werden, wenn zusätzliche Geräteschnittstelleninstanzen einer bestimmten Klasse auf dem System aktiviert sind, registrieren Sie sich zur Benachrichtigung über eine Geräteklassenänderung, indem Sie die IoRegisterPlugPlayNotification-Routine aufrufen.

Aufrufer von IoGetDeviceInterfaces müssen unter IRQL = PASSIVE_LEVEL im Kontext eines Systemthreads ausgeführt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt Hinweise)
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PowerIrpDDis(wdm)