Freigeben über


ZwCreateKey-Funktion (wdm.h)

Die ZwCreateKey-Routine erstellt einen neuen Registrierungsschlüssel oder öffnet einen vorhandenen Registrierungsschlüssel.

Syntax

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

Parameter

[out] KeyHandle

Zeiger auf eine HANDLE-Variable, die ein Handle auf den Schlüssel empfängt.

[in] DesiredAccess

Gibt einen ACCESS_MASK Wert an, der den angeforderten Zugriff auf das Objekt bestimmt. Zusätzlich zu den Zugriffsrechten, die für alle Objekttypen definiert sind (siehe ACCESS_MASK), kann der Aufrufer eine oder mehrere der folgenden Zugriffsrechte angeben, die für Objektverzeichnisse spezifisch sind:

DesiredAccess-Flag Ermöglicht dem Aufrufer, dies zu tun
KEY_QUERY_VALUE Lesen von Schlüsselwerten.
KEY_SET_VALUE Schreiben sie Schlüsselwerte.
KEY_CREATE_SUB_KEY Erstellen Sie Unterschlüssel für den Schlüssel.
KEY_ENUMERATE_SUB_KEYS Lesen Sie die Unterschlüssel des Schlüssels.
KEY_CREATE_LINK Erstellen Sie eine symbolische Verknüpfung mit dem Schlüssel. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
KEY_NOTIFY Bitten Sie, eine Benachrichtigung zu erhalten, wenn sich der Name, der Wert oder die Attribute des Schlüssels ändern. Weitere Informationen finden Sie unter ZwNotifyChangeKey.

Der Aufrufer kann auch eine der folgenden Konstanten angeben, die mehrere ACCESS_MASK Flags kombiniert.

Dauerhaft Besteht aus diesen ACCESS_MASK Flags
KEY_READ STANDARD_RIGHTS_READ, KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS und KEY_NOTIFY
KEY_WRITE STANDARD_RIGHTS_WRITE, KEY_SET_VALUE und KEY_CREATE_SUB_KEY
KEY_EXECUTE Identisch mit KEY_READ.
KEY_ALL_ACCESS STANDARD_RIGHTS_ALL, KEY_QUERY_VALUE, KEY_SET_VALUE, KEY_CREATE_SUB_KEY, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY und KEY_CREATE_LINK

[in] ObjectAttributes

Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die den Objektnamen und andere Attribute angibt. Verwenden Sie InitializeObjectAttributes , um diese Struktur zu initialisieren. Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss er das attribut OBJ_KERNEL_HANDLE festlegen, wenn initializeObjectAttributes aufgerufen wird.

TitleIndex

Geräte- und Zwischentreiber legen diesen Parameter auf Null fest.

[in, optional] Class

Zeiger auf eine Unicode-Zeichenfolge, die die Objektklasse des Schlüssels enthält. Diese Informationen werden vom Konfigurations-Manager verwendet.

[in] CreateOptions

Gibt die Optionen an, die beim Erstellen oder Öffnen eines Schlüssels angewendet werden sollen, die als kompatible Kombination der folgenden Flags angegeben werden.

CreateOptions-Flag BESCHREIBUNG
REG_OPTION_VOLATILE Der Schlüssel wird nicht beibehalten, wenn das System neu gestartet wird.
REG_OPTION_NON_VOLATILE Der Schlüssel wird beibehalten, wenn das System neu gestartet wird.
REG_OPTION_CREATE_LINK Der neu erstellte Schlüssel ist eine symbolische Verknüpfung. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
REG_OPTION_BACKUP_RESTORE Schlüssel sollten mit speziellen Berechtigungen erstellt oder geöffnet werden, die Sicherungs- und Wiederherstellungsvorgänge ermöglichen. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.

[out, optional] Disposition

Zeiger auf eine Variable, die einen Wert empfängt, der angibt, ob ein neuer Schlüssel erstellt oder ein vorhandener Schlüssel geöffnet wurde.

Dispositionswert BESCHREIBUNG
REG_CREATED_NEW_KEY Ein neuer Schlüssel wurde erstellt.
REG_OPENED_EXISTING_KEY Ein vorhandener Schlüssel wurde geöffnet.

Rückgabewert

ZwCreateKey gibt bei Erfolg STATUS_SUCCESS oder den entsprechenden NTSTATUS-Fehlercode bei Einem Fehler zurück.

Hinweise

ZwCreateKey stellt ein Handle bereit, mit dem der Aufrufer einen Registrierungsschlüssel bearbeiten kann. Weitere Informationen finden Sie unter Verwenden der Registrierung in einem Treiber.

Sobald der von KeyHandle angezeigte Handle nicht mehr verwendet wird, muss der Treiber ZwClose aufrufen, um ihn zu schließen.

Es gibt zwei alternative Möglichkeiten, den Namen der Datei anzugeben, die mit ZwCreateKey erstellt oder geöffnet werden soll:

  1. Als vollqualifizierter Pfadname, der im ObjectName-Member der Eingabe ObjectAttributes angegeben wird. Die Pfadnamen von Registrierungsschlüsseln beginnen mit \Registry.

  2. Als Pfadname relativ zu einem anderen Registrierungsschlüssel, dargestellt durch das Handle im RootDirectory-Member der Eingabe ObjectAttributes.

Wenn der von ObjectAttributes angegebene Schlüssel nicht vorhanden ist, versucht die Routine, den Schlüssel zu erstellen. Damit dieser Versuch erfolgreich ist, muss der neue Schlüssel ein direkter Unterschlüssel des Schlüssels sein, auf den von RootDirectory verwiesen wird, und der Schlüssel, auf den RootDirectory verweist, muss für KEY_CREATE_SUB_KEY Zugriff geöffnet worden sein.

Wenn der angegebene Schlüssel bereits vorhanden ist, wird er geöffnet, und sein Wert wird in keiner Weise beeinflusst.

Die von ObjectAttributes beim Erstellen eines Schlüssels angegebenen Sicherheitsattribute bestimmen, ob der angegebene DesiredAccess bei nachfolgenden Aufrufen von ZwCreateKey und ZwOpenKey gewährt wird.

Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss er sicherstellen, dass alle von dem Aufrufer erstellten Handles private Handles sind. Andernfalls kann der Prozess, in dessen Kontext der Treiber ausgeführt wird, auf das Handle zugreifen. Weitere Informationen finden Sie unter Objekthandles.

Weitere Informationen zum Arbeiten mit Registrierungsschlüsseln finden Sie unter Verwenden der Registrierung in einem Treiber.

Wenn der Aufruf dieser Funktion im Benutzermodus erfolgt, sollten Sie den Namen "NtCreateKey" anstelle von "ZwCreateKey" verwenden.

Die NtCreateKey-Routine im Windows-Kernel ist für Kernelmodustreiber nicht direkt zugänglich.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung Wert
Zielplattform Universell
Header wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI-Complianceregeln HwStorPortProhibitedDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)

Weitere Informationen

ACCESS_MASK

InitializeObjectAttributes

Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen

ZwClose

ZwDeleteKey

ZwEnumerateKey

ZwEnumerateValueKey

ZwFlushKey

ZwNotifyChangeKey

ZwOpenKey

ZwQueryValueKey

ZwSetValueKey