NtCreateTransaction-Funktion (wdm.h)
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 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 |
|---|---|
|
Der CreateOptions-Parameter enthält ein ungültiges Flag, der DesiredAccess-Parameter ist 0, oder die Zeichenfolge des Description-Parameters ist zu lang. |
|
KTM konnte keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen. |
|
Eine Sicherheitsbeschreibung enthält eine ungültige Zugriffssteuerungsliste (Invalid Access Control List, ACL). |
|
Ein Sicherheitsdeskriptor enthält einen ungültigen Sicherheitsbezeichner (SID). |
|
Der Objektname, den der ObjectAttributes-Parameter angibt, ist bereits vorhanden. |
|
Der Objektname, den der ObjectAttributes-Parameter angibt, ist ungültig. |
|
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, da 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 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, PowerIrpDDis |