ZwCreateKeyTransacted-Funktion (wdm.h)

Artikel
02/27/2024

Die ZwCreateKeyTransacted-Routine erstellt einen neuen Registrierungsschlüssel oder öffnet einen vorhandenen Und ordnet den Schlüssel einer Transaktion zu.

Syntax

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

Parameter

[out] KeyHandle

Ein Zeiger auf eine HANDLE-Variable, in die die Routine das Handle in den Schlüssel schreibt.

[in] DesiredAccess

Gibt den Typ des Zugriffs auf den Schlüssel an, den der Aufrufer anfordert. Dieser Parameter ist ein ACCESS_MASK Wert. Weitere Informationen finden Sie in der Beschreibung des DesiredAccess-Parameters der ZwCreateKey-Routine .

[in] ObjectAttributes

Ein Zeiger auf die Objektattribute des geöffneten Schlüssels. Dieser Parameter verweist auf eine OBJECT_ATTRIBUTES-Struktur , die zuvor von der InitializeObjectAttributes-Routine initialisiert worden sein muss. Der Aufrufer muss den Namen des Registrierungsschlüssels als ObjectName-Parameter im Aufruf von InitializeObjectAttributes angeben. 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

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

[in] CreateOptions

Gibt die Optionen an, die angewendet werden sollen, wenn die Routine den Schlüssel erstellt oder öffnet. Legen Sie diesen Parameter auf null oder auf das bitweise OR eines oder mehrerer der folgenden REG_OPTION_XXX-Flagbits fest.

CreateOptions-Flag	BESCHREIBUNG
REG_OPTION_VOLATILE	Der Schlüssel wird nach dem Neustart des Computers nicht beibehalten.
REG_OPTION_NON_VOLATILE	Der Schlüssel wird nach dem Neustart des Computers beibehalten.
REG_OPTION_CREATE_LINK	Der Schlüssel ist eine symbolische Verknüpfung. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.
REG_OPTION_BACKUP_RESTORE	Öffnen Sie den Schlüssel mit speziellen Berechtigungen, die Sicherungs- und Wiederherstellungsvorgänge ermöglichen. Dieses Flag wird von Geräte- und Zwischentreibern nicht verwendet.

[in] TransactionHandle

Ein Handle für ein Transaktionsobjekt. Um dieses Handle zu erhalten, können Sie die ZwCreateTransaction-Routine aufrufen. Wenn Sie über einen Zeiger auf ein Transaktionsobjekt verfügen, können Sie den Zeiger auf die ObOpenObjectByPointer-Routine angeben, um das entsprechende Transaktionshandle abzurufen.

[out, optional] Disposition

Ein Zeiger auf einen Speicherort, in den die Routine einen der folgenden Werte schreibt, um anzugeben, ob durch den Aufruf 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.

Sie können Disposition = NULL festlegen, wenn diese Informationen nicht benötigt werden.

Rückgabewert

ZwCreateKeyTransacted gibt STATUS_SUCCESS zurück, wenn der Aufruf den Schlüssel erfolgreich erstellt oder öffnet. Mögliche Fehlerrückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der ObjectAttributes-Parameter ist NULL oder verweist auf ungültige Informationen, oder der CreateOptions-Parameterwert gibt ungültige Optionen an.
STATUS_OBJECT_PATH_SYNTAX_BAD	Der Registrierungspfad in den Objektattributen ist ungültig.
STATUS_OBJECT_NAME_NOT_FOUND	Der Registrierungspfad in den Objektattributen wurde nicht gefunden.
STATUS_ACCESS_DENIED	Der Aufrufer verfügte nicht über die erforderlichen Zugriffsrechte, um ein Handle für den benannten Registrierungsschlüssel zu öffnen.
STATUS_INSUFFICIENT_RESOURCES	Ein Speicherbelegungsvorgang ist fehlgeschlagen.

Hinweise

Diese Routine stellt ein Handle bereit, mit dem der Aufrufer auf einen Registrierungsschlüssel zugreifen kann. Darüber hinaus ordnet diese Routine den Schlüssel einer aktiven Transaktion zu.

Nachdem das Handle, auf das von KeyHandle verwiesen wird, nicht mehr verwendet wird, muss der Treiber die ZwClose-Routine aufrufen, um es zu schließen.

Wie ZwCreateKeyTransacted ordnet die ZwOpenKeyTransacted-Routine einen Schlüssel einer Transaktion zu. Im Gegensatz zu ZwCreateKeyTransacted, das einen neuen Schlüssel erstellen oder einen vorhandenen Schlüssel öffnen kann, kann ZwOpenKeyTransacted nur einen bereits vorhandenen Registrierungsschlüssel öffnen.

Nachdem ein Kernelmodustreiber ein Handle für eine Transaktion abgerufen hat (z. B. durch Aufrufen von ZwCreateTransaction), kann der Treiber eine Reihe von Registrierungsvorgängen ausführen, die Teil dieser Transaktion sind. Der Treiber kann die Transaktion entweder durch Commit für die änderungen schließen, die in der Transaktion vorgenommen wurden, oder durch Rollback der Transaktion.

Nachdem der Treiber alle Registrierungsvorgänge erfolgreich abgeschlossen hat, die Teil einer Transaktion sind, kann er die ZwCommitTransaction-Routine aufrufen, um einen Commit für die Änderungen durchzuführen. Der Treiber kann die ZwRollbackTransaction-Routine aufrufen, um ein Rollback für die Transaktion auszuführen.

Während einer Transaktion ist ein Registrierungsvorgang Teil der Transaktion, wenn der Systemaufruf, der den Vorgang ausführt, eine der folgenden Bedingungen erfüllt:

Der Aufruf gibt als Eingabeparameter das Transaktionshandle an. Beispielsweise können Aufrufe von ZwCreateKeyTransacted und ZwOpenKeyTransacted der Transaktion ein oder mehrere Handles zu Registrierungsschlüsseln zuordnen.
Der Aufruf gibt als Eingabeparameter ein Registrierungsschlüsselhandle an, das durch einen Aufruf von ZwCreateKeyTransacted oder ZwOpenKeyTransacted abgerufen wurde, für den das Transaktionshandle bereitgestellt wurde. Beispielsweise kann ein Aufruf der ZwSetValueKey-Routine ein auf diese Weise abgerufenes Schlüsselhandle verwenden, um den Wert eines Registrierungsschlüssels als Teil einer Transaktion festzulegen.

Weitere Informationen zu Transaktionen im Kernelmodus finden Sie unter Verwenden des Kerneltransaktions-Managers.

Der Sicherheitsdeskriptor in den Objektattributen bestimmt, ob die durch den DesiredAccess-Parameter angegebenen Zugriffsrechte bei späteren Aufrufen von Routinen wie ZwOpenKeyTransacted , die auf den Schlüssel zugreifen, oder für Routinen wie ZwCreateKeyTransacted gewährt werden, die Unterschlüssel des Schlüssels erstellen.

Wenn der Aufrufer im Kernelmodus nicht in einem Systemthreadkontext ausgeführt wird, muss sichergestellt werden, dass alle erstellten Handles Kernelhandles 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 im Kernelmodus finden Sie unter Verwenden der Registrierung in einem Treiber.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und späteren Windows-Versionen.
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), PowerIrpDDis(wdm)