ZwCreateTransactionManager-Funktion (wdm.h)

Artikel
02/27/2024

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

Syntax

NTSYSCALLAPI NTSTATUS ZwCreateTransactionManager(
  [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 auf das neue Transaktions-Manager-Objekt empfängt.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den vom Aufrufer angeforderten Zugriff 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 eines der folgenden Zugriffsberechtigungsflags für Transaktions-Manager-Objekte angeben.

ACCESS_MASK Flag	Ermöglicht dem Aufrufer die
TRANSACTIONMANAGER_CREATE_RM	Erstellen Sie einen Ressourcen-Manager (siehe ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Rufen Sie Informationen zum Transaktions-Manager ab (siehe ZwQueryInformationTransactionManager und ZwEnumerateTransactionObject). Auch für ZwOpenResourceManager, ZwCreateTransaction und ZwOpenTransaction erforderlich.)
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. Die folgende Tabelle zeigt, wie die Bitmaps bestimmten Zugriffsrechten entsprechen.

Bitmap "Rechte"	Satz 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 er das attribut OBJ_KERNEL_HANDLE festlegen, wenn initializeObjectAttributes aufgerufen wird. Dieser Parameter ist optional und kann NULL sein.

[in, optional] LogFileName

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

[in, optional] CreateOptions

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

Optionsflag	Bedeutung
TRANSACTION_MANAGER_VOLATILE	Das Transaktions-Manager-Objekt ist volatil. Daher wird keine Protokolldatei verwendet.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Nur zur internen Verwendung.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Nur zur internen Verwendung.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Nur zur internen Verwendung.
TRANSACTION_MANAGER_COMMIT_LOWEST	Nur zur internen Verwendung.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Nur zur internen Verwendung.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Nur zur internen Verwendung.

[in, optional] CommitStrength

Für die zukünftige Verwendung reserviert. 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 keine Systemressourcen (in der Regel Arbeitsspeicher) zuordnen.
STATUS_LOG_CORRUPTION_DETECTED	BEI KTM ist beim Erstellen oder Öffnen der Protokolldatei ein Fehler aufgetreten.
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_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 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

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

Ihre TPS-Komponente muss ZwRecoverTransactionManager aufrufen, nachdem sie ZwCreateTransactionManager aufgerufen hat.

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

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

Weitere Informationen zur Verwendung von ZwCreateTransactionManager finden Sie unter Erstellen einer Resource Manager.

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, 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 (include Wdm.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)