Función NtCreateTransactionManager (wdm.h)

Artículo
02/29/2024

La rutina ZwCreateTransactionManager crea un nuevo objeto de administrador de transacciones.

Sintaxis

__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
);

Parámetros

[out] TmHandle

Puntero a una variable asignada por el autor de la llamada que recibe un identificador para el nuevo objeto del administrador de transacciones.

[in] DesiredAccess

Valor de ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto del administrador de transacciones. Además de los derechos de acceso definidos para todo tipo de objetos (vea ACCESS_MASK), el autor de la llamada puede especificar cualquiera de las siguientes marcas de derecho de acceso para los objetos del administrador de transacciones.

marca de ACCESS_MASK	Permite al autor de la llamada
TRANSACTIONMANAGER_CREATE_RM	Cree un administrador de recursos (consulte ZwCreateResourceManager).
TRANSACTIONMANAGER_QUERY_INFORMATION	Obtenga información sobre el administrador de transacciones (vea ZwQueryInformationTransactionManager y ZwEnumerateTransactionObject). También es necesario para ZwOpenResourceManager, ZwCreateTransaction y ZwOpenTransaction).
TRANSACTIONMANAGER_RECOVER	Recupere el administrador de transacciones (consulte ZwRecoverTransactionManager y ZwRollforwardTransactionManager).
TRANSACTIONMANAGER_RENAME	No se usa.
TRANSACTIONMANAGER_SET_INFORMATION	No se usa.

Como alternativa, puede especificar uno o varios de los siguientes ACCESS_MASK mapas de bits. Estos mapas de bits combinan las marcas de la tabla anterior con las marcas STANDARD_RIGHTS_XXX que se describen en la página de referencia de ACCESS_MASK . También puede combinar estos mapas de bits con marcas adicionales de la tabla anterior. En la tabla siguiente se muestra cómo se corresponden los mapas de bits con derechos de acceso específicos.

Mapa de bits de derechos	Conjunto de derechos de acceso específicos
TRANSACTIONMANAGER_GENERIC_READ	STANDARD_RIGHTS_READ y TRANSACTIONMANAGER_QUERY_INFORMATION
TRANSACTIONMANAGER_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTIONMANAGER_SET_INFORMATION, TRANSACTIONMANAGER_RECOVER, TRANSACTIONMANAGER_RENAME y TRANSACTIONMANAGER_CREATE_RM
TRANSACTIONMANAGER_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE
TRANSACTIONMANAGER_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTIONMANAGER_GENERIC_READ, TRANSACTIONMANAGER_GENERIC_WRITE y TRANSACTIONMANAGER_GENERIC_EXECUTE

[in, optional] ObjectAttributes

Puntero a una estructura de OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use la rutina InitializeObjectAttributes para inicializar esta estructura. Si el autor de la llamada no se ejecuta en un contexto de subproceso del sistema, debe establecer el atributo OBJ_KERNEL_HANDLE cuando llama a InitializeObjectAttributes. Este parámetro es opcional y puede ser NULL.

[in, optional] LogFileName

Puntero a una estructura de UNICODE_STRING que contiene la ruta de acceso y el nombre de archivo de un flujo de archivo de registro CLFS que se va a asociar al objeto del administrador de transacciones. Este parámetro debe ser NULL si el parámetro CreateOptions es TRANSACTION_MANAGER_VOLATILE. De lo contrario, este parámetro debe ser distinto de NULL. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in, optional] CreateOptions

Marcas de creación de objetos opcionales. La tabla siguiente contiene las marcas disponibles, que se definen en Ktmtypes.h.

Marca de opción	Significado
TRANSACTION_MANAGER_VOLATILE	El objeto del administrador de transacciones será volátil. Por lo tanto, no usará un archivo de registro.
TRANSACTION_MANAGER_COMMIT_DEFAULT	Solo para uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_VOLUME	Solo para uso interno.
TRANSACTION_MANAGER_COMMIT_SYSTEM_HIVES	Solo para uso interno.
TRANSACTION_MANAGER_COMMIT_LOWEST	Solo para uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_RECOVERY	Solo para uso interno.
TRANSACTION_MANAGER_CORRUPT_FOR_PROGRESS	Solo para uso interno.

[in, optional] CommitStrength

Reservado para uso futuro. Este parámetro debe ser cero.

Valor devuelto

ZwCreateTransactionManager devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, esta rutina podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El valor de un parámetro de entrada no es válido.
STATUS_INSUFFICIENT_RESOURCES	KTM no pudo asignar recursos del sistema (normalmente memoria).
STATUS_LOG_CORRUPTION_DETECTED	KTM encontró un error al crear o abrir el archivo de registro.
STATUS_INVALID_ACL	Un descriptor de seguridad contiene una lista de control de acceso (ACL) no válida.
STATUS_INVALID_SID	Un descriptor de seguridad contiene un identificador de seguridad (SID) no válido.
STATUS_OBJECT_NAME_EXISTS	El nombre de objeto que el parámetro ObjectAttributes especifica ya existe.
STATUS_OBJECT_NAME_COLLISION	El sistema operativo detectó un nombre de objeto duplicado. El error podría indicar que la secuencia de registro ya se está usando.
STATUS_OBJECT_NAME_INVALID	El nombre de objeto que especifica el parámetro ObjectAttributes no es válido.
STATUS_ACCESS_DENIED	El valor del parámetro DesiredAccess no es válido.

La rutina podría devolver otros valores NTSTATUS.

Comentarios

Si la secuencia de archivos de registro que especifica el parámetro LogFileName no existe, KTM llama a CLFS para crear la secuencia. Si la secuencia ya existe, KTM llama a CLFS para abrir la secuencia.

El componente tpS debe llamar a ZwRecoverTransactionManager después de llamar a ZwCreateTransactionManager.

Si el componente tpS especifica la marca TRANSACTION_MANAGER_VOLATILE en el parámetro CreateOptions , todos los administradores de recursos asociados al objeto del administrador de transacciones deben especificar la marca RESOURCE_MANAGER_VOLATILE cuando llaman a ZwCreateResourceManager.

Un componente TPS que llama a ZwCreateTransactionManager debe llamar finalmente a ZwClose para cerrar el identificador del objeto.

Para obtener más información sobre cómo usar ZwCreateTransactionManager, vea Creating a Resource Manager.

NtCreateTransactionManager y ZwCreateTransactionManager son dos versiones de la misma rutina de Servicios del sistema nativo de Windows.

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows Vista y versiones posteriores del sistema operativo.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis