Función IoCreateNotificationEvent (wdm.h)

Artigo
02/07/2025

El IoCreateNotificationEvent rutina crea o abre un evento de notificación con nombre que se usa para notificar a uno o varios subprocesos de ejecución que se ha producido un evento.

Sintaxis

C++

PKEVENT IoCreateNotificationEvent(
  [in]  PUNICODE_STRING EventName,
  [out] PHANDLE         EventHandle
);

Parámetros

[in] EventName

Puntero a un búfer que contiene una cadena Unicode terminada en null que asigna un nombre al evento.

[out] EventHandle

Puntero a una ubicación en la que se va a devolver un identificador de kernel para el objeto de evento.

Valor devuelto

IoCreateNotificationEvent devuelve un puntero al objeto de evento creado o abierto o NULL si no se pudo crear o abrir el objeto de evento.

Observaciones

Si el objeto de evento aún no existe, IoCreateNotificationEvent crea y lo abre y establece su estado en Signaled.

Si el objeto de evento ya existe, IoCreateNotificationEvent simplemente abre el objeto de evento.

Tanto los eventos de notificación como los eventos de sincronización se usan para coordinar la ejecución. Sin embargo, mientras un evento de sincronización se restablece a sí mismo, un evento de notificación permanece en estado Signaled hasta que el controlador llama a KeClearEvent o KeResetEvent.

Para sincronizar en un evento de notificación:

Abra el evento de notificación con IoCreateNotificationEvent. Identifique el evento con la cadena EventName.
Espere a que se indique el evento llamando a KeWaitForSingleObject con el PKEVENT devuelto por IoCreateNotificationEvent. Más de un subproceso de ejecución puede esperar un evento de notificación determinado. Para sondear en lugar de detener, especifique un de tiempo de espera de de cero para KeWaitForSingleObject.
Cierre el identificador del evento de notificación con ZwClose cuando ya no se necesite acceso al evento.

Hay dos métodos principales para compartir objetos de eventos:

La aplicación en modo de usuario crea el objeto de evento y pasa un identificador al objeto al controlador enviando un IOCTL al controlador. El controlador debe controlar el IOCTL en el contexto del proceso que creó el objeto de evento y debe validar el identificador llamando a ObReferenceObjectByHandle. Este método es el método recomendado para compartir objetos de eventos entre los modos de usuario y kernel.
El controlador crea un objeto de evento con nombre en el directorio de objetos global \BaseNamedObjects. Para acceder a un evento en modo kernel desde el modo de usuario, use el nombre Global\\Xxx. Tenga en cuenta que la configuración de seguridad puede impedir que una aplicación abra el evento. El directorio de objetos \\BaseNamedObjects no se crea hasta que se inicializa el subsistema de Microsoft Win32, por lo que los controladores que se cargan en tiempo de arranque no pueden crear objetos de evento en el directorio \\BaseNamedObjects en sus rutinas de DriverEntry.

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

Requisitos

Requisito	Valor
cliente mínimo admitido	Disponible a partir de Windows 2000.
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(storport), IrqlIoPassive4(wdm)