WdfRegistryCreateKey-Funktion (wdfregistry.h)

[Gilt für KMDF und UMDF]

Die WdfRegistryCreateKey-Methode erstellt und öffnet einen angegebenen Registrierungsschlüssel, oder öffnet einfach den Schlüssel, sofern vorhanden, 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
);

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.

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

Mindestens ein Kennzeichen. Informationen zu diesen Flags finden Sie im CreateOptions Parameter oder ZwCreateKey.

[out, optional] CreateDisposition

Ein Zeiger auf eine Position, die REG_CREATED_NEW_KEY empfängt, wenn ein neuer Schlüssel erstellt oder REG_OPENED_EXISTING_KEY wird, 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:

Eine Liste mit anderen Rückgabewerten, die die WdfRegistryCreateKey--Methode möglicherweise zurückgeben kann, 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.

Standardmäßig ist das übergeordnete Objekt des neuen Registrierungsschlüsselobjekts das Frameworktreiberobjekt, das vom WdfDriverCreate-Methode erstellt wird. Sie können das ParentObject Element 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 Ihr Treiber das übergeordnete Standardobjekt nicht ändert, sollte der Treiber das Registrierungsschlüsselobjekt löschen, wenn er die Verwendung des Objekts abgeschlossen hat. andernfalls bleibt das Registrierungsschlüsselobjekt erhalten, bis der E/A-Manager den Treiber entlädt.

Wenn ihr Treiber das übergeordnete Standardobjekt nicht ändert, sollte der Treiber WdfRegistryClose- aufrufen, wenn er die Verwendung des Objekts abgeschlossen hat; andernfalls bleibt das Registrierungsschlüsselobjekt erhalten, bis der E/A-Manager den Treiber entlädt. 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 Drivers.

Beispiele

Im folgenden Codebeispiel wird der Softwareschlüssel eines Treibers geöffnet. Anschließend wird der myKeyStr Registrierungsschlüssel 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

Siehe auch

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCreate

WdfDriverOpenParametersRegistryKey-

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey-

ZwCreateKey-