WdfRegistryCreateKey-Funktion (wdfregistry.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfRegistryCreateKey-Methode erstellt und öffnet einen angegebenen Registrierungsschlüssel oder öffnet den Schlüssel, sofern er bereits vorhanden ist, und erstellt ein Framework-Registrierungsschlüsselobjekt, das den Registrierungsschlüssel darstellt.

Syntax

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [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.

[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] CreateOptions

Mindestens ein Flag. Informationen zu diesen Flags finden Sie unter createOptions-Parameter oder ZwCreateKey.

[out, optional] CreateDisposition

Ein Zeiger auf einen Speicherort, der REG_CREATED_NEW_KEY empfängt, wenn ein neuer Schlüssel erstellt wird, oder REG_OPENED_EXISTING_KEY, wenn ein vorhandener Schlüssel geöffnet wird. Diese Werte werden in Wdm.h definiert. Dieser Zeiger ist optional und kann NULL sein.

[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

WdfRegistryCreateKey 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	WdfRegistryCreateKey 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 WdfRegistryCreateKey-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.

Standardmäßig ist das übergeordnete Element des neuen Registrierungsschlüsselobjekts das Frameworktreiberobjekt, das von der WdfDriverCreate-Methode erstellt wird. Sie können den ParentObject-Member der WDF_OBJECT_ATTRIBUTES-Struktur verwenden, um ein anderes übergeordnetes Element anzugeben. Das Framework löscht das Registrierungsschlüsselobjekt, wenn es das übergeordnete Objekt löscht. Wenn der Treiber das übergeordnete Standardobjekt nicht ändert, sollte der Treiber das Registrierungsschlüsselobjekt löschen, wenn er die Verwendung des -Objekts abgeschlossen hat. Andernfalls verbleibt das Registrierungsschlüsselobjekt, bis der E/A-Manager Den Treiber entladen hat.

Wenn ihr Treiber das übergeordnete Standardelement nicht ändert, sollte der Treiber WdfRegistryClose aufrufen, wenn er die Verwendung des -Objekts abgeschlossen hat. Andernfalls verbleibt das Registrierungsschlüsselobjekt, bis der E/A-Manager Den Treiber entladen hat. Alternativ kann der Treiber WdfObjectDelete aufrufen, um das Registrierungsschlüsselobjekt zu löschen.

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. Anschließend wird der Registrierungsschlüssel myKeyStr erstellt und 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"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  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)