Función ZwCreateEnlistment (wdm.h)
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 |
---|---|
|
Un identificador de objeto no es válido. |
|
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 . |
|
Error en la asignación de memoria. |
|
Error en la inscripción porque KTM o el administrador de recursos no están en un estado operativo. |
|
Error en la inscripción porque la transacción que especifica el parámetro TransactionHandle no está activa. |
|
El autor de la llamada intentó registrarse como administrador de transacciones superior, pero ya existe un administrador de transacciones superior . |
|
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. |
|
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.
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) |
Consulte también
Uso de las versiones Nt y Zw de las rutinas nativas de System Services