Funzione TmCreateEnlistment (wdm.h)

Articolo
02/29/2024

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

Sintassi

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

Parametri

[out] EnlistmentHandle

Puntatore a una variabile allocata dal chiamante che riceve un handle al nuovo oggetto di inserimento se la chiamata a TmCreateEnlistment ha esito positivo.

[in] PreviousMode

Modalità processore del processo che userà l'handle di inserimento per accedere all'oggetto enlistment. Questo valore deve essere UserMode o KernelMode.

[in] DesiredAccess

Valore ACCESS_MASK che specifica l'accesso richiesto dal chiamante all'oggetto enlistment. Per altre informazioni su questo parametro, vedere la descrizione del parametro DesiredAccess per ZwCreateEnlistment.

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

Puntatore a un oggetto resource manager. Per ottenere questo puntatore, il componente deve chiamare ObReferenceObjectByHandle e specificare l'handle dell'oggetto che una chiamata precedente a ZwCreateResourceManager o ZwOpenResourceManager fornita.

[in] Transaction

Puntatore a un oggetto transazione. Per ottenere questo puntatore, il componente deve chiamare ObReferenceObjectByHandle e specificare l'handle dell'oggetto che una chiamata precedente a ZwCreateTransaction o ZwOpenTransaction fornita. KTM aggiunge questa transazione all'elenco delle transazioni che il gestore risorse chiamante gestisce.

[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 dei valori TRANSACTION_NOTIFY_XXX definiti in Ktmtypes.h. Questo valore di 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

TmCreateEnlistment 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_PARAMETER	Il valore del parametro CreateOptions o NotificationMask non è valido oppure KTM non è riuscito a trovare la transazione specificata dal parametro Transaction .
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 Transaction non è attiva.
STATUS_TRANSACTION_SUPERIOR_EXISTS	Il chiamante ha tentato di registrare come gestore transazioni superiore , ma esiste già un elenco 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

La routine TmCreateEnlistment è una versione basata su puntatore della routine ZwCreateEnlistment .

Per informazioni su quando usare le routine TmXxx di KTM anziché le routine Zw Xxx, vedere Uso di routine TmXxx.

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