Partager via


TmCreateEnlistment, fonction (wdm.h)

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

Voir aussi

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObReferenceObjectByHandle

ResourceManagerNotification

ZwCreateEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenResourceManager

ZwOpenTransaction