Función ZwCreateEvent (ntifs.h)

Artículo
12/21/2024

El ZwCreateEvent rutina crea un objeto de evento, establece el estado inicial del evento en el valor especificado y abre un identificador para el objeto con el acceso deseado especificado.

Sintaxis

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

Parámetros

[out] EventHandle

Puntero a una variable que recibirá el identificador del objeto de evento. El identificador incluye información de contabilidad, como un recuento de referencias y un contexto de seguridad.

[in] DesiredAccess

Valor ACCESS_MASK que representa los tipos de acceso deseados para el objeto de evento. La tabla siguiente contiene los valores de ACCESS_MASK específicos del evento.

Valor	Acceso deseado
EVENT_QUERY_STATE	Consulte el estado del objeto de evento.
EVENT_MODIFY_STATE	Modifique el estado del objeto de evento.
EVENT_ALL_ACCESS	Todos los derechos de acceso posibles al objeto de evento.

[in, optional] ObjectAttributes

Puntero a la estructura de atributos de objeto proporcionada por el llamador que se va a usar para el objeto especificado. Estos atributos incluirían el ObjectName de y el SECURITY_DESCRIPTOR, por ejemplo. Este parámetro se inicializa llamando a la macro initializeObjectAttributes .

[in] EventType

Tipo del evento, que puede ser SynchronizationEvent o un NotificationEvent. Estos valores pertenecen a la enumeración EVENT_TYPE, que se define en el archivo de encabezado de ntdef. h.

[in] InitialState

Estado inicial del objeto de evento. Establézcalo en TRUE para inicializar el objeto de evento en estado Signaled. Establézcalo en FALSE para inicializar el objeto de evento en estado no señalizado.

Valor devuelto

ZwCreateEvent devuelve STATUS_SUCCESS o un estado de error adecuado. Entre los códigos de estado de error posibles se incluyen los siguientes:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	No se pudieron asignar recursos requeridos por esta función.
STATUS_INVALID_PARAMETER	La estructura ObjectAttributes proporcionada contenía un valor de parámetro no válido.
STATUS_INVALID_PARAMETER_4	El parámetro EventType especificado no era válido.
STATUS_OBJECT_NAME_INVALID	El parámetro ObjectAttributes contenía un ObjectName en la estructura OBJECT_ATTRIBUTES que no era válida.
STATUS_OBJECT_PATH_SYNTAX_BAD	El parámetro ObjectAttributes no contenía un miembro RootDirectory, pero el ObjectName miembro de la estructura OBJECT_ATTRIBUTES era una cadena vacía o no contenía un carácter OBJECT_NAME_PATH_SEPARATOR. Esto indica una sintaxis incorrecta para la ruta de acceso del objeto.
STATUS_PRIVILEGE_NOT_HELD	El autor de la llamada no tenía el privilegio necesario para crear un identificador con el acceso especificado en el parámetro DesiredAccess.

Observaciones

ZwCreateEvent crea un objeto de evento, establece su estado inicial en el valor especificado y abre un identificador para el objeto con el acceso deseado especificado.

Los eventos se usan para coordinar la ejecución. Los controladores del sistema de archivos pueden usar eventos para permitir que un autor de la llamada espere a que se complete la operación solicitada hasta que el evento especificado esté establecido en el estado Señalizado.

ZwCreateEvent puede crear eventos de notificación o sincronización:

Los eventos de notificación se pueden usar para notificar a uno o varios subprocesos de ejecución que se ha producido un evento.
Los eventos de sincronización se pueden usar en la serialización del acceso al hardware entre dos controladores no relacionados de otro modo.

Un evento de sincronización es el restablecimiento automático. Cuando se establece un evento de sincronización en el estado Signaled, se libera un único subproceso de ejecución que estaba esperando que se libere el evento y el evento se restablece automáticamente al estado de Not-Signaled.

A diferencia de un evento de sincronización, un evento de notificación no se restablezca automáticamente. Una vez que un evento de notificación está en estado Signaled, permanece en ese estado hasta que se restablece explícitamente.

Para sincronizar en un evento de notificación:

Cree el evento de notificación con ZwCreateEvent con el parámetro EventType establecido en NotificationEvent.
Espere a que se indique el evento llamando a ZwWaitForSingleObject con el EventHandle devuelto por ZwCreateEvent. Más de un subproceso de ejecución puede esperar a que se señale un evento de notificación determinado. Para sondear en lugar de detener, especifique un de tiempo de espera de de cero para ZwWaitForSingleObject.
Cierre el identificador del evento de notificación con ZwClose cuando ya no se necesite acceso al evento.

Se llama a la función ZwCreateEvent después de la macro InitializeObjectAttributes se usa para establecer atributos en la estructura OBJECT_ATTRIBUTES para el objeto.

Hay dos maneras alternativas de especificar el nombre del objeto pasado a ZwCreateEvent:

Como nombre de ruta de acceso completo, proporcionado en el ObjectName miembro de la entrada ObjectAttributes.
Como pathname relativo al directorio representado por el identificador del rootDirectory miembro de la entrada ObjectAttributes.

Para liberar el evento, un controlador llama a ZwClose con el identificador de eventos.

Para obtener más información sobre los eventos, vea Objetos de eventos.

Nota

Si la llamada a la rutina de ZwCreateEvent se produce en modo de usuario, debe usar el nombre "NtCreateEvent" en lugar de "ZwCreateEvent".

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	Windows XP.
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)