Funzione NtCreateEnlistment (wdm.h)

Articolo
08/08/2023

La routine ZwCreateEnlistment crea un nuovo oggetto di integrazione per una transazione.

Sintassi

__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
);

Parametri

[out] EnlistmentHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle per il nuovo oggetto di integrazione se la chiamata a ZwCreateEnlistment ha esito positivo.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto di integrazione. Oltre ai diritti di accesso definiti per tutti i tipi di oggetti (vedere ACCESS_MASK), il chiamante può specificare uno dei flag di accesso seguenti per gli oggetti di integrazione:

flag ACCESS_MASK	Consente al chiamante di
ENLISTMENT_QUERY_INFORMATION	Eseguire query sulle informazioni sull'integrazione (vedere ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Impostare le informazioni per l'integrazione (vedere ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Recuperare l'integrazione (vedere ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Eseguire operazioni eseguite da un gestore risorse non superiore (vedere ZwRollbackEnlistment, ZwPrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Eseguire operazioni che un gestore transazioni superiore deve eseguire (vedere ZwPrepareEnlistment, ZwPrepareEnlistment, ZwCommitEnlistment).

In alternativa, è possibile specificare una o più delle bitmap seguenti ACCESS_MASK . Queste bitmap combinano i flag della tabella precedente con i flag STANDARD_RIGHTS_XXX descritti nella pagina di riferimento ACCESS_MASK . È anche possibile combinare queste bitmap con flag aggiuntivi della tabella precedente. La tabella seguente illustra come le bitmap corrispondono a diritti di accesso specifici.

Diritto di accesso generico	Set di diritti di accesso specifici
ENLISTMENT_GENERIC_READ	STANDARD_RIGHTS_READ e ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS e ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS e ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE e ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Handle per l'oggetto resource manager del chiamante ottenuto da una chiamata precedente a ZwCreateResourceManager o ZwOpenResourceManager.

[in] TransactionHandle

Handle per un oggetto transazione ottenuto da una chiamata precedente a ZwCreateTransaction o ZwOpenTransaction. KTM aggiunge questa transazione all'elenco di transazioni che il gestore risorse chiamante gestisce.

[in, optional] ObjectAttributes

Puntatore a una struttura OBJECT_ATTRIBUTES che specifica il nome dell'oggetto e altri attributi. Utilizzare la routine InitializeObjectAttributes per inizializzare questa struttura. Se il chiamante non è in esecuzione in un contesto di thread di sistema, deve impostare l'attributo OBJ_KERNEL_HANDLE quando chiama InitializeObjectAttributes. Questo parametro è facoltativo e può essere NULL.

[in, optional] CreateOptions

Flag di opzione di integrazione. La tabella seguente contiene l'unico flag disponibile.

Flag CreateOptions	Significato
ENLISTMENT_SUPERIOR	Il chiamante si integra come gestore transazioni superiore per la transazione specificata.

Questo parametro è facoltativo e può essere zero.

[in] NotificationMask

OR bit per bit di valori TRANSACTION_NOTIFY_XXX definiti in Ktmtypes.h. Questa maschera specifica i tipi di notifiche delle transazioni inviate dal KTM al chiamante.

[in, optional] EnlistmentKey

Puntatore alle informazioni definite dal chiamante che identificano in modo univoco l'integrazione. Il gestore risorse riceve questo puntatore quando chiama ZwGetNotificationResourceManager o quando KTM chiama la routine di callback ResourceManagerNotification . Il gestore risorse può mantenere un conteggio dei riferimenti per questa chiave chiamando TmReferenceEnlistmentKey e TmDereferenceEnlistmentKey. Questo parametro è facoltativo e può essere NULL.

Valore restituito

ZwCreateEnlistment restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questa routine potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_HANDLE	Un handle di oggetto non è valido.
STATUS_INVALID_PARAMETER	Il valore del parametro CreateOptions o NotificationMask non è valido oppure KTM non è riuscito a trovare la transazione specificata dal parametro TransactionHandle .
STATUS_INSUFFICIENT_RESOURCES	Allocazione di memoria non riuscita.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	L'integrazione non è riuscita perché KTM o resource manager non è in uno stato operativo.
STATUS_TRANSACTION_NOT_ACTIVE	L'integrazione non è riuscita perché la transazione specificata dal parametro TransactionHandle non è attiva.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Il chiamante ha tentato di registrarsi come gestore transazioni superiore, ma esiste già un gestore transazioni superiore .
STATUS_TM_VOLATILE	Il chiamante sta tentando di eseguire la registrazione come gestore transazioni superiore, ma l'oggetto resource manager del chiamante è volatile mentre l'oggetto di gestione transazioni associato non è volatile .
STATUS_ACCESS_DENIED	Il valore del parametro DesiredAccess non è valido.

La routine potrebbe restituire altri valori NTSTATUS.

Commenti

Un gestore di risorse chiama ZwCreateEnlistment per l'integrazione in una transazione.

I gestori di risorse che non sono superiori devono includere il flag ENLISTMENT_SUBORDINATE_RIGHTS nella maschera di accesso.

I gestori delle transazioni superiori devono includere il flag ENLISTMENT_SUPERIOR_RIGHTS nelle maschere di accesso. In genere, un gestore transazioni superiore include codice che chiama ZwRollbackEnlistment, quindi deve includere anche il flag ENLISTMENT_SUBORDINATE_RIGHTS.

Un gestore di risorse che chiama ZwCreateEnlistment deve infine chiamare ZwClose per chiudere l'handle dell'oggetto.

Il gestore risorse può usare il parametro EnlistmentKey per assegnare un valore univoco a ogni integrazione, ad esempio un puntatore a una struttura di dati contenente informazioni sull'integrazione. Ad esempio, se resource manager archivia l'handle dell'oggetto di integrazione nella struttura, resource manager può eseguire le operazioni seguenti:

Chiamare ZwGetNotificationResourceManager per ottenere una notifica.
Ottenere il valore della chiave di integrazione dalla struttura TRANSACTION_NOTIFICATION .
Usare la chiave di integrazione per trovare l'handle dell'oggetto di integrazione archiviato.
Chiamare routine che richiedono l'handle di integrazione come input, ad esempio ZwCommitComplete o ZwRollbackComplete.

Per altre informazioni su ZwCreateEnlistment, vedere Creating a Resource Manager and Creating a Superior Transaction Manager.For more information about ZwCreateEnlistment, see Creating a Resource Manager and Creating a Superior Transaction Manager.

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive del sistema operativo.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs, PowerIrpDDis