WdfDeviceOpenRegistryKey-Funktion (wdfdevice.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfDeviceOpenRegistryKey- Methode öffnet den Hardwareschlüssel eines Geräts oder den Softwareschlüssel eines Treibers in der Registrierung und erstellt ein Framework-Registrierungsschlüsselobjekt, das den Registrierungsschlüssel darstellt.

Syntax

NTSTATUS WdfDeviceOpenRegistryKey(
  [in]           WDFDEVICE              Device,
  [in]           ULONG                  DeviceInstanceKeyType,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Parameter

[in] Device

Ein Handle zu einem Framework-Geräteobjekt.

[in] DeviceInstanceKeyType

Gibt an, welcher Schlüssel oder Unterschlüssel geöffnet werden soll.

Anmerkung

UMDF unterstützt das Erstellen von Unterschlüsseln nicht.

Dies ist ein bitweiser OR der folgenden Flags (die in Wdm.hdefiniert sind).

DeviceInstanceKeyType-Flag	Bedeutung	Fachwerk
PLUGPLAY_REGKEY_DEVICE	Öffnet den Hardwareschlüssel des Geräts.	KMDF/UMDF
PLUGPLAY_REGKEY_DRIVER	Öffnet den Softwareschlüssel des Treibers. Ein UMDF-Treiber, der dieses Flag festlegt, muss auch DesiredAccess- auf KEY_READfestlegen. Andernfalls gibt diese Methode STATUS_ACCESS_DENIEDzurück.	KMDF/UMDF
PLUGPLAY_REGKEY_CURRENT_HWPROFILE	Ein KMDF-Treiber verwendet dieses Kennzeichen, um die Kopie des Hardware- oder Softwareschlüssels zu öffnen, der sich im aktuellen Hardwareprofil befindet.	KMDF
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	Ein UMDF-Treiber verwendet diese Flags zusammen, um den ServiceName Unterschlüssel des Softwareschlüssels des Treibers für lese-/schreibzugriff zu öffnen.	UMDF
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	Ebenso verwendet ein UMDF-Treiber diese Flags, um den ServiceName Unterschlüssel des Hardwareschlüssels des Geräts für lese-/schreibzugriff zu öffnen.	UMDF

[in] DesiredAccess

Ein ACCESS_MASK-typed-Wert, der Zugriffsrechte angibt, die der Treiber für den angegebenen Registrierungsschlüssel anfordert.

Ein KMDF-Treiber fordert in der Regel KEY_READ, KEY_WRITEoder KEY_READ | KEY_WRITE.

Wenn Sie einen UMDF-Treiber schreiben, verwenden Sie die folgende Tabelle.

DeviceInstanceKeyType	DesiredAccess
PLUGPLAY_REGKEY_DEVICE	KEY_READ
PLUGPLAY_REGKEY_DEVICE \| WDF_REGKEY_DEVICE_SUBKEY	KEY_READ oder KEY_READ \| KEY_SET_VALUE
PLUGPLAY_REGKEY_DRIVER	KEY_READ
PLUGPLAY_REGKEY_DRIVER \| WDF_REGKEY_DRIVER_SUBKEY	KEY_READ oder KEY_READ \| KEY_SET_VALUE

Bitten Sie als bewährte Methode nur um die Zugriffstypen, die Ihr Treiber benötigt.

[in, optional] KeyAttributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur, die vom Treiber bereitgestellte Attribute für das neue Registrierungsschlüsselobjekt enthält. Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] Key

Ein Zeiger auf einen Speicherort, der ein Handle für das neue Registrierungsschlüsselobjekt empfängt.

Rückgabewert

WdfDeviceOpenRegistryKey gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_DEVICE_REQUEST	WdfDeviceOpenRegistryKey wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben. Bei UMDF kann dieser Rückgabewert auf unzureichende Zugriffsrechte hinweisen.
STATUS_INSUFFICIENT_RESOURCES	Ein Registrierungsschlüsselobjekt konnte nicht zugeordnet werden.
STATUS_OBJECT_NAME_NOT_FOUND	Der angegebene Registrierungsschlüssel ist nicht vorhanden.

Eine Liste mit anderen Rückgabewerten, die die WdfDeviceOpenRegistryKey--Methode möglicherweise zurückgeben kann, finden Sie unter Framework Object Creation Errors.

Die Methode gibt möglicherweise andere NTSTATUS-Wertezurück.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Wenn Ihr Treiber einen Hardware- oder Softwareschlüssel öffnen muss, bevor er WdfDeviceCreateaufgerufen hat, muss er WdfFdoInitOpenRegistryKey anstelle von WdfDeviceOpenRegistryKeyaufrufen.

Wenn der Treiber den Registrierungsschlüssel verwendet hat, den er mit WdfDeviceOpenRegistryKey-geöffnet hat, muss der Treiber WdfRegistryCloseaufrufen.

Weitere Informationen zu den Registrierungs-, Hardware- und Softwareschlüsseln und Registrierungsobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Drivers.

Beispiele

Codebeispiele, die WdfDeviceOpenRegistryKeyverwenden, finden Sie unter WdfRegistryCreateKey, WdfRegistryOpenKeyund WdfRegistryQueryValue.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfdevice.h (einschließen Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	AccessHardwareKey(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

WdfFdoInitOpenRegistryKey

Freigeben über