Fonction ZwCreateTransaction (wdm.h)

Article
03/14/2023

La routine ZwCreateTransaction crée un objet transaction.

Syntaxe

NTSYSCALLAPI NTSTATUS ZwCreateTransaction(
  [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 vers le nouvel objet de transaction, si l’appel à ZwCreateTransaction réussit.

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé de l’appelant à l’objet de 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	Commitez la transaction (voir ZwCommitTransaction).
TRANSACTION_ENLIST	Créez une inscription pour la transaction (consultez ZwCreateEnlistment).
TRANSACTION_PROPAGATE	Ne pas utiliser.
TRANSACTION_QUERY_INFORMATION	Obtenir des informations sur la transaction (voir ZwQueryInformationTransaction).
TRANSACTION_ROLLBACK	Restaurer la transaction (voir ZwRollbackTransaction).
TRANSACTION_SET_INFORMATION	Définissez les informations pour la transaction (consultez ZwSetInformationTransaction).

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.

Bitmap de 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 de transaction. 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 de 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 de transaction à l’objet de gestionnaire de transactions spécifié. Si ce paramètre a la valeur NULL, KTM affecte le nouvel objet de 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 au moment spécifié par ce paramètre, KTM restaure la transaction. La valeur de 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, l’heure d’expiration est relative à l’heure système actuelle. Sinon, le délai d’expiration est absolu. Ce pointeur est facultatif et peut avoir la valeur 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 NULL terminée. 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 maximale de chaîne 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 de l’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 de transaction. Si l’appelant ne spécifie pas d’identificateur UOW, KTM génère un GUID et l’affecte à l’objet de 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 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 qui a appelé ZwCreateTransaction doit appeler ZwClose. Si le dernier handle de transaction se ferme avant qu’un composant 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 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(storport), PowerIrpDDis(wdm)