NtCreateEnlistment-Funktion (wdm.h)

Artikel
07.02.2025

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

Syntax

C++

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [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 Listenobjekt empfängt, wenn der Aufruf von ZwCreateEnlist ment erfolgreich ist.

[in] DesiredAccess

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

ACCESS_MASK-Kennzeichnung	Ermöglicht es dem Aufrufer,
ENLISTMENT_QUERY_INFORMATION	Abfrageinformationen zur Liste (siehe ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Set information for the enlistment (see ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Wiederherstellen der Auflistung (siehe ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Ausführen von Vorgängen, die ein ressourcenmanager, der nicht überlegen ist (siehe ZwRollbackEnlistment, ZwPrePrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Ausführen von Vorgängen, die ein überlegener Transaktionsmanager ausführen muss (siehe ZwPrepareEnlistment, ZwPrePrepareEnlistment, ZwCommitEnlistment).

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.

Generisches Zugriffsrecht	Festlegen bestimmter Zugriffsrechte
ENLISTMENT_GENERIC_READ	STANDARD_RIGHTS_READ und ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS und ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS und ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE und ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Ein Handle für das Ressourcen-Manager-Objekt des Aufrufers, das durch einen vorherigen Aufruf von ZwCreateResourceManager oder ZwOpenResourceManagerabgerufen wurde.

[in] TransactionHandle

Ein Handle für ein Transaktionsobjekt, das durch einen vorherigen Aufruf von ZwCreateTransaction oder ZwOpenTransactionabgerufen wurde. KTM fügt diese Transaktion zur Liste der Transaktionen hinzu, die der aufrufende Ressourcenmanager verarbeitet.

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

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

Flag "CreateOptions"	Bedeutung
ENLISTMENT_SUPERIOR	Der Aufrufer wird als überlegener Transaktionsmanager für die angegebene Transaktion in die Liste gesetzt.

Dieser Parameter ist optional und kann null sein.

[in] NotificationMask

Ein bitweises ODER von TRANSACTION_NOTIFY_XXX--Werten, die in Ktmtypes.h definiert sind. Diese Maske gibt die Arten von Transaktionsbenachrichtigungen an, die KTM an den Anrufer sendet.

[in, optional] EnlistmentKey

Ein Zeiger zum Aufrufen definierter Informationen, die die Liste eindeutig identifiziert. 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 TmReferenceEnlistmentKey und TmDereferenceEnlistmentKeyaufgerufen wird. Dieser Parameter ist optional und kann NULL-werden.

Rückgabewert

ZwCreateEnlistment 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_HANDLE	Ein Objekthandle ist ungültig.
STATUS_INVALID_PARAMETER	Der Wert des CreateOptions oder NotificationMask Parameter ist ungültig, oder KTM konnte die Transaktion, die der TransactionHandle 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 im Betriebszustand befindet.
STATUS_TRANSACTION_NOT_ACTIVE	Fehler bei der Auflistung, da die Transaktion, die vom TransactionHandle Parameter angegeben wird, nicht aktiv ist.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Der Anrufer hat versucht, sich als überlegener Transaktionsmanager zu registrieren, aber es ist bereits ein überlegener Transaktions manager vorhanden.
STATUS_TM_VOLATILE	Der Aufrufer versucht, sich als überlegener Transaktionsmanager zu registrieren, aber das Ressourcen-Manager-Objekt des Aufrufers ist veränderlich, während das zugeordnete Transaktions-Manager-Objekt nicht veränderlich ist.
STATUS_ACCESS_DENIED	Der Wert des parameters DesiredAccess ist ungültig.

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

Bemerkungen

Ein Ressourcenmanager ruft ZwCreateEnlistment- auf, um eine Transaktion auflisten zu können.

Ressourcenmanager, die nicht überlegen sind, müssen das ENLISTMENT_SUBORDINATE_RIGHTS Flag in ihre Zugriffsmaske aufnehmen.

Superior Transaktionsmanager müssen die ENLISTMENT_SUPERIOR_RIGHTS Kennzeichnung in ihre Zugriffsmasken aufnehmen. In der Regel enthält ein überlegener Transaktionsmanager Code, der ZwRollbackEnlistmentaufruft, sodass er auch das ENLISTMENT_SUBORDINATE_RIGHTS Flag enthalten muss.

Ein Ressourcenmanager, der ZwCreateEnlistment aufruft muss schließlich ZwClose- aufrufen, um das Objekthandle zu schließen.

Der Ressourcenmanager kann den parameter EnlistmentKey verwenden, um jedem Enlistment einen eindeutigen Wert zuzuweisen, z. B. einen Zeiger auf eine Datenstruktur, die Informationen zur Enlistment enthält. Wenn der Ressourcenmanager beispielsweise das Handle des Enlistment-Objekts in der Struktur speichert, kann der Ressourcen-Manager folgende Aktionen ausführen:

Rufen Sie ZwGetNotificationResourceManager- auf, um eine Benachrichtigung abzurufen.
Rufen Sie den Wert des Listenschlüssels aus der TRANSACTION_NOTIFICATION-Struktur ab.
Verwenden Sie den Listenschlüssel, um das gespeicherte Enlistment-Objekthandle zu finden.
Aufrufen von Routinen, die das Listenhandle als Eingabe erfordern, z. B. ZwCommitComplete- oder ZwRollbackComplete-.

Weitere Informationen zu ZwCreateEnlistmentfinden Sie unter Creating a Resource Manager and Creating a Superior Transaction Manager.

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