Función IoCreateSynchronizationEvent (wdm.h)

  • Artículo

La rutina IoCreateSynchronizationEvent crea o abre un evento de sincronización con nombre para su uso en la serialización del acceso al hardware entre dos controladores no relacionados de otro modo.

Sintaxis

PKEVENT IoCreateSynchronizationEvent(
  [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 para el objeto de evento. En Windows Server 2003 y versiones posteriores de Windows, el identificador devuelto es un identificador de kernel.

Valor devuelto

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

Comentarios

El objeto de evento se crea si aún no existe. IoCreateSynchronizationEvent establece el estado de un nuevo evento de sincronización en Signaled. Si el objeto de evento ya existe, simplemente se abre. El par de controladores que usan una llamada de evento de sincronización KeWaitForSingleObject con el puntero PKEVENT devuelto por esta rutina.

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

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

El uso compartido de objetos de eventos entre el modo de usuario y el modo kernel requiere cuidado. 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 driverEntry .

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

Requisitos

Requisito Value
Cliente mínimo compatible Disponible a partir de Windows 2000.
Plataforma de destino Universal
Encabezado wdm.h (incluya Ntddk.h)
Library NtosKrnl.lib
Archivo DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Reglas de cumplimiento de DDI HwStorPortProhibitedDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

Consulte también

IoCreateNotificationEvent

KeWaitForSingleObject

RtlInitUnicodeString

ZwClose