NtCreateTransactionManager-Funktion (wdm.h)

Artikel
02/07/2025

Die ZwCreateTransactionManager Routine erstellt ein neues Transaktions-Manager-Objekt.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Parameter

[out] TmHandle

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein Handle für das neue Transaktions-Manager-Objektempfängt.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den angeforderten Zugriff des Aufrufers auf das Transaktions-Manager-Objekt angibt. Zusätzlich zu den Zugriffsrechten, die für alle Arten von Objekten definiert sind (siehe ACCESS_MASK), kann der Aufrufer jedes der folgenden Zugriffsrechten für Transaktions-Manager-Objekte angeben.

ACCESS_MASK-Kennzeichnung	Ermöglicht es dem Aufrufer,
TRANSACTIONMANAGER_CREATE_RM	Erstellen eines Ressourcen-Managers (siehe ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Abrufen von Informationen zum Transaktions-Manager (siehe ZwQueryInformationTransactionManager und ZwEnumerateTransactionObject). Auch erforderlich für ZwOpenResourceManager, ZwCreateTransactionund ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Wiederherstellen des Transaktions-Managers (siehe ZwRecoverTransactionManager und ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Wird nicht verwendet.
TRANSACTIONMANAGER_SET_INFORMATION	Wird nicht verwendet.

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
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ und TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME und TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE und TRANSACTIONMANAGER_GENERIC_EXECUTE

[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] LogFileName

Ein Zeiger auf eine UNICODE_STRING Struktur, die den Pfad und Dateinamen eines CLFS-Protokolldateidatenstroms enthält, dem Transaktions-Manager-Objekt zugeordnet werden soll. Dieser Parameter muss NULL- sein, wenn der parameter CreateOptions TRANSACTION_MANAGER_VOLATILE ist. Andernfalls muss dieser Parameter nichtNULL-sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] CreateOptions

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

Option flag	Bedeutung
TRANSACTION_MANAGER_VOLATILE	Das Transaktions-Manager-Objekt ist veränderlich. Daher wird keine Protokolldatei verwendet.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Nur für die interne Verwendung.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Nur für die interne Verwendung.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Nur für die interne Verwendung.
TRANSACTION_MANAGER_COMMIT_LOWEST	Nur für die interne Verwendung.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Nur für die interne Verwendung.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Nur für die interne Verwendung.

[in, optional] CommitStrength

Reserviert für die zukünftige Verwendung. Dieser Parameter muss null sein.

Rückgabewert

ZwCreateTransactionManager 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 Wert eines Eingabeparameters ist ungültig.
STATUS_INSUFFICIENT_RESOURCES	KTM konnte Systemressourcen (in der Regel Speicher) nicht zuordnen.
STATUS_LOG_CORRUPTION_DETECTED	KTM hat beim Erstellen oder Öffnen der Protokolldatei einen Fehler festgestellt.
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 parameter ObjectAttributes angibt, ist bereits vorhanden.
STATUS_OBJECT_NAME_COLLISION	Das Betriebssystem hat einen doppelten Objektnamen erkannt. Der Fehler kann darauf hinweisen, dass der Protokolldatenstrom bereits verwendet wird.
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

Wenn der Protokolldateidatenstrom, den der LogFileName Parameter angibt, nicht vorhanden ist, ruft KTM CLFS auf, um den Datenstrom zu erstellen. Wenn der Stream bereits vorhanden ist, ruft KTM CLFS auf, um den Datenstrom zu öffnen.

Ihre TPS-Komponente muss ZwRecoverTransactionManager aufrufen, nachdem sie ZwCreateTransactionManager

Wenn Ihre TPS-Komponente das TRANSACTION_MANAGER_VOLATILE Flag im parameter CreateOptions angibt, müssen alle Ressourcenmanager, die dem Transaktions-Manager-Objekt zugeordnet sind, das RESOURCE_MANAGER_VOLATILE Flag angeben, wenn sie ZwCreateResourceManageraufrufen.

Eine TPS-Komponente, die ZwCreateTransactionManager aufruft muss schließlich ZwClose- aufrufen, um das Objekthandle zu schließen.

Weitere Informationen zur Verwendung von ZwCreateTransactionManagerfinden Sie unter Erstellen eines Ressourcen-Managers.

NtCreateTransactionManager und ZwCreateTransactionManager sind zwei Versionen derselben Windows Native System Services-Routine.

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, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis