WdfRegistryOpenKey-Funktion (wdfregistry.h)

Artikel
03/22/2025

[Gilt für KMDF und UMDF]

Die WdfRegistryOpenKey--Methode öffnet einen angegebenen Registrierungsschlüssel und erstellt ein Framework-Registrierungsschlüsselobjekt, das den Registrierungsschlüssel darstellt.

Syntax

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

Die Parameter

[in, optional] ParentKey

Ein Handle zu einem Framework-Registrierungsschlüsselobjekt. Dieses Objekt stellt einen übergeordneten Registrierungsschlüssel dar, den der Treiber geöffnet hat. Dieser Parameter ist optional und kann NULL-werden. Wenn der Parameter nicht NULL-ist, muss sich der Schlüssel, der KeyName- angibt, unter diesem übergeordneten Schlüssel in der Registrierung befinden. Weitere Informationen zu diesem übergeordneten Schlüssel finden Sie im Abschnitt "Hinweise".

[in] KeyName

Ein Zeiger auf eine UNICODE_STRING Struktur, die den Namen des zu öffnenden Schlüssels enthält. Der Schlüsselname kann Pfadinformationen enthalten. Wenn ParentKey-NULL-ist, muss KeyName- einen vollständigen Pfad zu einem Registrierungsschlüssel angeben. Beispiele finden Sie im Abschnitt "Hinweise".

[in] DesiredAccess

Ein ACCESS_MASK-typed-Wert, der Zugriffsrechte angibt, die der Treiber für den angegebenen Registrierungsschlüssel anfordert. Eine Liste der Zugriffsrechte, die treiber normalerweise für Registrierungsschlüssel verwenden, finden Sie unter Öffnen eines Handle für ein Registry-Key Object. Ihr Treiber muss nur die Zugriffstypen anfordern, die er benötigt. Beispielsweise darf der Treiber nicht nach KEY_ALL_ACCESS fragen, wenn er nur den Registrierungsschlüssel liest.

[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

WdfRegistryOpenKey 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	WdfRegistryOpenKey- wurde bei IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_INSUFFICIENT_RESOURCES	Ein Registrierungsschlüsselobjekt konnte nicht zugeordnet werden.
STATUS_ACCESS_DENIED	Das System hat die angegebenen Zugriffsrechte verweigert.
STATUS_OBJECT_NAME_NOT_FOUND	Der angegebene Registrierungsschlüssel ist nicht vorhanden.

Eine Liste mit anderen Rückgabewerten, die von der WdfRegistryOpenKey--Methode möglicherweise zurückgegeben werden, finden Sie unter Framework-Objekterstellungsfehler.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Bemerkungen

Um ein Handle für ein Registrierungsschlüsselobjekt abzurufen, das einen übergeordneten Schlüssel darstellt, kann Ihr Treiber WdfDriverOpenParametersRegistryKey-, WdfDeviceOpenRegistryKey-oder WdfFdoInitOpenRegistryKeyaufrufen.

Das im KeyName Parameter angegebene Zeichenfolgenformat hängt davon ab, ob der Aufrufer ein KMDF-Treiber oder ein UMDF-Treiber ist. Um beispielsweise den folgenden Pfad zu öffnen:

HKLM\System\CurrentControlSet\Control

Ihr Treiber verwendet möglicherweise diese bedingte Logik:

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

Wenn der Treiber einen Registrierungsschlüssel verwendet hat, der mit WdfRegistryOpenKey-geöffnet wird, muss der Treiber WdfRegistryCloseaufrufen.

Weitere Informationen zu Registrierungsschlüsselobjekten finden Sie unter Verwenden der Registrierung in Framework-Based Drivers.

Beispiele

Das folgende Codebeispiel öffnet den Softwareschlüssel eines Treibers und öffnet dann den MySubKey Registrierungsschlüssel, der sich unter dem Softwareschlüssel des Treibers befindet.

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

Anforderungen

Anforderung	Wert
Zielplattform	universell
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Kopfzeile	wdfregistry.h (include Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)