NtCreateEnlistment-Funktion (wdm.h)

Artikel
02/27/2024

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

Syntax

__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 Enlistment-Objekt empfängt, wenn der Aufruf von ZwCreateEnlistment erfolgreich ist.

[in] DesiredAccess

Ein ACCESS_MASK Wert, der den vom Aufrufer angeforderten Zugriff auf das Enlistment-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 Einlistungsobjekte angeben:

ACCESS_MASK Flag	Ermöglicht dem Aufrufer die
ENLISTMENT_QUERY_INFORMATION	Abfrageinformationen zur Einlistung (siehe ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Legen Sie Informationen für die Einlistung fest (siehe ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Wiederherstellen der Einlistung (siehe ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Führen Sie Vorgänge aus, die ein Ressourcen-Manager ausführt, der nicht überlegen ist (siehe ZwRollbackEnlistment, ZwPrePrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Führen Sie Vorgänge aus, die ein höherer Transaktions-Manager 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. Die folgende Tabelle zeigt, wie die Bitmaps bestimmten Zugriffsrechten entsprechen.

Generisches Zugriffsrecht	Satz 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 ZwOpenResourceManager abgerufen wurde.

[in] TransactionHandle

Ein Handle für ein Transaktionsobjekt , das durch einen vorherigen Aufruf von ZwCreateTransaction oder ZwOpenTransaction abgerufen wurde. KTM fügt diese Transaktion der Liste der Transaktionen hinzu, die der aufrufende Ressourcen-Manager 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 er das attribut OBJ_KERNEL_HANDLE festlegen, wenn initializeObjectAttributes aufgerufen wird. Dieser Parameter ist optional und kann NULL sein.

[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 mit TRANSACTION_NOTIFY_XXX-Werten , die in Ktmtypes.h definiert sind. Diese Maske 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

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-Parameters 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 in einem betriebsfähigen Zustand befinden.
STATUS_TRANSACTION_NOT_ACTIVE	Fehler bei der Einlistung, da die Transaktion, die vom TransactionHandle-Parameter angegeben wird, nicht aktiv ist.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Der Aufrufer hat versucht, sich als überlegener Transaktionsmanager zu registrieren, aber ein überlegener Transaktionsmanager 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

Ein Ressourcen-Manager ruft ZwCreateEnlistment auf, um sich in eine Transaktion ein eintragen zu können.

Ressourcenmanager, die nicht überlegen sind, müssen das flag ENLISTMENT_SUBORDINATE_RIGHTS in ihrer Zugriffsmaske enthalten.

Übergeordnete Transaktionsmanager müssen das ENLISTMENT_SUPERIOR_RIGHTS-Flag in ihre Zugriffsmasken aufnehmen. In der Regel enthält ein überlegener Transaktions-Manager Code, der ZwRollbackEnlistment aufruft. Daher muss er auch das flag ENLISTMENT_SUBORDINATE_RIGHTS enthalten.

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

Ihr Ressourcen-Manager kann den EnlistmentKey-Parameter verwenden, um jeder Enlist einen eindeutigen Wert zuzuweisen, z. B. einen Zeiger auf eine Datenstruktur, die Informationen zur Enlistment enthält. Wenn der Ressourcen-Manager beispielsweise das Handle des Einlistungsobjekts in der Struktur speichert, kann der Ressourcen-Manager die folgenden Schritte ausführen:

Rufen Sie ZwGetNotificationResourceManager auf, um eine Benachrichtigung abzurufen.
Rufen Sie den Wert des Auflistungsschlüssels aus der TRANSACTION_NOTIFICATION-Struktur ab.
Verwenden Sie den Auflistungsschlüssel, um das handle des gespeicherten Eintragsobjekts zu suchen.
Rufen Sie Routinen auf, die das Enlistment-Handle als Eingabe erfordern, z. B. ZwCommitComplete oder ZwRollbackComplete.

Weitere Informationen zu ZwateCreateEnlistment finden Sie unter Erstellen einer Resource Manager und Erstellen eines übergeordneten Transaktions-Managers.

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 (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs, PowerIrpDDis