WdfRegistryOpenKey-Funktion (wdfregistry.h)

Artikel
08/08/2023

[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
);

Parameter

[in, optional] ParentKey

Ein Handle für ein Framework-Registrierungsschlüsselobjekt. Dieses Objekt stellt einen übergeordneten Registrierungsschlüssel dar, den der Treiber geöffnet hat. Dieser Parameter ist optional und kann NULL sein. Wenn der Parameter nicht NULL ist, muss sich der Schlüssel, den 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 ParentKeyNULL ist, muss KeyName einen vollständigen Pfad zu einem Registrierungsschlüssel angeben. Beispiele finden Sie im Abschnitt Hinweise.

[in] DesiredAccess

Ein ACCESS_MASK typisierter Wert, der Zugriffsrechte angibt, die der Treiber für den angegebenen Registrierungsschlüssel anfordert. Eine Liste der Zugriffsrechte, die Treiber in der Regel für Registrierungsschlüssel verwenden, finden Sie unter Öffnen eines Handle für ein Registry-Key-Objekt. Ihr Treiber muss nur nach den benötigten Zugriffstypen fragen. Der Treiber darf beispielsweise 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 unter IRQL = PASSIVE_LEVEL nicht aufgerufen.
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde 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 Fehler beim Erstellen von Frameworkobjekten.

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Hinweise

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

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

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 die Verwendung eines Registrierungsschlüssels abgeschlossen hat, den er mit WdfRegistryOpenKey öffnet, muss der Treiber WdfRegistryClose aufrufen.

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

Beispiele

Im folgenden Codebeispiel wird der Softwareschlüssel eines Treibers geöffnet, und dann wird der Registrierungsschlüssel MySubKey geöffnet, 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
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfregistry.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)