ZwCreateKey-Funktion (wdm.h)

Artikel
02/29/2024

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:

Als vollqualifizierter Pfadname, der im ObjectName-Member der Eingabe ObjectAttributes angegeben wird. Die Pfadnamen von Registrierungsschlüsseln beginnen mit \Registry.
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)