TmCreateEnlistment-Funktion (wdm.h)

Artikel
08/08/2023

Die TmCreateEnlistment-Routine erstellt ein neues Enlistment-Objekt für eine Transaktion.

Syntax

NTSTATUS TmCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           KPROCESSOR_MODE    PreviousMode,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           PRKRESOURCEMANAGER ResourceManager,
  [in]           PKTRANSACTION      Transaction,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

Parameter

[out] EnlistmentHandle

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die ein Handle für das neue Einlistungsobjekt empfängt, wenn der Aufruf von TmCreateEnlistment erfolgreich ist.

[in] PreviousMode

Der Prozessormodus des Prozesses, der das Enlistmenthandle verwendet, um auf das Enlistmentobjekt zuzugreifen. Dieser Wert muss entweder UserMode oder KernelMode sein.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den vom Aufrufer angeforderten Zugriff auf das Enlistment-Objekt angibt. Weitere Informationen zu diesem Parameter finden Sie in der Beschreibung des DesiredAccess-Parameters für ZwCreateEnlistment.

[in] 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] ResourceManager

Ein Zeiger auf ein Resource Manager-Objekt. Um diesen Zeiger abzurufen, muss Ihre Komponente ObReferenceObjectByHandle aufrufen und das Objekthandle bereitstellen, das ein vorheriger Aufruf von ZwCreateResourceManager oder ZwOpenResourceManager bereitgestellt hat.

[in] Transaction

Ein Zeiger auf ein Transaktionsobjekt. Um diesen Zeiger abzurufen, muss Ihre Komponente ObReferenceObjectByHandle aufrufen und das Objekthandle bereitstellen, das ein vorheriger Aufruf von ZwCreateTransaction oder ZwOpenTransaction bereitgestellt hat. KTM fügt diese Transaktion der Liste der Transaktionen hinzu, die der aufrufende Ressourcen-Manager verarbeitet.

[in, optional] CreateOptions

Enlistment-Optionsflags. Die folgende Tabelle enthält das einzige verfügbare Flag.

CreateOptions-Flag	Bedeutung
ENLISTMENT_SUPERIOR	Der Aufrufer wird als überlegener Transaktions-Manager für die angegebene Transaktion angezeigt.

Dieser Parameter ist optional und kann null sein.

[in] NotificationMask

Ein bitweiser OR der TRANSACTION_NOTIFY_XXX-Werte , die in Ktmtypes.h definiert sind. Dieser Maskenwert gibt die Arten von Transaktionsbenachrichtigungen an, die KTM an den Aufrufer sendet.

[in, optional] EnlistmentKey

Ein Zeiger auf vom Aufrufer definierte Informationen, die die Einlist eindeutig identifizieren. Der Ressourcen-Manager empfängt diesen Zeiger, wenn er ZwGetNotificationResourceManager aufruft oder wenn KTM die ResourceManagerNotification-Rückrufroutine aufruft. Der Ressourcen-Manager kann eine Referenzanzahl für diesen Schlüssel verwalten, indem er TmReferenceEnlistmentKey und TmDereferenceEnlistmentKey aufruft. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

TmCreateEnlistment 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 des CreateOptions - oder NotificationMask-Parameters ist ungültig, oder KTM konnte die Transaktion, die der Transaction-Parameter angibt, nicht finden.
STATUS_INSUFFICIENT_RESOURCES	Fehler bei der Speicherzuweisung.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	Fehler bei der Einlistung, da sich KTM oder der Ressourcenmanager nicht in einem betriebsfähigen Zustand befinden.
STATUS_TRANSACTION_NOT_ACTIVE	Fehler bei der Einlistung, da die Transaktion, die der Transaction-Parameter angibt, nicht aktiv ist.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Der Aufrufer hat versucht, sich als überlegener Transaktionsmanager zu registrieren, aber eine übergeordnete Einlistung ist bereits vorhanden.
STATUS_TM_VOLATILE	Der Aufrufer versucht, sich als überlegener Transaktions-Manager zu registrieren, aber das Ressourcen-Manager-Objekt des Aufrufers ist volatil , während das zugehörige Transaktions-Manager-Objekt nicht volatil ist.
STATUS_ACCESS_DENIED	Der Wert des DesiredAccess-Parameters ist ungültig.

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

Hinweise

Die TmCreateEnlistment-Routine ist eine zeigerbasierte Version der ZwCreateEnlistment-Routine .

Informationen zur Verwendung der TMXxx-Routinen von KTM anstelle von ZwXxx-Routinen finden Sie unter Verwenden von TmXxx-Routinen.

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