IoRegisterDeviceInterface-Funktion (wdm.h)

Die IoRegisterDeviceInterface-Routine registriert eine Geräteschnittstellenklasse, sofern sie noch nicht registriert wurde, und erstellt eine neue instance der Schnittstellenklasse, die ein Treiber anschließend für die Verwendung durch Anwendungen oder andere Systemkomponenten aktivieren kann.

Syntax

NTSTATUS IoRegisterDeviceInterface(
  [in]           PDEVICE_OBJECT  PhysicalDeviceObject,
  [in]           const GUID      *InterfaceClassGuid,
  [in, optional] PUNICODE_STRING ReferenceString,
  [out]          PUNICODE_STRING SymbolicLinkName
);

Parameter

[in] PhysicalDeviceObject

Ein Zeiger auf das PDO für das Gerät.

[in] InterfaceClassGuid

Ein Zeiger auf die Klassen-GUID, die die zu registrierende Funktionalität (die Geräteschnittstellenklasse) identifiziert.

[in, optional] ReferenceString

Zeigt optional auf eine UNICODE_STRING. Die Zeichenfolge darf keine Pfadtrennzeichen ("/" oder "\") enthalten. Funktionstreiber geben normalerweise NULL für diesen Parameter an. Filtertreiber müssen NULL angeben.

Verweiszeichenfolgen werden nur von einigen wenigen Bustreibern verwendet, z. B. swenum, bei dem es sich um einen Bustreiber handelt, der Geräteschnittstelleninstanzen als Platzhalter für bei Bedarf erstellte Softwaregeräte verwendet. Wenn ein instance einer Schnittstelle geöffnet wird, übergibt der E/A-Manager die Verweiszeichenfolge des instance an den Treiber. Die Zeichenfolge wird Teil des Namens der Schnittstelle instance (als angefügte Pfadkomponente). Der Treiber kann dann die Verweiszeichenfolge verwenden, um zwischen zwei Schnittstelleninstanzen derselben Klasse für ein einzelnes Gerät zu unterscheiden.

Auf Microsoft Windows 98/Me-Systemen darf der ReferenceString-Wert nicht länger als MAX_PATH Zeichen sein. Für Windows 2000 und höhere Versionen von Windows gibt es keine Längenbegrenzung.

[out] SymbolicLinkName

Ein Zeiger auf eine Unicode-Zeichenfolgenstruktur, die vom Aufrufer zugewiesen wird. Wenn diese Routine erfolgreich ist, initialisiert sie die Unicode-Zeichenfolge und ordnet den Zeichenfolgenpuffer, der den Kernelmoduspfad enthält, dem symbolischen Link für einen instance der angegebenen Geräteschnittstellenklasse zu.

Der Aufrufer muss SymbolicLinkName als undurchsichtig behandeln und darf ihn nicht disassemblieren.

Der Aufrufer ist für das Freigeben von SymbolicLinkName mit RtlFreeUnicodeString verantwortlich, wenn er nicht mehr benötigt wird.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	Die Parameter sind ungültig. Es ist möglich, dass PhysicalDeviceObject nicht auf einen gültigen PDO verweist oder dass die ReferenceString-Zeichenfolge ein ungültiges Zeichen enthält.

Hinweise

IoRegisterDeviceInterface registriert eine Geräteschnittstellenklasse, sofern sie noch nicht registriert wurde, und erstellt eine neue instance der Schnittstellenklasse. Ein Treiber kann diese Routine für ein bestimmtes Gerät mehrmals aufrufen, um mehrere Schnittstellenklassen zu registrieren und Instanzen der Klassen zu erstellen. Eine Funktion oder ein Filtertreiber registriert in der Regel Geräteschnittstellen in der AddDevice-Routine . Beispielsweise kann ein fehlertoleranter Volumetreiber eine instance einer fehlertoleranten Volumeschnittstelle und eine instance einer Volumeschnittstelle für ein bestimmtes Volume registrieren.

Wenn die Geräteschnittstellenklasse noch nicht registriert wurde, erstellt der E/A-Manager einen Registrierungsschlüssel für sie zusammen mit instance spezifischen persistenten Speicher unter dem Schlüssel. Treiber können mithilfe von IoOpenDeviceInterfaceRegistryKey auf diesen persistenten Speicher zugreifen.

Ein Treiber registriert einmal eine Schnittstelle instance und ruft dann IoSetDeviceInterfaceState auf, um die Schnittstelle zu aktivieren und zu deaktivieren.

Registrierte Schnittstellen bleiben bei Betriebssystemneustarts erhalten. Wenn die angegebene Schnittstelle bereits registriert ist, übergibt der E/A-Manager seinen Namen in SymbolicLinkName und gibt den Informationserfolg status STATUS_OBJECT_NAME_EXISTS zurück.

Die meisten Treiber verwenden eine NULL-Verweiszeichenfolge für eine Geräteschnittstelle instance. Wenn ein Treiber eine Nicht-NULL-Verweiszeichenfolge verwendet, muss er zusätzliche Arbeit leisten, einschließlich möglicherweise der Verwaltung seines eigenen Namespaces und der Sicherheit. Ein Filtertreiber, der eine Geräteschnittstelle verfügbar macht, muss einen NULLReferenceString verwenden, um Konflikte mit anderen Treibern im Gerätestapel zu vermeiden.

Anrufer dieser Routine müssen die Registrierung für eine Geräteschnittstelle nicht entfernen, wenn sie nicht mehr benötigt wird. Geräteschnittstellenregistrierungen können bei Bedarf aus dem Benutzermodus entfernt werden.

Aufrufer von IoRegisterDeviceInterface 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), IrqlIoPassive3(wdm), PowerIrpDDis(wdm)

Weitere Informationen

IoGetDeviceInterfaces

IoOpenDeviceInterfaceRegistryKey

IoSetDeviceInterfaceState

RtlFreeUnicodeString