IoOpenDeviceRegistryKey-Funktion (wdm.h)

Artikel
08/08/2023

Die IoOpenDeviceRegistryKey-Routine gibt ein Handle an einen Registrierungsstatusspeicherort für ein bestimmtes Gerät instance zurück.

Syntax

NTSTATUS IoOpenDeviceRegistryKey(
  [in]  PDEVICE_OBJECT DeviceObject,
  [in]  ULONG          DevInstKeyType,
  [in]  ACCESS_MASK    DesiredAccess,
  [out] PHANDLE        DeviceRegKey
);

Parameter

[in] DeviceObject

Zeiger auf das Objekt des physischen Geräts (PDO) des Geräts instance, für das der Registrierungsstatusspeicherort geöffnet werden soll.

[in] DevInstKeyType

Gibt Flags an, die angeben, ob ein gerätespezifischer Hardwareschlüssel oder ein treiberspezifischer Softwareschlüssel geöffnet werden soll. Die Flags geben auch an, ob der Schlüssel relativ zum aktuellen Hardwareprofil ist. Weitere Informationen zu Hardware- und Softwareschlüsseln finden Sie unter Einführung in Registrierungsschlüssel für Treiber.

Die Flags werden wie folgt definiert:

PLUGPLAY_REGKEY_DEVICE

Öffnen Sie den Hardwareschlüssel des Geräts, einen gerätespezifischen Registrierungsstatusspeicherort, der Informationen zum Gerät enthält. Dieses Flag kann nicht mit PLUGPLAY_REGKEY_DRIVER angegeben werden.

PLUGPLAY_REGKEY_DRIVER

Öffnen Sie den Softwareschlüssel des Geräts, einen gerätespezifischen Registrierungsstatusspeicherort zum Speichern treiberspezifischer Informationen. Dieses Flag kann nicht mit PLUGPLAY_REGKEY_DEVICE angegeben werden.

PLUGPLAY_REGKEY_CURRENT_HWPROFILE

Hardwareprofile sind veraltet, und der Zustand sollte nicht relativ zu einem Hardwareprofil gespeichert werden.

Öffnen Sie einen Schlüssel relativ zum aktuellen Hardwareprofil für Geräte- oder Treiberinformationen. Dadurch kann der Treiber auf hardwareprofilspezifische Konfigurationsinformationen zugreifen. Der Aufrufer muss entweder PLUGPLAY_REGKEY_DEVICE oder PLUGPLAY_REGKEY_DRIVER mit diesem Flag angeben.

[in] DesiredAccess

Gibt den ACCESS_MASK Wert an, der den Zugriff darstellt, den der Aufrufer auf den Schlüssel benötigt. Eine Beschreibung der einzelnen KEY_XXX-Zugriffsrechte finden Sie in der ZwCreateKey-Routine.

[out] DeviceRegKey

Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der bei erfolgreicher Rückgabe ein Handle zum angeforderten Registrierungsstatusspeicherort enthält.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Gibt möglicherweise an, dass der Aufrufer einen unzulässigen Satz von DevInstKeyType-Flags angegeben oder ein DeviceObject bereitgestellt hat , das kein gültiges PDO ist.

Hinweise

Der Treiber muss ZwClose aufrufen, um das von dieser Routine zurückgegebene Handle zu schließen, wenn kein Zugriff mehr erforderlich ist.

Die registrierungsschlüssel, die von dieser Routine geöffnet werden, sind nicht unveränderlich.

Benutzermodus-Setupanwendungen können mithilfe von CM_Open_DevNode_Key - oder Geräteinformationsfunktionen wie SetupDiOpenDevRegKey oder SetupDiCreateDevRegKey auf diese Registrierungsschlüssel zugreifen.

Um den Status in diesen Registrierungsstatusspeicherorten zum Zeitpunkt der Treiberpaketinstallation vorab aufzufüllen, verwenden Sie INF AddReg-Anweisungen in einer INF-Datei.

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

Anforderungen

Anforderung	Wert
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), PowerIrpDDis(wdm)