IoRegisterDeviceInterface-Funktion (wdm.h)
Die IoRegisterDeviceInterface Routine registriert eine Geräteschnittstellenklasse, sofern sie noch nicht registriert wurde, und erstellt eine neue Instanz 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 den PDO für das Gerät.
[in] InterfaceClassGuid
Ein Zeiger auf die Klassen-GUID, die die Funktionalität (die Geräteschnittstellenklasse) identifiziert, die registriert wird.
[in, optional] ReferenceString
Zeigt optional auf eine UNICODE_STRING. Die Zeichenfolge darf keine Pfadtrennzeichen ("/" oder "\") enthalten. Funktionstreiber geben in der Regel NULL- für diesen Parameter an. Filtertreiber müssen NULL-angeben.
Referenzzeichenfolgen werden nur von einigen Bustreibern verwendet, z. B. Swenum, bei dem es sich um einen Bustreiber handelt, der Geräteschnittstelleninstanzen als Platzhalter für Softwaregeräte verwendet, die bei Bedarf erstellt wurden. Wenn eine Instanz einer Schnittstelle geöffnet wird, übergibt der E/A-Manager die Referenzzeichenfolge der Instanz an den Treiber. Die Zeichenfolge wird Teil des Namens der Schnittstelleninstanz (als angefügte Pfadkomponente). Der Treiber kann dann die Referenzzeichenfolge verwenden, um zwischen zwei Schnittstelleninstanzen derselben Klasse für ein einzelnes Gerät zu unterscheiden.
Auf Microsoft Windows 98/Me-Systemen kann der ReferenceString- Wert nicht mehr als MAX_PATH Zeichen sein. Für Windows 2000 und höhere Versionen von Windows gibt es keine Längenbeschränkung.
[out] SymbolicLinkName
Ein Zeiger auf eine Unicode-Zeichenfolgenstruktur, die vom Aufrufer zugewiesen wird. Wenn diese Routine erfolgreich ist, initialisiert sie die Unicode-Zeichenfolge und weist den Zeichenfolgenpuffer, der den Kernelmoduspfad enthält, der symbolischen Verknüpfung für eine Instanz der angegebenen Geräteschnittstellenklasse zu.
Der Aufrufer muss SymbolicLinkName als undurchsichtig behandeln und darf ihn nicht zerlegen.
Der Anrufer ist dafür verantwortlich, SymbolicLinkName mit RtlFreeUnicodeString frei zu geben, 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 |
|---|---|
|
Die Parameter sind ungültig. Zu den Möglichkeiten gehören, dass PhysicalDeviceObject- nicht auf einen gültigen PDO verweist oder dass die ReferenceString- Zeichenfolge ein ungültiges Zeichen enthält. |
Bemerkungen
IoRegisterDeviceInterface registriert eine Geräteschnittstellenklasse, sofern sie noch nicht registriert wurde, und erstellt eine neue Instanz der Schnittstellenklasse. Ein Treiber kann diese Routine mehrmals für ein bestimmtes Gerät aufrufen, um mehrere Schnittstellenklassen zu registrieren und Instanzen der Klassen zu erstellen. Ein Funktions- oder Filtertreiber registriert in der Regel Geräteschnittstellen in seiner AddDevice- Routine. Beispielsweise kann ein fehlertoleranter Volumetreiber eine Instanz einer fehlertoleranten Volumeschnittstelle und eine Instanz einer Volumeschnittstelle für ein bestimmtes Volume registrieren.
Wenn die Geräteschnittstellenklasse noch nicht registriert wurde, erstellt der E/A-Manager dafür einen Registrierungsschlüssel zusammen mit instanzspezifischem persistentem Speicher unter dem Schlüssel. Treiber können über IoOpenDeviceInterfaceRegistryKeyauf diesen beständigen Speicher zugreifen.
Ein Treiber registriert eine Schnittstelleninstanz einmal und ruft dann IoSetDeviceInterfaceState- auf, um die Schnittstelle zu aktivieren und zu deaktivieren.
Registrierte Schnittstellen werden über Betriebssystemneustarts hinweg beibehalten. Wenn die angegebene Schnittstelle bereits registriert ist, übergibt der E/A-Manager seinen Namen in SymbolicLinkName und gibt den Status des informationsbasierten Erfolgs STATUS_OBJECT_NAME_EXISTS zurück.
Die meisten Treiber verwenden eine NULL- Referenzzeichenfolge für eine Geräteschnittstelleninstanz. Wenn ein Treiber eine nicht-NULL- Referenzzeichenfolge verwendet, muss er zusätzliche Arbeit ausführen, einschließlich möglicherweise der Verwaltung eines eigenen Namespaces und der Sicherheit. Ein Filtertreiber, der eine Geräteschnittstelle verfügbar macht, muss eine NULL-ReferenceString- verwenden, um Konflikte mit anderen Treibern im Gerätestapel zu vermeiden.
Aufrufer dieser Routine müssen die Registrierung für eine Geräteschnittstelle nicht entfernen, wenn sie nicht mehr benötigt wird. Geräteoberflächenregistrierungen 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 |
|---|---|
| mindestens unterstützte Client- | Ab Windows 2000 verfügbar. |
| Zielplattform- | Universal |
| Header- | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL- | NtosKrnl.exe |
| IRQL- | PASSIVE_LEVEL (siehe Abschnitt "Hinweise") |
| DDI-Complianceregeln | HwStorPortProhibitedDDIs(storport), IrqlIoPassive3(wdm), PowerIrpDDis(wdm) |