Función KeSetEvent (wdm.h)

Artículo
08/08/2023

La rutina KeSetEvent establece un objeto de evento en un estado señalado si el evento aún no se ha señalado y devuelve el estado anterior del objeto de evento.

Sintaxis

LONG KeSetEvent(
  [in, out] PRKEVENT  Event,
  [in]      KPRIORITY Increment,
  [in]      BOOLEAN   Wait
);

Parámetros

[in, out] Event

Puntero a un objeto de evento inicializado para el que el autor de la llamada proporciona el almacenamiento.

[in] Increment

Especifica el incremento de prioridad que se va a aplicar si establecer el evento hace que se cumpla una espera.

[in] Wait

Especifica si la llamada a KeSetEvent debe ir seguida inmediatamente de una llamada a una de las rutinas KeWaitXxx . Si es TRUE, la llamada a KeSetEvent debe ir seguida de una llamada a KeWaitForMultipleObjects, KeWaitForMutexObject o KeWaitForSingleObject. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

Si se señalizó el estado anterior del objeto de evento, se devuelve un valor distinto de cero.

Comentarios

Llamar a KeSetEvent hace que el evento alcance un estado señalado. Si el evento es un evento de notificación, el sistema intenta satisfacer tantas esperas como sea posible en el objeto de evento. El evento permanece señalado hasta que una llamada a KeClearEvent o KeResetEvent la borra. Si el evento es un evento de sincronización, se satisface una espera antes de que el sistema borre automáticamente el evento.

La rutina KeSetEvent podría generar temporalmente el IRQL. Si el parámetro Wait es FALSE, la rutina, antes de devolverla, restaura el IRQL al valor original que tenía al principio de la llamada.

Si espera = TRUE, la rutina devuelve sin reducir el IRQL. En este caso, la llamada a KeSetEvent debe seguir inmediatamente una llamada a KeWaitXxx . Al establecer Wait = TRUE, el autor de la llamada puede impedir que se produzca un cambio de contexto innecesario entre la llamada KeSetEvent y la llamada KeWaitXxx . La rutina KeWaitXxx , antes de devolverla, restaura el IRQL a su valor original al principio de la llamada a KeSetEvent . Aunque IRQL deshabilita los modificadores de contexto entre las dos llamadas, estas llamadas no se pueden usar de forma confiable como inicio y final de una operación atómica. Por ejemplo, entre estas dos llamadas, un subproceso que se ejecuta al mismo tiempo en otro procesador podría cambiar el estado del objeto de evento o del destino de la espera.

Una rutina de subproceso paginable o controlador paginable que se ejecuta en IRQL = PASSIVE_LEVEL nunca debe llamar a KeSetEvent con el parámetro Wait establecido en TRUE. Esta llamada provoca un error grave en la página si el autor de la llamada se pagina entre las llamadas a KeSetEvent y KeWaitXxx.

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

Si Wait está establecido en FALSE, el autor de la llamada puede ejecutarse en IRQL <= DISPATCH_LEVEL. De lo contrario, los autores de llamadas de KeSetEvent deben ejecutarse en IRQL <= APC_LEVEL y en un contexto de subproceso nobitrario.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 2000.
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	CompletionEventChecking(wdm), DoubleKeSetEvent(storport), HwStorPortProhibitedDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm), IrqlKeSetEvent(wdm), SignalEventInCompletion(wdm)