KeSetEvent, fonction (wdm.h)

Article
02/27/2024

La routine KeSetEvent définit un objet événement à un état signalé si l’événement n’a pas déjà été signalé et retourne l’état précédent de l’objet d’événement.

Syntaxe

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

Paramètres

[in, out] Event

Pointeur vers un objet d’événement initialisé pour lequel l’appelant fournit le stockage.

[in] Increment

Spécifie l’incrément de priorité à appliquer si la définition de l’événement entraîne la satisfaction d’une attente.

[in] Wait

Spécifie si l’appel à KeSetEvent doit être suivi immédiatement d’un appel à l’une des routines KeWaitXxx . Si la valeur est TRUE, l’appel KeSetEvent doit être suivi d’un appel à KeWaitForMultipleObjects, KeWaitForMutexObject ou KeWaitForSingleObject. Pour plus d'informations, consultez la section Notes qui suit.

Valeur retournée

Si l’état précédent de l’objet événement a été signalé, une valeur différente de zéro est retournée.

Remarques

L’appel de KeSetEvent entraîne l’obtention d’un état signalé par l’événement. Si l’événement est un événement de notification, le système tente de satisfaire autant d’attentes que possible sur l’objet d’événement. L’événement reste signalé jusqu’à ce qu’un appel à KeClearEvent ou KeResetEvent l’efface. Si l’événement est un événement de synchronisation, une attente est satisfaite avant que le système efface automatiquement l’événement.

La routine KeSetEvent peut temporairement déclencher l’IRQL. Si le paramètre Wait a la valeur FALSE, la routine, avant de retourner, restaure l’IRQL à la valeur d’origine qu’elle avait au début de l’appel.

Si l’argument Wait = TRUE est attendu, la routine retourne sans abaisser l’IRQL. Dans ce cas, l’appel KeSetEvent doit être immédiatement suivi d’un appel KeWaitXxx . En définissant Wait = TRUE, l’appelant peut empêcher un changement de contexte inutile entre l’appel KeSetEvent et l’appel KeWaitXxx . La routine KeWaitXxx , avant de retourner, restaure l’IRQL à sa valeur d’origine au début de l’appel KeSetEvent . Bien que l’IRQL désactive les commutateurs de contexte entre les deux appels, ces appels ne peuvent pas être utilisés de manière fiable comme début et fin d’une opération atomique. Par exemple, entre ces deux appels, un thread qui s’exécute en même temps sur un autre processeur peut modifier l’état de l’objet d’événement ou de la cible de l’attente.

Une routine de thread paginable ou de pilote paginable qui s’exécute à IRQL = PASSIVE_LEVEL ne doit jamais appeler KeSetEvent avec le paramètre Wait défini sur TRUE. Un tel appel provoque une erreur de page irrécupérable si l’appelant est paginé entre les appels à KeSetEvent et KeWaitXxx.

Pour plus d’informations sur les objets d’événement, consultez Objets d’événement.

Si Wait a la valeur FALSE, l’appelant peut s’exécuter sur IRQL <= DISPATCH_LEVEL. Sinon, les appelants de KeSetEvent doivent s’exécuter sur IRQL <= APC_LEVEL et dans un contexte de thread nonarbitrary.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Consultez la section Notes.
Règles de conformité DDI	CompletionEventChecking(wdm), DoubleKeSetEvent(storport), HwStorPortProhibitedDDIs(storport), IoAllocateIrpSignalEventInCompletion(wdm), IoBuildDeviceIoControlSetEvent(wdm), IoBuildFsdIrpSignalEventInCompletion(wdm),IrqlKeSetEvent(wdm), SignalEventInCompletion(wdm)