Fonction NtCreateTransactionManager (wdm.h)

Article
2025-02-07

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

Syntaxe

C++

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransactionManager(
  [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 vers le nouvel objet de gestionnaire de transactions .

[in] DesiredAccess

Valeur ACCESS_MASK qui spécifie l’accès demandé par l’appelant à l’objet gestionnaire de transactions. Outre les 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 de ACCESS_MASK	Autorise l’appelant à
TRANSACTIONMANAGER_CREATE_RM	Créez un gestionnaire de ressources (consultez ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Obtenez des informations sur le gestionnaire de transactions (voir ZwQueryInformationTransactionManager et ZwEnumerateTransactionObject). Également requis pour ZwOpenResourceManager, ZwCreateTransactionet 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 deXXX STANDARD_RIGHTS_ qui sont 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 fichiers journaux CLFS à associer à l’objet du gestionnaire de transactions. Ce paramètre doit être NULL si le paramètre CreateOptions est TRANSACTION_MANAGER_VOLATILE. Dans le cas contraire, ce paramètre doit être non-NULL. Pour plus d’informations, consultez la section Remarques suivante.

[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’utilise pas de fichier journal.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Pour une utilisation interne uniquement.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Pour une utilisation interne uniquement.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Pour une utilisation interne uniquement.
TRANSACTION_MANAGER_COMMIT_LOWEST	Pour une utilisation interne uniquement.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Pour une utilisation interne uniquement.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Pour une utilisation interne uniquement.

[in, optional] CommitStrength

Réservé pour une utilisation ultérieure. Ce paramètre doit être égal à zéro.

Valeur de retour

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

Retourner le code	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 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 non valide (ACL).
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_COLLISION	Le système d’exploitation a détecté un nom d’objet dupliqué. 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 fichiers journaux 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 une fois qu’il a appelé ZwCreateTransactionManager

Si votre composant TPS spécifie l’indicateur de 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 appeler ZwClose pour fermer le handle d’objet.

Pour plus d’informations sur l’utilisation de ZwCreateTransactionManager, consultez Création d’unResource 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 de 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Vista et versions ultérieures du système d’exploitation.
plateforme cible	Universel
d’en-tête	wdm.h (include Wdm.h, Ntifs.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
règles de conformité DDI	HwStorPortProhibitedDDIs, PowerIrpDDis