Fonction FltCancellableWaitForSingleObject (fltkernel.h)

Article
08/07/2023

La routine FltCancellableWaitForSingleObject exécute une opération d’attente annulable (une attente qui peut être terminée) sur un objet de répartiteur.

Syntaxe

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

Paramètres

[in] Object

Pointeur vers un objet de répartiteur initialisé (événement, mutex, sémaphore, thread ou minuteur) pour lequel l’appelant fournit le stockage.

[in, optional] Timeout

Pointeur vers une valeur de délai d’attente facultative. Ce paramètre spécifie l’heure absolue ou relative, en unités de 100 nanosecondes, lorsque l’attente doit être terminée.

Si le délai d’expiration pointe vers une valeur zéro (autrement dit, *Délai d’attente == 0), la routine retourne sans attendre. Si l’appelant fournit un pointeur NULL ( c’est-à-dire, Délai d’attente == NULL), la routine attend indéfiniment jusqu’à ce que l’objet soit défini à l’état signalé.

Une valeur de délai d’expiration positive spécifie une heure absolue, par rapport au 1er janvier 1601. Une valeur de délai d’attente négative spécifie un intervalle par rapport à l’heure actuelle. Les heures d’expiration absolues suivent les modifications apportées à l’heure système. Les heures d’expiration relatives ne sont pas affectées par les changements d’heure système.

Si le délai d’expiration est spécifié, l’attente est automatiquement satisfaite si l’objet n’est pas défini à l’état signalé à l’expiration de l’intervalle donné.

Une valeur de délai d’attente égale à zéro (autrement dit, *Délai d’attente == 0) vous permet de tester un ensemble de conditions d’attente et d’effectuer de manière conditionnelle des actions supplémentaires si l’attente peut être immédiatement satisfaite, comme dans l’acquisition d’un mutex.

[in, optional] CallbackData

Pointeur vers la structure FLT_CALLBACK_DATA qui représente l’opération d’E/S qui a été émise par l’utilisateur et qui peut être annulée par l’utilisateur. L’appelant doit s’assurer que l’opération d’E/S reste valide pendant la durée de cette routine et que les E/S ne doivent pas avoir de routine d’annulation définie (par exemple, une fonction FltSetCancelCompletion ne doit pas avoir été appelée sur l’opération d’E/S). Notez que l’appelant doit contenir callbackData ; il ne peut pas être passé à un pilote de niveau inférieur.

Valeur retournée

FltCancellableWaitForSingleObject peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_SUCCESS	L’objet dispatcher spécifié par le paramètre Object a été défini sur l’état signalé.
STATUS_TIMEOUT	Un délai d’attente s’est produit avant que l’objet soit défini sur un état signalé. Cette valeur peut également être retournée lorsque la condition d’attente spécifiée ne peut pas être immédiatement remplie et que le délai d’expiration est défini sur zéro.
STATUS_ABANDONED_WAIT_0	L’appelant a tenté d’attendre un mutex qui a été abandonné.
STATUS_CANCELLED	L’attente a été interrompue par une demande d’annulation en attente sur l’opération d’E/S. Notez que cette valeur est retournée uniquement si CallbackData correspond à une opération basée sur IRP est passée à FltCancellableWaitForSingleObject et si les E/S ont été annulées par une routine telle que FltCancelIo.
STATUS_THREAD_IS_TERMINATING	L’attente a été interrompue, car l’application ou l’utilisateur a arrêté le thread.

La valeur de retour indique uniquement le status de l’attente.

Notez que la macro NT_SUCCESS retourne FALSE (« échec ») pour les valeurs STATUS_CANCELLED et STATUS_THREAD_IS_TERMINATING status et TRUE (« réussite ») pour toutes les autres valeurs status.

Remarques

La routine FltCancellableWaitForSingleObject exécute une opération d’attente annulable sur un objet de répartiteur. Si l’utilisateur ou l’application termine le thread, ou si une E/S associée au thread a été annulée par une routine telle que FltCancelIo, l’attente est annulée.

La routine est conçue pour prendre en charge les instructions d’achèvement/annulation d’E/S. L’objectif de ces recommandations est de permettre aux utilisateurs de mettre rapidement fin aux applications. Cela, à son tour, nécessite que les applications aient la possibilité d’arrêter rapidement les threads qui exécutent des E/S et toutes les opérations d’E/S actuelles. Cette routine permet aux threads utilisateur de bloquer (c’est-à-dire d’attendre) dans le noyau pour l’achèvement des E/S, les objets de répartiteur ou les variables de synchronisation de manière à ce que l’attente soit facilement annulée. Cette routine permet également d’arrêter l’attente du thread si le thread est arrêté par un utilisateur ou une application.

Par exemple, un redirecteur peut avoir besoin de créer une opération d’E/S secondaire afin de traiter une E/S en mode utilisateur et d’attendre de manière synchrone que la demande secondaire se termine. Une façon de procéder consiste à configurer un événement qui sera signalé par la routine d’achèvement de l’opération d’E/S secondaire, puis à attendre que l’événement soit signalé. Ensuite, pour effectuer une opération d’attente annulable, FltCancellableWaitForSingleObject est appelé en passant dans l’événement associé à l’opération d’E/S secondaire et à l’opération d’E/S en mode utilisateur d’origine. L’attente du thread pour que l’événement soit signalé est annulée si un événement d’arrêt en attente se produit ou si l’opération d’E/S en mode utilisateur d’origine est annulée.

Notez que la fin de l’attente n’annule pas automatiquement les opérations d’E/S émises par l’appelant, qui doivent être gérées séparément par l’appelant.

Une considération particulière s’applique lorsque le paramètre Object passé à FltCancellableWaitForSingleObject est un mutex. Si l’objet répartiteur attendu est un mutex, la remise APC est la même que pour tous les autres objets de répartiteur pendant l’attente. Toutefois, une fois que FltCancellableWaitForSingleObject retourne avec STATUS_SUCCESS et que le thread contient réellement le mutex, seuls les API spéciales en mode noyau sont livrées. La remise de tous 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é.

Un mutex ne peut être acquis de manière récursive que des fois MINLONG. Si cette limite est dépassée, la routine déclenche une exception STATUS_MUTANT_LIMIT_EXCEEDED.

FltCancellableWaitForSingleObject doit être appelé au PASSIVE_LEVEL IRQL si le paramètre CallbackData représente un IRP de gestionnaire de filtres valide. Sinon, la routine peut être appelée à l’IRQL inférieur ou égal à APC_LEVEL. Les API de noyau normales peuvent être désactivées par l’appelant, si nécessaire, en appelant les routines KeEnterCriticalRegion ou FsRtlEnterFileSystem . Toutefois, les API de noyau spéciales ne doivent pas être désactivées.

La routine FltCancellableWaitForSingleObject s’affirme sur les builds de débogage si CallbackData représente une opération IRP du Gestionnaire de filtres, mais que l’IRP dans la structure CallbackData a la valeur NULL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
En-tête	fltkernel.h (inclure Fltkernel.h, Ntifs.h)
Bibliothèque	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	Consultez la section Notes.