NtOpenTransactionManager-Funktion (wdm.h)

Artikel
08/08/2023

Die ZwOpenTransactionManager-Routine ruft ein Handle für ein vorhandenes Transaktions-Manager-Objekt ab.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] LPGUID             TmIdentity,
  [in, optional] ULONG              OpenOptions
);

Parameter

[out] TmHandle

Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die ein Handle für das Transaktions-Manager-Objekt empfängt, wenn ZwOpenTransactionManager STATUS_SUCCESS zurückgibt.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den vom Aufrufer angeforderten Zugriff auf das Transaktions-Manager-Objekt angibt. Informationen zum Angeben dieses Parameters finden Sie im DesiredAccess-Parameter von ZwCreateTransactionManager.

[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 des Protokolldateidatenstroms enthält, der beim Erstellen des Transaktions-Manager-Objekts erstellt wurde. Weitere Informationen finden Sie im LogFileName-Parameter von ZwCreateTransactionManager. Dieser Parameter ist optional und kann NULL sein.

[in, optional] TmIdentity

Ein Zeiger auf eine GUID, die das Transaktions-Manager-Objekt identifiziert. Dieser Parameter ist optional und kann NULL sein.

[in, optional] OpenOptions

Dieser Parameter wird nicht verwendet und muss null entsprechen.

Rückgabewert

ZwOpenTransactionManager 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_OBJECT_NAME_INVALID	Der Objektname, den der ObjectAttributes-Parameter angibt, ist ungültig.
STATUS_LOG_CORRUPTION_DETECTED	BEI KTM ist beim Erstellen oder Öffnen der Protokolldatei ein Fehler aufgetreten.
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 mithilfe einer der folgenden drei Techniken identifizieren, welches Transaktions-Manager-Objekt geöffnet werden soll:

Verwenden Sie den Parameter LogFileName , um den Pfad und dateinamen eines Protokolldateidatenstroms anzugeben, der beim Erstellen des Transaktions-Manager-Objekts erstellt wurde.
Verwenden Sie den TmIdentity-Parameter , um die GUID anzugeben, die das Transaktions-Manager-Objekt identifiziert.
Verwenden Sie den ObjectAttributes-Parameter , um eine OBJECT_ATTRIBUTES-Struktur anzugeben, die den Objektnamen enthält, den der Aufrufer zuvor für die ZwCreateTransactionManager-Routine angegeben hat.

Sie müssen nur einen der oben aufgeführten Parameter (einen Objektnamen, einen Protokolldateinamen oder eine GUID) angeben und die anderen beiden Parameter auf NULL festlegen.

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

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

Weitere Informationen zur Verwendung von ZwOpenTransactionManager finden Sie unter Transaction Manager-Objekte und Erstellen einer Resource Manager.

NtOpenTransactionManager und ZwOpenTransactionManager 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 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 (include Wdm.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis