Fonction NtCreateTransaction (wdm.h)

La routine ZwCreateTransaction crée un objet transaction.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

Paramètres

[out] TransactionHandle

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

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé de l’appelant à l’objet transaction. 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 suivants pour les objets transactionnels.

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.

En règle générale, un gestionnaire de ressources spécifie TRANSACTION_RESOURCE_MANAGER_RIGHTS.

La valeur DesiredAccess ne peut pas être égale à zéro.

[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] Uow

Pointeur vers un GUID que KTM utilise comme identificateur d’unité de travail (UOW) du nouvel objet transactionnel. Ce paramètre est facultatif et peut être NULL. Si ce paramètre a la valeur NULL, KTM génère un GUID et l’affecte à l’objet transaction. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] TmHandle

Handle d’un objet de gestionnaire de transactions obtenu par un appel précédent à ZwCreateTransactionManager ou ZwOpenTransactionManager. KTM affecte le nouvel objet transaction à l’objet gestionnaire de transactions spécifié. Si ce paramètre a la valeur NULL, KTM affecte le nouvel objet transaction à un gestionnaire de transactions ultérieurement, lorsqu’un gestionnaire de ressources crée une inscription pour la transaction.

[in, optional] CreateOptions

Indicateurs de création d’objets facultatifs. Le tableau suivant contient les indicateurs disponibles, qui sont définis dans Ktmtypes.h.

[in, optional] IsolationLevel

Réservé à un usage ultérieur. Les appelants doivent définir ce paramètre sur zéro.

[in, optional] IsolationFlags

Réservé pour un usage futur. Les appelants doivent définir ce paramètre sur zéro.

[in, optional] Timeout

Pointeur vers une valeur de délai d’attente. Si la transaction n’a pas été validée à l’heure spécifiée par ce paramètre, KTM annule la transaction. La valeur du délai d’attente est exprimée en unités de temps système (intervalles de 100 nanosecondes) et peut spécifier une heure absolue ou une heure relative. Si la valeur pointée par Délai d’expiration est négative, le délai d’expiration est relatif à l’heure système actuelle. Sinon, le délai d’expiration est absolu. Ce pointeur est facultatif et peut être NULL si vous ne souhaitez pas que la transaction ait une valeur de délai d’attente. Si délai d’expiration = NULL ou *Délai d’expiration = 0, la transaction n’expire jamais. (Vous pouvez également utiliser ZwSetInformationTransaction pour définir une valeur de délai d’attente.)

[in, optional] Description

Pointeur vers une structure de UNICODE_STRING fournie par l’appelant qui contient une chaîne terminée par NULL. La chaîne fournit une description de la transaction. KTM stocke une copie de la chaîne et inclut la chaîne dans les messages qu’il écrit dans le flux de journal. La longueur de chaîne maximale est MAX_TRANSACTION_DESCRIPTION_LENGTH. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

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

La routine peut retourner d’autres valeurs NTSTATUS.

Remarques

L’appelant peut utiliser le paramètre Uow pour spécifier un identificateur UOW pour l’objet transaction. Si l’appelant ne spécifie pas d’identificateur UOW, KTM génère un GUID et l’affecte à l’objet transaction. L’appelant peut obtenir ultérieurement ce GUID en appelant ZwQueryInformationTransaction.

En règle générale, vous devez laisser KTM générer un GUID pour l’objet de transaction, sauf si votre composant communique avec un autre composant TPS qui a déjà généré un identificateur UOW pour la transaction.

Pour fermer le handle de transaction, le composant appelé ZwCreateTransaction doit appeler ZwClose. Si le dernier handle de transaction se ferme avant qu’un composant n’appelle ZwCommitTransaction pour la transaction, KTM annule la transaction.

Pour plus d’informations sur la façon dont les clients de transaction doivent utiliser ZwCreateTransaction, consultez Création d’un client transactionnel.

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

Voir aussi

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

UNICODE_STRING

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

ZwClose

ZwCommitTransaction

ZwCreateEnlistment

ZwCreateTransactionManager

ZwOpenTransaction

ZwOpenTransactionManager

ZwQueryInformationTransaction

ZwRollbackTransaction

ZwSetInformationTransaction