Fonction NtCreateTransaction (wdm.h)

Article
02/27/2024

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.

Masque d’accès	Permet à l’appelant de
TRANSACTION_COMMIT	Validez la transaction (voir ZwCommitTransaction).
TRANSACTION_ENLIST	Créez une inscription pour la transaction (consultez ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Ne pas utiliser.
TRANSACTION_QUERY_INFORMATION	Obtenez des informations sur la transaction (consultez ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Restaurer la transaction (voir ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Définissez des informations pour la transaction (consultez ZwSetInformationTransaction).

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.

Bitmap des droits	Ensemble de droits d’accès spécifiques
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION et SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT et SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK et SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE et TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE et SYNCHRONIZE

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.

Indicateur d’option	Signification
TRANSACTION_DO_NOT_PROMOTE	Réservé à un usage ultérieur.

[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 :

Code de retour	Description
STATUS_INVALID_PARAMETER	Le paramètre CreateOptions contient un indicateur non valide, le paramètre DesiredAccess est égal à zéro ou la chaîne du paramètre Description est trop longue.
STATUS_INSUFFICIENT_RESOURCES	KTM n’a pas pu allouer de ressources système (généralement de la mémoire).
STATUS_INVALID_ACL	Un descripteur de sécurité contient une liste de contrôle d’accès (ACL) non valide.
STATUS_INVALID_SID	Un descripteur de sécurité contient un identificateur de sécurité (SID) non valide.
STATUS_OBJECT_NAME_EXISTS	Le nom d’objet spécifié par le paramètre ObjectAttributes existe déjà.
STATUS_OBJECT_NAME_INVALID	Le nom de l’objet spécifié par le paramètre ObjectAttributes n’est pas valide.
STATUS_ACCESS_DENIED	La valeur du paramètre DesiredAccess n’est pas valide.

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

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, PowerIrpDDis