Función NtOpenTransactionManager (wdm.h)

Artículo
03/05/2024

La rutina ZwOpenTransactionManager obtiene un identificador para un objeto de administrador de transacciones existente.

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenTransactionManager(
  [out]          PHANDLE            TmHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] PUNICODE_STRING    LogFileName,
  [in, optional] LPGUID             TmIdentity,
  [in, optional] ULONG              OpenOptions
);

Parámetros

[out] TmHandle

Puntero a una variable asignada por el autor de la llamada que recibe un identificador al objeto del administrador de transacciones si ZwOpenTransactionManager devuelve STATUS_SUCCESS.

[in] DesiredAccess

Valor de ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto del administrador de transacciones. Para obtener información sobre cómo especificar este parámetro, vea el parámetro DesiredAccess de ZwCreateTransactionManager.

[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 la secuencia de archivos de registro que se creó cuando se creó el objeto del administrador de transacciones. Para obtener más información, vea el parámetro LogFileName de ZwCreateTransactionManager. Este parámetro es opcional y puede ser NULL.

[in, optional] TmIdentity

Puntero a un GUID que identifica el objeto del administrador de transacciones. Este parámetro es opcional y puede ser NULL.

[in, optional] OpenOptions

Este parámetro no se usa y debe ser cero.

Valor devuelto

ZwOpenTransactionManager 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_OBJECT_NAME_INVALID	El nombre de objeto que especifica el parámetro ObjectAttributes no es válido.
STATUS_LOG_CORRUPTION_DETECTED	KTM encontró un error al crear o abrir el archivo de registro.
STATUS_ACCESS_DENIED	El valor del parámetro DesiredAccess no es válido.

La rutina podría devolver otros valores NTSTATUS.

Comentarios

El autor de la llamada puede identificar qué objeto de administrador de transacciones se va a abrir mediante una de las tres técnicas siguientes:

Use el parámetro LogFileName para especificar la ruta de acceso y el nombre de archivo de un flujo de archivo de registro que se creó cuando se creó el objeto del administrador de transacciones.
Use el parámetro TmIdentity para especificar el GUID que identifica el objeto del administrador de transacciones.
Utilice el parámetro ObjectAttributes para proporcionar una estructura de OBJECT_ATTRIBUTES que contenga el nombre de objeto que el autor de la llamada especificó anteriormente en la rutina ZwCreateTransactionManager .

Debe especificar solo uno de los parámetros enumerados anteriormente (un nombre de objeto, un nombre de archivo de registro o un GUID) y establecer los otros dos parámetros en NULL.

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

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

Para obtener más información sobre cómo usar ZwOpenTransactionManager, vea Objetos del Administrador de transacciones y Creación de un Resource Manager.

NtOpenTransactionManager y ZwOpenTransactionManager son dos versiones de la misma rutina de Windows Native System Services.

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