NtCreateTransaction-Funktion (wdm.h)

Artikel
02/07/2025

Die ZwCreateTransaction Routine erstellt ein Transaktionsobjekt.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [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 angeforderten Zugriff des Aufrufers 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 es dem Aufrufer,
TRANSACTION_COMMIT	Commit der Transaktion (siehe ZwCommitTransaction).
TRANSACTION_ENLIST	Erstellen Sie eine Liste für die Transaktion (siehe ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Nicht verwenden.
TRANSACTION_QUERY_INFORMATION	Abrufen von Informationen zur Transaktion (siehe ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Zurücksetzen der Transaktion (siehe ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Festlegen von Informationen für die Transaktion (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. In der folgenden Tabelle wird gezeigt, wie die Bitmaps bestimmten Zugriffsrechten entsprechen.

Rechtebitmap	Festlegen bestimmter Zugriffsrechte
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION und SYNCHRONISIEREN
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT und SYNCHRONISIEREN
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK und SYNCHRONISIEREN
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 SYNCHRONISIEREN

In der Regel gibt ein Ressourcenmanager TRANSACTION_RESOURCE_MANAGER_RIGHTS an.

Der wert DesiredAccess darf nicht null 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 das attribut OBJ_KERNEL_HANDLE festgelegt werden, wenn er InitializeObjectAttributesaufruft. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] Uow

Ein Zeiger auf eine GUID, die KTM als Arbeitseinheit (UOW) des neuen Transaktionsobjekts verwendet,. Dieser Parameter ist optional und kann NULL-werden. Wenn dieser Parameter NULL-ist, generiert KTM eine GUID und weist ihn 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 ZwOpenTransactionManagerabgerufen 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 Ressourcenmanager eine Liste für die Transaktion erstellt.

[in, optional] CreateOptions

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

Option flag	Bedeutung
TRANSACTION_DO_NOT_PROMOTE	Reserviert für die zukünftige Verwendung.

[in, optional] IsolationLevel

Reserviert für die zukünftige Verwendung. Aufrufer müssen diesen Parameter auf Null festlegen.

[in, optional] IsolationFlags

Reserviert für die zukünftige Verwendung. Aufrufer sollten diesen Parameter auf Null festlegen.

[in, optional] Timeout

Ein Zeiger auf einen Timeoutwert. Wenn die Transaktion nicht durch den durch diesen Parameter angegebenen Zeitpunkt zugesichert wurde, setzt KTM die Transaktion zurück. Der Timeoutwert wird in Systemzeiteinheiten (100-Nanosekunden-Intervalle) ausgedrückt und kann entweder eine absolute Zeit oder eine relative Zeit angeben. Wenn der von timeout verweist, ist die Ablaufzeit relativ zur aktuellen Systemzeit. Andernfalls ist die Ablaufzeit absolut. Dieser Zeiger ist optional und kann NULL- werden, wenn die Transaktion keinen Timeoutwert aufweisen soll. Wenn Timeout = NULL- oder *Timeout- = 0 ist, wird kein Timeout für die Transaktion 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 MIT NULL beendete Zeichenfolge enthält. Die Zeichenfolge enthält eine Beschreibung der Transaktion. KTM speichert eine Kopie der Zeichenfolge und enthält die Zeichenfolge in Nachrichten, die sie in den Protokolldatenstrom schreibt. Die maximale Zeichenfolgenlänge ist MAX_TRANSACTION_DESCRIPTION_LENGTH. Dieser Parameter ist optional und kann NULL-werden.

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 parameter CreateOptions enthält ein ungültiges Flag, der DesiredAccess Parameter null ist oder die Description Parameterzeichenfolge zu lang ist.
STATUS_INSUFFICIENT_RESOURCES	KTM konnte Systemressourcen (in der Regel Speicher) nicht zuordnen.
STATUS_INVALID_ACL	Ein Sicherheitsdeskriptor enthält eine ungültige Zugriffssteuerungsliste (Access Control List, ACL).
STATUS_INVALID_SID	Ein Sicherheitsdeskriptor enthält einen ungültigen Sicherheitsbezeichner (SECURITY Identifier, SID).
STATUS_OBJECT_NAME_EXISTS	Der Objektname, den der ObjectAttributes Parameter angibt, ist bereits vorhanden.
STATUS_OBJECT_NAME_INVALID	Der Objektname, den der parameter ObjectAttributes angibt, ist ungültig.
STATUS_ACCESS_DENIED	Der Wert des parameters DesiredAccess ist ungültig.

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

Bemerkungen

Der Aufrufer kann den parameter Uow 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 ZwQueryInformationTransactionaufgerufen wird.

Normalerweise sollten Sie ZULASSEN, dass KTM eine GUID für das Transaktionsobjekt generiert, es sei denn, Ihre Komponente kommuniziert mit einer anderen TPS-Komponente, die bereits einen UOW-Bezeichner für die Transaktion generiert hat.

Zum Schließen des Transaktionshandles muss die Komponente, die ZwCreateTransaction- aufgerufen hat, ZwClose-aufrufen. Wenn das letzte Transaktionshandle geschlossen wird, bevor Komponenten ZwCommitTransaction- für die Transaktion aufgerufen werden, setzt KTM die Transaktion zurück.

Weitere Informationen dazu, wie Transaktionsclients ZwCreateTransaction-verwenden sollen, 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 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
mindestens unterstützte Client-	Verfügbar in Windows Vista und höheren Betriebssystemversionen.
Zielplattform-	Universal
Header-	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis