TmCreateEnlistment, fonction (wdm.h)

Article
08/08/2023

La routine TmCreateEnlistment crée un objet d’inscription pour une transaction.

Syntaxe

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

Paramètres

[out] EnlistmentHandle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle pour le nouvel objet d’inscription si l’appel à TmCreateEnlistment réussit.

[in] PreviousMode

Mode processeur du processus qui utilisera le handle d’inscription pour accéder à l’objet d’inscription. Cette valeur doit être UserMode ou KernelMode.

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé de l’appelant à l’objet d’inscription. Pour plus d’informations sur ce paramètre, consultez la description du paramètre DesiredAccess pour ZwCreateEnlistment.

[in] ObjectAttributes

Pointeur vers une structure OBJECT_ATTRIBUTES qui spécifie le nom de l’objet et d’autres attributs. Utilisez la routine InitializeObjectAttributes pour initialiser cette structure. Si l’appelant n’est pas en cours d’exécution dans un contexte de thread système, il doit définir l’attribut OBJ_KERNEL_HANDLE lorsqu’il appelle InitializeObjectAttributes. Ce paramètre est facultatif et peut être NULL.

[in] ResourceManager

Pointeur vers un objet Resource Manager. Pour obtenir ce pointeur, votre composant doit appeler ObReferenceObjectByHandle et fournir le handle d’objet fourni par un appel précédent à ZwCreateResourceManager ou ZwOpenResourceManager .

[in] Transaction

Pointeur vers un objet de transaction. Pour obtenir ce pointeur, votre composant doit appeler ObReferenceObjectByHandle et fournir le handle d’objet fourni par un appel précédent à ZwCreateTransaction ou ZwOpenTransaction . KTM ajoute cette transaction à la liste des transactions que le gestionnaire de ressources appelant gère.

[in, optional] CreateOptions

Indicateurs d’option d’inscription. Le tableau suivant contient le seul indicateur disponible.

Indicateur CreateOptions	Signification
ENLISTMENT_SUPERIOR	L’appelant s’inscrit en tant que gestionnaire de transactions supérieur pour la transaction spécifiée.

Ce paramètre est facultatif et peut être égal à zéro.

[in] NotificationMask

OR au niveau du bit des valeurs TRANSACTION_NOTIFY_XXX définies dans Ktmtypes.h. Cette valeur de masque spécifie les types de notifications de transaction que KTM envoie à l’appelant.

[in, optional] EnlistmentKey

Pointeur vers les informations définies par l’appelant qui identifie de manière unique l’inscription. Le gestionnaire de ressources reçoit ce pointeur lorsqu’il appelle ZwGetNotificationResourceManager ou lorsque KTM appelle la routine de rappel ResourceManagerNotification . Le gestionnaire de ressources peut conserver un nombre de références pour cette clé en appelant TmReferenceEnlistmentKey et TmDereferenceEnlistmentKey. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

TmCreateEnlistment retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette routine peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	La valeur du paramètre CreateOptions ou NotificationMask n’est pas valide, ou KTM n’a pas trouvé la transaction spécifiée par le paramètre Transaction .
STATUS_INSUFFICIENT_RESOURCES	Une allocation de mémoire a échoué.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	L’inscription a échoué, car KTM ou le gestionnaire de ressources n’est pas dans un état opérationnel.
STATUS_TRANSACTION_NOT_ACTIVE	L’inscription a échoué, car la transaction spécifiée par le paramètre Transaction n’est pas active.
STATUS_TRANSACTION_SUPERIOR_EXISTS	L’appelant a essayé de s’inscrire en tant que gestionnaire de transactions supérieur , mais il existe déjà une inscription supérieure.
STATUS_TM_VOLATILE	L’appelant tente de s’inscrire en tant que gestionnaire de transactions supérieur, mais l’objet resource manager de l’appelant est volatile , tandis que l’objet gestionnaire de transactions associé n’est pas volatile.
STATUS_ACCESS_DENIED	La valeur du paramètre DesiredAccess n’est pas valide.

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

La routine TmCreateEnlistment est une version basée sur des pointeurs de la routine ZwCreateEnlistment .

Pour plus d’informations sur l’utilisation des routines TmXxx de KTM au lieu des routines ZwXxx , consultez Utilisation des routines TmXxx.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et versions ultérieures du système d’exploitation.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL