ZwCreateKey-Funktion (wdm.h)

Artikel
12/21/2024

Die ZwCreateKey Routine erstellt einen neuen Registrierungsschlüssel oder öffnet eine vorhandene.

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 an 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	Schlüsselwerte lesen.
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 Kennzeichen 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.

Konstante	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

Zeigen Sie 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 das attribut OBJ_KERNEL_HANDLE festgelegt werden, wenn er InitializeObjectAttributesaufruft.

TitleIndex

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

[in, optional] Class

Zeigen Sie 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 einer Taste angewendet werden sollen, die als kompatible Kombination der folgenden Flags angegeben ist.

Flag "CreateOptions"	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 ein symbolischer Zusammenhang. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern verwendet.
REG_OPTION_BACKUP_RESTORE	Schlüssel sollte mit speziellen Berechtigungen erstellt oder geöffnet werden, die Sicherungs- und Wiederherstellungsvorgänge zulassen. Dieses Kennzeichen wird nicht von Geräte- und Zwischentreibern verwendet.

[out, optional] Disposition

Zeigen Sie 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	Es wurde ein neuer Schlüssel erstellt.
REG_OPENED_EXISTING_KEY	Ein vorhandener Schlüssel wurde geöffnet.

Rückgabewert

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

Bemerkungen

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- darauf verwiesene Handle nicht mehr verwendet wird, muss der Treiber ZwClose- aufrufen, um es zu schließen.

Es gibt zwei alternative Möglichkeiten, den Namen der zu erstellenden oder geöffneten Datei mit ZwCreateKey-anzugeben:

Als vollqualifizierter Pfadname, angegeben im ObjectName Member der Eingabe ObjectAttributes. 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 durch 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 RootDirectoryverweist, 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 ist in keiner Weise betroffen.

Die von ObjectAttributes beim Erstellen eines Schlüssels angegebenen Sicherheitsattribute bestimmen, ob die angegebene DesiredAccess- für nachfolgende Aufrufe von ZwCreateKey und ZwOpenKeygewährt wird.

Wenn der Aufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss sichergestellt werden, dass es sich bei den erstellten Handles um private Handles handelt. Andernfalls kann über den Prozess, in dem der Treiber ausgeführt wird, auf das Handle zugegriffen werden kann. Weitere Informationen finden Sie unter Object Handles.

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 kann nicht direkt auf Kernelmodustreiber zugegriffen werden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), IrqlZwPassive(wdm), PowerIrpDDis(wdm), ZwRegistryCreate(storport), ZwRegistryCreate(storport), ZwRegistryCreate(wdm), ZwRegistryOpen(wdm)