ZwCreateTransactionManager, fonction (wdm.h)

Article
08/08/2023

La routine ZwCreateTransactionManager crée un objet de gestionnaire de transactions.

Syntaxe

NTSYSCALLAPI NTSTATUS ZwCreateTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              CommitStrength
);

Paramètres

[out] TmHandle

Pointeur vers une variable allouée par l’appelant qui reçoit un handle pour le nouvel objet gestionnaire de transactions.

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé de l’appelant à l’objet gestionnaire de transactions. 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 du gestionnaire de transactions.

indicateur ACCESS_MASK	Permet à l’appelant de
TRANSACTIONMANAGER_CREATE_RM	Créez un gestionnaire de ressources (consultez ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Obtenez des informations sur le gestionnaire de transactions (consultez ZwQueryInformationTransactionManager et ZwEnumerateTransactionObject). Également requis pour ZwOpenResourceManager, ZwCreateTransaction et ZwOpenTransaction.)
TRANSACTIONMANAGER_RECOVER	Récupérez le gestionnaire de transactions (consultez ZwRecoverTransactionManager et ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	Non utilisé.
TRANSACTIONMANAGER_SET_INFORMATION	Non utilisé.

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
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ et TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME et TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE et TRANSACTIONMANAGER_GENERIC_EXECUTE

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

Pointeur vers une structure UNICODE_STRING qui contient le chemin d’accès et le nom de fichier d’un flux de fichier journal CLFS à associer à l’objet gestionnaire de transactions. Ce paramètre doit être NULL si le paramètre CreateOptions est TRANSACTION_MANAGER_VOLATILE. Sinon, ce paramètre doit être non NULL. Pour plus d'informations, consultez la section Notes qui suit.

[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_MANAGER_VOLATILE	L’objet du gestionnaire de transactions sera volatile. Par conséquent, il n’utilisera pas de fichier journal.
TRANSACTION_MANAGER_COMMIT_DEFAULT	À usage interne uniquement.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	À usage interne uniquement.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	À usage interne uniquement.
TRANSACTION_MANAGER_COMMIT_LOWEST	À usage interne uniquement.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	À usage interne uniquement.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	À usage interne uniquement.

[in, optional] CommitStrength

Réservé pour un usage futur. Ce paramètre doit être égal à zéro.

Valeur retournée

ZwCreateTransactionManager 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	La valeur d’un paramètre d’entrée n’est pas valide.
STATUS_INSUFFICIENT_RESOURCES	KTM n’a pas pu allouer de ressources système (généralement de la mémoire).
STATUS_LOG_CORRUPTION_DETECTED	KTM a rencontré une erreur lors de la création ou de l’ouverture du fichier journal.
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_COLLISION	Le système d’exploitation a détecté un nom d’objet en double. L’erreur peut indiquer que le flux de journal est déjà utilisé.
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

Si le flux de fichier journal spécifié par le paramètre LogFileName n’existe pas, KTM appelle CLFS pour créer le flux. Si le flux existe déjà, KTM appelle CLFS pour ouvrir le flux.

Votre composant TPS doit appeler ZwRecoverTransactionManager après avoir appelé ZwCreateTransactionManager

Si votre composant TPS spécifie l’indicateur TRANSACTION_MANAGER_VOLATILE dans le paramètre CreateOptions , tous les gestionnaires de ressources associés à l’objet gestionnaire de transactions doivent spécifier l’indicateur RESOURCE_MANAGER_VOLATILE lorsqu’ils appellent ZwCreateResourceManager.

Un composant TPS qui appelle ZwCreateTransactionManager doit finalement appeler ZwClose pour fermer le handle d’objet.

Pour plus d’informations sur l’utilisation de ZwCreateTransactionManager, consultez Création d’un Resource Manager.

NtCreateTransactionManager et ZwCreateTransactionManager sont deux versions de la même routine Windows Native System Services.

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, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)