Fonction ZwCreateEnlistment (wdm.h)

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

Syntaxe

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

Paramètres

[out] EnlistmentHandle

Pointeur vers une variable allouée à l’appelant qui reçoit un handle vers 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érer l’inscription (voir ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS Effectuez des opérations qu’effectue un gestionnaire de ressources qui n’est pas supérieur (voir ZwRollbackEnlistment, ZwPrePrepareComplete, ZwPrepareComplete, 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 de la table précédente 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 de 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 quand 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 un gestionnaire de transactions supérieur existe déjà.
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 alors 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 :

  1. Appelez ZwGetNotificationResourceManager pour obtenir une notification.
  2. Obtenez la valeur de la clé d’inscription à partir de la structure TRANSACTION_NOTIFICATION .
  3. Utilisez la clé d’inscription pour rechercher le handle de l’objet d’inscription stocké.
  4. 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 à partir 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 Utilisation des versions Nt et Zw des routines des services système natifs.

Configuration requise

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

Voir aussi

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

TRANSACTION_NOTIFICATION

Utilisation des versions Nt et Zw des routines natives des services système natifs

ZwClose

ZwCommitComplete

ZwCommitEnlistment

ZwCreateResourceManager

ZwCreateTransaction

ZwGetNotificationResourceManager

ZwOpenEnlistment

ZwOpenResourceManager

ZwOpenTransaction

ZwPrePrepareComplete

ZwPrePrepareEnlistment

ZwPrepareComplete

ZwPrepareEnlistment

ZwQueryInformationEnlistment

ZwReadOnlyEnlistment

ZwRecoverEnlistment

ZwRollbackComplete

ZwRollbackEnlistment

ZwSetInformationEnlistment

ZwSinglePhaseReject