Funzione ZwCreateEnlistment (wdm.h)

Articolo
08/08/2023

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

Sintassi

NTSYSCALLAPI NTSTATUS ZwCreateEnlistment(
  [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 al nuovo oggetto di inserimento se la chiamata a ZwCreateEnlistment ha esito positivo.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto enlistment. 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 inserimento:

flag ACCESS_MASK	Consente al chiamante di
ENLISTMENT_QUERY_INFORMATION	Eseguire query sulle informazioni sull'inserimento (vedere ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Impostare le informazioni per l'inserimento (vedere ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Recuperare l'inserimento (vedere ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Eseguire operazioni che un gestore risorse non superiore esegue (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 insieme a flag aggiuntivi dalla tabella precedente. Nella tabella seguente viene illustrato 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 a un oggetto transazione ottenuto da una chiamata precedente a ZwCreateTransaction o ZwOpenTransaction. KTM aggiunge questa transazione all'elenco delle 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. Usare 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 inserimento. La tabella seguente contiene l'unico flag disponibile.

Flag CreateOptions	Significato
ENLISTMENT_SUPERIOR	Il chiamante esegue l'inserimento 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 chiamante KTM.

[in, optional] EnlistmentKey

Puntatore a informazioni definite dal chiamante che identificano in modo univoco l'inserimento. Gestione risorse riceve questo puntatore quando chiama ZwGetNotificationResourceManager o quando KTM chiama la routine di callback ResourceManagerNotification . Gestione risorse può mantenere un numero di 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 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	Un'allocazione di memoria non riuscita.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	L'inserimento non è riuscito perché KTM o il gestore risorse non è in uno stato operativo.
STATUS_TRANSACTION_NOT_ACTIVE	L'inserimento non è riuscito perché la transazione specificata dal parametro TransactionHandle non è attiva.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Il chiamante ha provato a registrare come gestore transazioni superiore, ma esiste già un gestore transazioni superiore .
STATUS_TM_VOLATILE	Il chiamante sta tentando di registrare come gestore transazioni superiore, ma l'oggetto resource manager del chiamante è volatile mentre l'oggetto gestione transazioni associato non è volatile .
STATUS_ACCESS_DENIED	Il valore del parametro DesiredAccess non è valido.

La routine potrebbe restituire altri valori NTSTATUS.

Commenti

Un resource manager chiama ZwCreateEnlistment per l'inserimento in una transazione.

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

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

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

Gestione risorse può usare il parametro EnlistmentKey per assegnare un valore univoco a ogni inserimento, ad esempio un puntatore a una struttura di dati che contiene informazioni sull'inserimento. Ad esempio, se gestione risorse archivia l'handle dell'oggetto di inserimento nella struttura, gestione risorse può eseguire le operazioni seguenti:

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

Per altre informazioni su ZwCreateEnlistment, vedere Creazione di un Resource Manager e Creazione di un gestore transazioni superiore.

Per le chiamate dai driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Windows Native System Services 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 Uso di nt e zw versioni delle routine di Servizi di sistema nativo.

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(storport), PowerIrpDDis(wdm)