Función NtCreateEnlistment (wdm.h)

Artículo
08/08/2023

La rutina ZwCreateEnlistment crea una nueva objeto de inscripción para una transacción.

Sintaxis

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateEnlistment(
  [out]          PHANDLE            EnlistmentHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           HANDLE             ResourceManagerHandle,
  [in]           HANDLE             TransactionHandle,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [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 del nuevo objeto de inscripción si la llamada a ZwCreateEnlistment se realiza correctamente.

[in] DesiredAccess

Valor ACCESS_MASK que especifica el acceso solicitado del autor de la llamada al objeto de inscripción. Además de los derechos de acceso definidos para todos los tipos de objetos (vea ACCESS_MASK), el autor de la llamada puede especificar cualquiera de las siguientes marcas de acceso adecuadas para los objetos de inscripción:

marca de ACCESS_MASK	Permite al autor de la llamada
ENLISTMENT_QUERY_INFORMATION	Consulte información sobre la inscripción (consulte ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Establezca información para la inscripción (consulte ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Recupere la inscripción (consulte ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Realice operaciones que realice un administrador de recursos que no sea superior (consulte ZwRollbackEnlistment, ZwPrepareComplete, ZwPrepareComplete, ZwCommitComplete, ZwRollbackComplete, ZwSinglePhaseReject, ZwReadOnlyEnlistment).
ENLISTMENT_SUPERIOR_RIGHTS	Realice operaciones que un administrador de transacciones superior debe realizar (consulte ZwPrepareEnlistment, ZwPrepareEnlistment, ZwCommitEnlistment).

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 deXXX STANDARD_RIGHTS_ que se describen en la página de referencia de ACCESS_MASK. También puede combinar estos mapas de bits junto 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.

Derecho de acceso genérico	Conjunto de derechos de acceso específicos
ENLISTMENT_GENERIC_READ	STANDARD_RIGHTS_READ y ENLISTMENT_QUERY_INFORMATION
ENLISTMENT_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, ENLISTMENT_SET_INFORMATION, ENLISTMENT_RECOVER, ENLISTMENT_REFERENCE, ENLISTMENT_SUBORDINATE_RIGHTS y ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, ENLISTMENT_RECOVER, ENLISTMENT_SUBORDINATE_RIGHTS y ENLISTMENT_SUPERIOR_RIGHTS
ENLISTMENT_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, ENLISTMENT_GENERIC_READ, ENLISTMENT_GENERIC_WRITE y ENLISTMENT_GENERIC_EXECUTE

[in] ResourceManagerHandle

Identificador del objeto del administrador de recursos del autor de la llamada que obtuvo una llamada anterior a ZwCreateResourceManager o ZwOpenResourceManager.

[in] TransactionHandle

Identificador de un objeto de transacción obtenido por 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] ObjectAttributes

Puntero a una estructura OBJECT_ATTRIBUTES que especifica el nombre del objeto y otros atributos. Use la rutina de 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 se puede NULL.

[in, optional] CreateOptions

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

Marca de CreateOptions	Significado
ENLISTMENT_SUPERIOR	El autor de la llamada se inscribe como un 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 TRANSACTION_NOTIFY_XXX valores definidos en Ktmtypes.h. Esta 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 se puede NULL.

Valor devuelto

ZwCreateEnlistment 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_HANDLE	Un identificador de objeto no es válido.
STATUS_INVALID_PARAMETER	El CreateOptions o NotificationMask valor del parámetro no es válido o KTM no pudo encontrar la transacción que especifica el parámetro transactionHandle.
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 estado operativo.
STATUS_TRANSACTION_NOT_ACTIVE	Error en la inscripción porque la transacción que especifica el parámetro transactionHandle no está activo.
STATUS_TRANSACTION_SUPERIOR_EXISTS	El autor de la llamada intentó registrarse como administrador de transacciones superior, pero ya existe un administrador de transacciones 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 que 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 puede devolver otros valores NTSTATUS de .

Observaciones

Un administrador de recursos llama a zwCreateEnlistment para inscribirse en una transacción.

Los administradores de recursos que no son superiores deben incluir la marca ENLISTMENT_SUBORDINATE_RIGHTS en su máscara de acceso.

administradores de transacciones superiores deben incluir la marca ENLISTMENT_SUPERIOR_RIGHTS en sus máscaras de acceso. Normalmente, un administrador de transacciones superior incluye código que llama a ZwRollbackEnlistment, por lo que también debe incluir la marca ENLISTMENT_SUBORDINATE_RIGHTS.

Un administrador de recursos que llama a ZwCreateEnlistment debe llamar finalmente a ZwClose para cerrar el identificador de objeto.

El administrador de recursos puede usar el parámetro EnlistmentKey para asignar un valor único a cada inscripción, como un puntero a una estructura de datos que contiene información sobre la inscripción. Por ejemplo, si el administrador de recursos almacena el identificador del objeto de inscripción en la estructura, el administrador de recursos puede hacer lo siguiente:

Llame a ZwGetNotificationResourceManager para obtener una notificación.
Obtenga el valor de clave de inscripción de la estructura TRANSACTION_NOTIFICATION.
Use la clave de inscripción para buscar el identificador de objeto de inscripción almacenado.
Llame a rutinas que requieran el identificador de inscripción como entrada, como ZwCommitComplete o ZwRollbackComplete.

Para obtener más información sobre ZwCreateEnlistment, vea Creating a Resource Manager and Creating a Superior Transaction Manager.

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows pueden comportarse 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 de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible en Windows Vista y versiones posteriores del sistema operativo.
de la plataforma de destino de	Universal
encabezado de	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs, PowerIrpDDis