ZwCreateTransaction-Funktion (wdm.h)

Artikel
03/14/2023

Die ZwCreateTransaction-Routine erstellt ein Transaktionsobjekt.

Syntax

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Parameter

[out] TransactionHandle

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein Handle für das neue Transaktionsobjekt empfängt, wenn der Aufruf von ZwCreateTransaction erfolgreich ist.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den vom Aufrufer angeforderten Zugriff auf das Transaktionsobjekt angibt. Zusätzlich zu den Zugriffsrechten, die für alle Arten von Objekten definiert sind (siehe ACCESS_MASK), kann der Aufrufer jedes der folgenden Flags für Transaktionsobjekte angeben.

Zugriffsmaske	Ermöglicht dem Aufrufer die
TRANSACTION_COMMIT	Commit für die Transaktion (siehe ZwCommitTransaction).
TRANSACTION_ENLIST	Erstellen Sie eine Enlistment für die Transaktion (siehe ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Nicht verwenden.
TRANSACTION_QUERY_INFORMATION	Rufen Sie Informationen zur Transaktion ab (siehe ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Rollback der Transaktion (siehe ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Legen Sie Informationen für die Transaktion fest (siehe ZwSetInformationTransaction).

Alternativ können Sie eine oder mehrere der folgenden ACCESS_MASK Bitmaps angeben. Diese Bitmaps kombinieren die Flags aus der vorherigen Tabelle mit den STANDARD_RIGHTS_XXX-Flags , die auf der ACCESS_MASK Referenzseite beschrieben werden. Sie können diese Bitmaps auch mit zusätzlichen Flags aus der vorherigen Tabelle kombinieren. Die folgende Tabelle zeigt, wie die Bitmaps bestimmten Zugriffsrechten entsprechen.

Bitmap "Rechte"	Satz bestimmter Zugriffsrechte
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION und SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT und SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK und SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE und TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE und SYNCHRONIZE

In der Regel gibt ein Ressourcen-Manager TRANSACTION_RESOURCE_MANAGER_RIGHTS an.

Der DesiredAccess-Wert darf nicht 0 sein.

[in, optional] ObjectAttributes

Ein Zeiger auf eine OBJECT_ATTRIBUTES-Struktur , die den Objektnamen und andere Attribute angibt. Verwenden Sie die InitializeObjectAttributes-Routine , 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. Dieser Parameter ist optional und kann NULL sein.

[in, optional] Uow

Ein Zeiger auf eine GUID, die KTM als UOW-Bezeichner (Unit of Work) des neuen Transaktionsobjekts verwendet. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, generiert KTM eine GUID und weist sie dem Transaktionsobjekt zu. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] TmHandle

Ein Handle für ein Transaktions-Manager-Objekt , das durch einen vorherigen Aufruf von ZwCreateTransactionManager oder ZwOpenTransactionManager abgerufen wurde. KTM weist das neue Transaktionsobjekt dem angegebenen Transaktions-Manager-Objekt zu. Wenn dieser Parameter NULL ist, weist KTM das neue Transaktionsobjekt später einem Transaktions-Manager zu, wenn ein Ressourcen-Manager eine Registrierung für die Transaktion erstellt.

[in, optional] CreateOptions

Optionale Objekterstellungsflags. Die folgende Tabelle enthält die verfügbaren Flags, die in Ktmtypes.h definiert sind.

Optionsflag	Bedeutung
TRANSACTION_DO_NOT_PROMOTE	Für zukünftige Verwendung reserviert.

[in, optional] IsolationLevel

Für zukünftige Verwendung reserviert. Aufrufer müssen diesen Parameter auf Null festlegen.

[in, optional] IsolationFlags

Für die zukünftige Verwendung reserviert. Aufrufer sollten diesen Parameter auf 0 festlegen.

[in, optional] Timeout

Ein Zeiger auf einen Timeoutwert. Wenn die Transaktion bis zu der von diesem Parameter angegebenen Zeit noch nicht committet wurde, führt KTM ein Rollback für die Transaktion aus. Der Timeoutwert wird in Systemzeiteinheiten (Intervalle von 100 Nanosekunden) ausgedrückt und kann entweder eine absolute Zeit oder eine relative Zeit angeben. Wenn der Wert, auf den durch Timeout verwiesen wird, negativ ist, ist die Ablaufzeit relativ zur aktuellen Systemzeit. Andernfalls ist die Ablaufzeit absolut. Dieser Zeiger ist optional und kann NULL sein, wenn Sie nicht möchten, dass die Transaktion einen Timeoutwert aufweist. Wenn Timeout = NULL oder *Timeout = 0 ist, wird für die Transaktion kein Timeout ausgeführt. (Sie können auch ZwSetInformationTransaction verwenden, um einen Timeoutwert festzulegen.)

[in, optional] Description

Ein Zeiger auf eine vom Aufrufer bereitgestellte UNICODE_STRING-Struktur , die eine NULL-beendete Zeichenfolge enthält. Die Zeichenfolge enthält eine Beschreibung der Transaktion. KTM speichert eine Kopie der Zeichenfolge und schließt die Zeichenfolge in Nachrichten ein, die in den Protokolldatenstrom geschrieben werden. Die maximale Zeichenfolgenlänge ist MAX_TRANSACTION_DESCRIPTION_LENGTH. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

ZwCreateTransaction gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Routine möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Der CreateOptions-Parameter enthält ein ungültiges Flag, der DesiredAccess-Parameter ist 0, oder die Zeichenfolge des Description-Parameters ist zu lang.
STATUS_INSUFFICIENT_RESOURCES	KTM konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen.
STATUS_INVALID_ACL	Eine Sicherheitsbeschreibung enthält eine ungültige Zugriffssteuerungsliste (Invalid Access Control List, ACL).
STATUS_INVALID_SID	Ein Sicherheitsdeskriptor enthält einen ungültigen Sicherheitsbezeichner (SID).
STATUS_OBJECT_NAME_EXISTS	Der Objektname, den der ObjectAttributes-Parameter angibt, ist bereits vorhanden.
STATUS_OBJECT_NAME_INVALID	Der Objektname, den der ObjectAttributes-Parameter angibt, ist ungültig.
STATUS_ACCESS_DENIED	Der Wert des DesiredAccess-Parameters ist ungültig.

Die Routine gibt möglicherweise andere NTSTATUS-Werte zurück.

Hinweise

Der Aufrufer kann den Uow-Parameter verwenden, um einen UOW-Bezeichner für das Transaktionsobjekt anzugeben. Wenn der Aufrufer keinen UOW-Bezeichner angibt, generiert KTM eine GUID und weist sie dem Transaktionsobjekt zu. Der Aufrufer kann diese GUID später abrufen, indem er ZwQueryInformationTransaction aufruft.

In der Regel sollten Sie ktm eine GUID für das Transaktionsobjekt generieren lassen, es sei denn, Ihre Komponente kommuniziert mit einer anderen TPS-Komponente, die bereits einen UOW-Bezeichner für die Transaktion generiert hat.

Um das Transaktionshandle zu schließen, muss die Komponente, die ZwCreateTransaction aufgerufen hat , ZwClose aufrufen. Wenn das letzte Transaktionshandle geschlossen wird, bevor eine Komponente ZwCommitTransaction für die Transaktion aufruft, führt KTM ein Rollback für die Transaktion aus.

Weitere Informationen dazu, wie Transaktionsclients ZwCreateTransaction verwenden sollten, finden Sie unter Erstellen eines Transaktionsclients.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx - und ZwXxx-Versionen einer Windows Native System Services-Routine anders verhalten, wie 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 systemeigenen Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Betriebssystemversionen.
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)