Función ZwCreateEvent (ntifs.h)

Artículo
07/11/2023

La rutina ZwCreateEvent 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 de 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 autor de la llamada que se va a usar para el objeto especificado. Estos atributos incluirían objectName 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 NotificationEvent. Estos valores pertenecen a la enumeración EVENT_TYPE , que se define en el archivo de encabezado ntdef.h .

[in] InitialState

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

Valor devuelto

ZwCreateEvent devuelve STATUS_SUCCESS o un estado de error adecuado. Entre los posibles códigos de estado de error 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 miembro ObjectName 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 .

Comentarios

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 finalice la operación solicitada hasta que el evento especificado esté establecido en el estado Signaled.

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 un evento de sincronización se establece en el estado Signaled, se libera un único subproceso de ejecución que estaba esperando que se indique 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 señale el evento mediante una llamada a ZwWaitForSingleObject con 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 tiempo de espera de cero en 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 usar la macro InitializeObjectAttributes 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 miembro ObjectName de la entrada ObjectAttributes.
Como pathname relativo al directorio representado por el identificador en el miembro RootDirectory 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 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 versiones NtXxx y ZwXxx de una rutina de Servicios del sistema nativo de Windows se pueden comportar 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	Windows XP.
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)