Función TmCreateEnlistment (wdm.h)

Artículo
08/08/2023

La rutina TmCreateEnlistment crea un nuevo objeto de inscripción para una transacción.

Sintaxis

NTSTATUS TmCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           KPROCESSOR_MODE    PreviousMode,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           PRKRESOURCEMANAGER ResourceManager,
  [in]           PKTRANSACTION      Transaction,
  [in, optional] ULONG              CreateOptions,
  [in]           NOTIFICATION_MASK  NotificationMask,
  [in, optional] PVOID              EnlistmentKey
);

Parámetros

[out] EnlistmentHandle

Puntero a una variable asignada por el autor de la llamada que recibe un identificador para el nuevo objeto de inscripción si la llamada a TmCreateEnlistment se realiza correctamente.

[in] PreviousMode

Modo de procesador del proceso que usará el identificador de inscripción para acceder al objeto de inscripción. Este valor debe ser UserMode o KernelMode.

[in] DesiredAccess

Valor de ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto de inscripción. Para obtener más información sobre este parámetro, vea la descripción del parámetro DesiredAccess para ZwCreateEnlistment.

[in] ObjectAttributes

Puntero a una estructura 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] ResourceManager

Puntero a un objeto de Resource Manager. Para obtener este puntero, el componente debe llamar a ObReferenceObjectByHandle y proporcionar el identificador del objeto que proporcionó una llamada anterior a ZwCreateResourceManager o ZwOpenResourceManager .

[in] Transaction

Puntero a un objeto de transacción. Para obtener este puntero, el componente debe llamar a ObReferenceObjectByHandle y proporcionar el identificador del objeto que proporcionó una llamada anterior a ZwCreateTransaction o ZwOpenTransaction . KTM agrega esta transacción a la lista de transacciones que controla el administrador de recursos que realiza la llamada.

[in, optional] CreateOptions

Marcas de opción de inscripción. La tabla siguiente contiene la única marca disponible.

Marca CreateOptions	Significado
ENLISTMENT_SUPERIOR	El autor de la llamada está inscribiendo como administrador de transacciones superior para la transacción especificada.

Este parámetro es opcional y puede ser cero.

[in] NotificationMask

Or bit a bit de los valores TRANSACTION_NOTIFY_XXX que se definen en Ktmtypes.h. Este valor de máscara especifica los tipos de notificaciones de transacción que KTM envía al autor de la llamada.

[in, optional] EnlistmentKey

Puntero a la información definida por el autor de la llamada que identifica de forma única la inscripción. El administrador de recursos recibe este puntero cuando llama a ZwGetNotificationResourceManager o cuando KTM llama a la rutina de devolución de llamada ResourceManagerNotification . El administrador de recursos puede mantener un recuento de referencias para esta clave llamando a TmReferenceEnlistmentKey y TmDereferenceEnlistmentKey. Este parámetro es opcional y puede ser NULL.

Valor devuelto

TmCreateEnlistment 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 del parámetro CreateOptions o NotificationMask no es válido o KTM no pudo encontrar la transacción que especifica el parámetro Transaction .
STATUS_INSUFFICIENT_RESOURCES	Error en la asignación de memoria.
STATUS_TRANSACTIONMANAGER_NOT_ONLINE	Error en la inscripción porque KTM o el administrador de recursos no están en un estado operativo.
STATUS_TRANSACTION_NOT_ACTIVE	Error en la inscripción porque la transacción que especifica el parámetro Transaction no está activa.
STATUS_TRANSACTION_SUPERIOR_EXISTS	El autor de la llamada intentó registrarse como administrador de transacciones superior , pero ya existe una inscripción superior.
STATUS_TM_VOLATILE	El autor de la llamada está intentando registrarse como administrador de transacciones superior, pero el objeto del administrador de recursos del autor de la llamada es volátil mientras el objeto del administrador de transacciones asociado no es volátil.
STATUS_ACCESS_DENIED	El valor del parámetro DesiredAccess no es válido.

La rutina podría devolver otros valores NTSTATUS.

Comentarios

La rutina TmCreateEnlistment es una versión basada en puntero de la rutina ZwCreateEnlistment .

Para obtener información sobre cuándo usar rutinas TmXxx de KTM en lugar de rutinas ZwXxx , vea Using TmXxx 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, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL