Función ZwCreateEnlistment (wdm.h)

Artículo
02/29/2024

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

Sintaxis

NTSYSCALLAPI NTSTATUS ZwCreateEnlistment(
  [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 para el nuevo objeto de inscripción si la llamada a ZwCreateEnlistment se realiza correctamente.

[in] DesiredAccess

Valor de 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 derecho de acceso para los objetos de inscripción:

marca de ACCESS_MASK	Permite al autor de la llamada a
ENLISTMENT_QUERY_INFORMATION	Consulte información sobre la inscripción (vea ZwQueryInformationEnlistment).
ENLISTMENT_SET_INFORMATION	Establezca información para la inscripción (vea ZwSetInformationEnlistment).
ENLISTMENT_RECOVER	Recuperar la inscripción (consulte ZwRecoverEnlistment).
ENLISTMENT_SUBORDINATE_RIGHTS	Realice operaciones que realice un administrador de recursos que no sea superior (consulte ZwRollbackEnlistment, ZwPrePrepareComplete, 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 STANDARD_RIGHTS_XXX 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 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] 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 valores TRANSACTION_NOTIFY_XXX que se definen 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 puede ser 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 valor del parámetro CreateOptions o NotificationMask 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 un estado operativo.
STATUS_TRANSACTION_NOT_ACTIVE	Error en la inscripción porque la transacción que especifica el parámetro TransactionHandle no está activa.
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 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

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.

Los 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 del 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.
Rutinas de llamada que requieren 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 versiones NtXxx y ZwXxx de una rutina de Windows Native System Services 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 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, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)