ZwWaitForSingleObject, fonction (ntifs.h)

Article
12/21/2024

La routine ZwWaitForSingleObject attend que l’objet spécifié atteigne un état de Signaled. Un délai d’attente facultatif peut également être spécifié.

Syntaxe

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Paramètres

[in] Handle

Handle vers l’objet.

[in] Alertable

Valeur booléenne qui spécifie si l’attente est alertable.

[in, optional] Timeout

Pointeur facultatif vers une valeur de délai d’attente qui spécifie l’heure absolue ou relative à laquelle l’attente doit être terminée. Une valeur négative spécifie un intervalle par rapport à l’heure actuelle. La valeur doit être exprimée en unités de 100 nanosecondes. Les heures d’expiration absolues suivent les modifications apportées à l’heure système. Les délais d’expiration relatifs ne sont pas affectés par les modifications de temps système.

Valeur de retour

ZwWaitForSingleObject pouvez retourner l’un des codes d’état suivants :

Retourner le code	Description
STATUS_ACCESS_DENIED	L’appelant n’a pas les privilèges requis pour l’événement spécifié par le paramètre de handle .
STATUS_ALERTED	L’attente a été abandonnée pour remettre une alerte au thread actuel.
STATUS_INVALID_HANDLE	Le paramètre Handle fourni n’était pas valide.
STATUS_SUCCESS	L’objet spécifié satisfait l’attente.
STATUS_TIMEOUT	Un délai d’attente s’est produit avant que l’objet ait été défini sur un état signalé. Cette valeur peut être retournée lorsque l’ensemble spécifié de conditions d’attente ne peut pas être immédiatement rempli et que le paramètre Délai d’expiration est défini sur zéro.
STATUS_USER_APC	L’attente a été abandonnée pour remettre un APC utilisateur au thread actuel.

Notez que la macro NT_SUCCESS reconnaît les valeurs d’état STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT et STATUS_USER_APC comme valeurs de « réussite ».

Remarques

ZwWaitForSingleObject attend que l’objet spécifié atteigne un état de Signaled. Un délai d’expiration facultatif peut également être spécifié. ZwWaitForSingleObject examine l’état actuel de l’objet spécifié pour déterminer si l’attente peut être satisfaite immédiatement. Dans ce cas, les actions sont effectuées. Sinon, le thread actuel est placé dans un état d’attente et un nouveau thread est sélectionné pour l’exécution sur le processeur actuel.

Si un paramètre Timeout n’est pas spécifié, l’attente n’est pas satisfaite tant que l’objet n’a pas atteint l’état Signaled. Si un paramètre Timeout est spécifié et que l’objet n’a pas atteint l’état Signaled lorsque le délai d’expiration expire, l’attente est automatiquement satisfaite. Si une explicite délai d’expiration valeur zéro est spécifiée, aucune attente ne se produit si l’attente ne peut pas être satisfaite immédiatement. Un délai d’attente délai d’attente valeur zéro permet le test d’un ensemble de conditions d’attente et les performances conditionnelles des effets secondaires si l’attente peut être immédiatement satisfaite, comme dans l’acquisition d’un mutex. L’attente peut également être spécifiée en tant qu’alerte.

Le paramètre Alertable spécifie si le thread peut être alerté et son état d’attente a donc été abandonné. Si la valeur de ce paramètre est FALSE, le thread ne peut pas être alerté. La seule exception à cette règle est celle d’un thread de fin. Dans certaines circonstances, un thread de fin peut être alerté pendant qu’il est en cours d’arrêt. Un thread est automatiquement alertable, par exemple, lorsqu’il est arrêté par un utilisateur avec une touche Ctrl+C.

Si la valeur de alertable est TRUE et que l’une des conditions suivantes est présente, le thread est alerté :

Si l’origine de l’alerte est une routine interne en mode noyau non documenté utilisée pour les threads d’alerte.
L’origine de l’alerte est un APC en mode utilisateur.

Dans le premier de ces deux cas, l’attente du thread est satisfaite d’un état d’achèvement de STATUS_ALERTED. Dans le deuxième cas, il est satisfait d’un état d’achèvement de STATUS_USER_APC.

Le thread doit être alertable pour qu’un APC en mode utilisateur soit remis. Ce n’est pas le cas pour les API en mode noyau. Un APC en mode noyau peut être remis et exécuté même si le thread n’est pas alerté. Une fois l’exécution de l’APC terminée, l’attente du thread reprend. Un thread n’est jamais alerté, ni son attente abandonnée, par la remise d’un APC en mode noyau.

La remise d’API en mode noyau à un thread en attente ne dépend pas du fait que le thread peut être alerté. Si l’APC en mode noyau est un APC en mode noyau spécial, l’APC est fourni à condition que l’IRQL soit inférieur à APC_LEVEL. Si l’APC en mode noyau est un APC en mode noyau normal, l’APC est fourni à condition que les trois conditions suivantes soient conservées : (1) l’IRQL est inférieur à APC_LEVEL, (2) aucun APC du noyau n’est en cours et (3) le thread n’est pas dans une section critique.

Si le handle passé à ZwWaitForSingleObject fait référence à un mutex, la remise d’APC est la même que pour tous les autres objets de répartiteur pendant l’attente. Toutefois, une fois ZwWaitForSingleObject retourne avec STATUS_SUCCESS et le thread contient réellement le mutex, seules les API en mode noyau spécial sont remises. La remise de toutes les autres API, en mode noyau et en mode utilisateur, est désactivée. Cette restriction sur la remise des API persiste jusqu’à ce que le mutex soit libéré.

Il est particulièrement important de vérifier la valeur de retour de ZwWaitForSingleObject lorsque le paramètre Alertable a la valeur TRUE, car ZwWaitForSingleObject peut retourner tôt avec un état de STATUS_USER_APC ou de STATUS_ALERTED.

Toutes les attentes à long terme peuvent être abandonnées par un utilisateur si le paramètre Alertable a la valeur FALSE.

Pour plus d’informations, consultez Les threads en attente reçoivent-ils des alertes et des API ?

Les appelants de ZwWaitForSingleObject doivent s’exécuter au niveau d’IRQL inférieur ou égal à DISPATCH_LEVEL. En règle générale, l’appelant doit s’exécuter à l’PASSIVE_LEVEL IRQL et dans un contexte de thread nonarbitraire. Un appel en cours d’exécution à l’DISPATCH_LEVEL IRQL est valide si et uniquement si l’appelant spécifie un paramètre Timeout de zéro. Autrement dit, un pilote ne doit pas attendre un intervalle différent de zéro à IRQL égal à DISPATCH_LEVEL.

Les intervalles de délai d’attente sont mesurés par rapport à l’horloge système, et la précision de la mesure de délai d’attente est limitée par la granularité de l’horloge système. Pour plus d’informations, consultez précision du minuteur.

Si l’appel à la fonction ZwWaitForSingleObject se produit en mode utilisateur, vous devez utiliser le nom «NtWaitForSingleObject» au lieu de «ZwWaitForSingleObject».

Pour les appels à partir de pilotes en mode noyau, les versions NtXxx et ZwXxx d’une routine Windows Native System Services peuvent se comporter différemment de la façon dont elles gèrent et interprètent les paramètres d’entrée. Pour plus d’informations sur la relation entre les versions NtXxx et ZwXxx d’une routine, consultez Using Nt and Zw Versions of the Native System Services Routines.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP
plateforme cible	Universel
d’en-tête	ntifs.h (include Ntifs.h, FltKernel.h)
bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
règles de conformité DDI	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)