ZwOpenKeyTransactedEx-Funktion (wdm.h)

Artikel
08/08/2023

Die ZwOpenKeyTransactedEx-Routine öffnet einen vorhandenen Registrierungsschlüssel und ordnet den Schlüssel einer Transaktion zu.

Syntax

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

Parameter

[out] KeyHandle

Ein Zeiger auf eine HANDLE-Variable, in die die Routine den 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.

[in] OpenOptions

Gibt die Optionen an, die beim Öffnen des Schlüssels angewendet werden sollen. Legen Sie diesen Parameter auf null oder auf den bitweisen OR eines oder mehrerer der folgenden REG_OPTION_XXX-Flagbits fest.

OpenOptions-Flag	BESCHREIBUNG
REG_OPTION_OPEN_LINK	Der Schlüssel ist eine symbolische Verbindung. Dieses Flag wird nicht von Geräte- und Zwischentreibern verwendet.
REG_OPTION_BACKUP_RESTORE	Der Schlüssel sollte mit speziellen Berechtigungen geöffnet werden, die Sicherungs- und Wiederherstellungsvorgänge ermöglichen. Dieses Flag wird nicht von Geräte- und Zwischentreibern 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 bereitstellen, um das entsprechende Transaktionshandle abzurufen.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der ObjectAttributes-Parameter ist NULL oder verweist auf ungültige Informationen.
STATUS_INVALID_PARAMETER_4	Der OpenOptions-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	Fehler bei einem Speicherbelegungsvorgang.

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.

Wenn der angegebene Schlüssel nicht in der Registrierung vorhanden ist, gibt ZwOpenKeyTransactedEx einen Fehler status Wert zurück und stellt kein Schlüsselhandle bereit. Im Gegensatz zur ZwCreateKeyTransacted-Routine erstellt die ZwOpenKeyTransactedEx-Routine den angegebenen Schlüssel nicht, wenn der Schlüssel nicht vorhanden ist. Sowohl ZwCreateKeyTransacted als auch ZwOpenKeyTransactedEx ordnen einer Transaktion einen Registrierungsschlüssel zu.

Die ZwOpenKeyEx-Routine ähnelt ZwOpenKeyTransactedEx, ordnet jedoch keinen Schlüssel einer Transaktion zu.

Die ZwOpenKeyTransacted-Routine ähnelt ZwOpenKeyTransactedEx , akzeptiert jedoch keinen OpenOptions-Parameter . Mit dem OpenOptions-Parameter von ZwOpenKeyTransactedEx kann der Aufrufer einen Schlüssel öffnen, der eine symbolische Verknüpfung darstellt, oder einen Schlüssel für Sicherungs- und Wiederherstellungsvorgänge öffnen. Ein Aufruf von ZwOpenKeyTransactedEx , bei dem der OpenOptions-Parameter auf 0 festgelegt ist, entspricht einem Aufruf von ZwOpenKeyTransacted.

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 schließen, indem er für die Änderungen, die in der Transaktion vorgenommen wurden, committ 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 ZwOpenKeyTransactedEx der Transaktion einen oder mehrere Schlüssel zuordnen.
Der Aufruf gibt als Eingabeparameter ein Registrierungsschlüsselhandle an, das durch einen Aufruf von ZwCreateKeyTransacted oder ZwOpenKeyTransactedEx abgerufen wurde, für den das Transaktionshandle bereitgestellt wurde. Beispielsweise kann ein Aufruf der ZwSetValueKey-Routine ein Schlüsselhandle verwenden, das auf diese Weise abgerufen wurde, um den Wert eines Registrierungsschlüssels als Teil einer Transaktion festzulegen.

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

ZwOpenKeyTransactedEx ignoriert die Sicherheitsinformationen in der Struktur, auf die der ObjectAttributes-Parameter verweist.

Wenn der Kernelmodusaufrufer nicht in einem Systemthreadkontext ausgeführt wird, muss er sicherstellen, dass alle von diesem 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 7 und höheren Versionen des Windows-Betriebssystems.
Zielplattform	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)