Fonction NtCreateEnlistment (wdm.h)

Article
02/29/2024

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

Syntaxe

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

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 à ZwCreateEnlistment réussit.

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé de l’appelant à l’objet d’inscription. En plus des droits d’accès définis pour tous les types d’objets (voir ACCESS_MASK), l’appelant peut spécifier l’un des indicateurs de droit d’accès suivants pour les objets d’inscription :

indicateur ACCESS_MASK	Permet à l’appelant de
ENLISTMENT_QUERY_INFORMATION	Interroger des informations sur l’inscription (voir ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Définissez des informations pour l’inscription (consultez ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Récupérez l’inscription (voir ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Effectuer des opérations qu’un gestionnaire de ressources qui n’est pas supérieur effectue (voir ZwRollbackEnlistment, ZwPrePrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Effectuer des opérations qu’un gestionnaire de transactions supérieur doit effectuer (voir ZwPrepareEnlistment, ZwPrePrepareEnlistment, ZwCommitEnlistment).

Vous pouvez également spécifier une ou plusieurs des bitmaps ACCESS_MASK suivantes. Ces bitmaps combinent les indicateurs du tableau précédent avec les indicateurs STANDARD_RIGHTS_XXX décrits dans la page de référence ACCESS_MASK . Vous pouvez également combiner ces bitmaps avec des indicateurs supplémentaires du tableau précédent. Le tableau suivant montre comment les bitmaps correspondent à des droits d’accès spécifiques.

Droit d’accès générique	Ensemble de droits d’accès spécifiques
ENLISTMENT_GENERIC_READ	STANDARD_RIGHTS_READ et ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS et ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS et ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE et ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Handle de l’objet resource manager de l’appelant obtenu par un appel précédent à ZwCreateResourceManager ou ZwOpenResourceManager.

[in] TransactionHandle

Handle d’un objet transaction obtenu 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] 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, 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. Ce 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

ZwCreateEnlistment 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_HANDLE	Un handle d’objet n’est pas valide.
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 TransactionHandle .
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 TransactionHandle 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à un gestionnaire de transactions supérieur .
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

Un gestionnaire de ressources appelle ZwCreateEnlistment pour s’inscrire dans une transaction.

Les gestionnaires de ressources qui ne sont pas supérieurs doivent inclure l’indicateur ENLISTMENT_SUBORDINATE_RIGHTS dans leur masque d’accès.

Les gestionnaires de transactions supérieurs doivent inclure l’indicateur ENLISTMENT_SUPERIOR_RIGHTS dans leurs masques d’accès. En règle générale, un gestionnaire de transactions supérieur inclut du code qui appelle ZwRollbackEnlistment. Il doit donc également inclure l’indicateur ENLISTMENT_SUBORDINATE_RIGHTS.

Un gestionnaire de ressources qui appelle ZwCreateEnlistment doit finalement appeler ZwClose pour fermer le handle d’objet.

Votre gestionnaire de ressources peut utiliser le paramètre EnlistmentKey pour affecter une valeur unique à chaque inscription, par exemple un pointeur vers une structure de données qui contient des informations sur l’inscription. Par exemple, si le gestionnaire de ressources stocke le handle de l’objet d’inscription dans la structure, le gestionnaire de ressources peut effectuer les opérations suivantes :

Appelez ZwGetNotificationResourceManager pour obtenir une notification.
Obtenez la valeur de clé d’inscription à partir de la structure TRANSACTION_NOTIFICATION .
Utilisez la clé d’inscription pour rechercher le handle d’objet d’inscription stocké.
Appelez des routines qui nécessitent le handle d’inscription en tant qu’entrée, telles que ZwCommitComplete ou ZwRollbackComplete.

Pour plus d’informations sur ZwCreateEnlistment, consultez Création d’un Resource Manager et Création d’un gestionnaire de transactions supérieur.

Pour les appels provenant de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment dans la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

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
Règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis