ZwOpenKeyTransacted-Funktion (wdm.h)

Artikel
08/08/2023

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

Syntax

NTSYSAPI NTSTATUS ZwOpenKeyTransacted(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [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] 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

ZwOpenKeyTransacted 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_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 ZwOpenKeyTransacted einen Fehler status Wert zurück und stellt kein Schlüsselhandle bereit. Im Gegensatz zur ZwCreateKeyTransacted-Routine erstellt die ZwOpenKeyTransacted-Routine den angegebenen Schlüssel nicht, wenn der Schlüssel nicht vorhanden ist. Sowohl ZwCreateKeyTransacted als auch ZwOpenKeyTransacted ordnen einer Transaktion einen Registrierungsschlüssel zu.

Die ZwOpenKey-Routine ähnelt ZwOpenKeyTransacted, ordnet aber keinem Schlüssel einer Transaktion zu.

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 ZwOpenKeyTransacted der Transaktion einen oder mehrere Schlüssel 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 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.

ZwOpenKeyTransacted 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 Vista 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)