KeRemoveQueue, fonction (ntifs.h)
La routine KeRemoveQueue donne au thread appelant un pointeur vers une entrée de file d’attente donnée à partir de l’objet de file d’attente donné ou permet à l’appelant d’attendre, jusqu’à un intervalle de délai d’attente facultatif, sur l’objet de file d’attente.
Syntaxe
PLIST_ENTRY KeRemoveQueue(
[in, out] PRKQUEUE Queue,
[in] KPROCESSOR_MODE WaitMode,
[in, optional] PLARGE_INTEGER Timeout
);
Paramètres
[in, out] Queue
Pointeur vers un objet de file d’attente initialisé pour lequel l’appelant fournit un stockage résident dans un pool non paginé.
[in] WaitMode
Mode processeur dans lequel l’appelant attend, qui peut être KernelMode ou UserMode. Si quelque chose sur sa pile peut être accessible au >IRQL = DISPATCH_LEVEL, l’appelant doit spécifier KernelMode.
[in, optional] Timeout
Pointeur vers une variable qui spécifie le temps absolu ou relatif, en unités de 100 nanosecondes, à laquelle l’attente doit expirer. Si la valeur de délai d’expiration est négative, l’heure d’expiration est relative à l’heure système actuelle ; sinon, c’est absolu. Les temps d’expiration absolus suivent les modifications apportées à l’heure système ; les heures d’expiration relatives ne sont pas affectées par les modifications de temps système. Ce pointeur peut être NULL.
Valeur de retour
KeRemoveQueue retourne l’une des valeurs suivantes :
- Pointeur vers une entrée de file d’attente donnée à partir de l’objet file d’attente donné, si un pointeur est disponible.
- STATUS_TIMEOUT, si l’intervalle de délai d’expiration donné a expiré avant qu’une entrée ne soit disponible
- STATUS_USER_APC, si un APC en mode utilisateur a été remis dans le contexte du thread appelant
- STATUS_ABANDONED, si la file d’attente a été exécutée
Remarques
Les appelants de KeRemoveQueue doivent tester si sa valeur de retour est STATUS_TIMEOUT ou STATUS_USER_APC avant d’accéder aux membres d’entrée. Le test de la valeur de retour de KeRemoveQueue par rapport à NULL est une erreur de programmation.
La spécification d’une valeur zéro pour délai d’expiration indique que l’appelant ne veut pas attendre une entrée si la file d’attente est actuellement vide. La spécification d’un pointeur **NULL*délai d’expiration indique la volonté de l’appelant d’attendre indéfiniment une entrée.
Si le paramètre WaitMode est UserMode, la pile du noyau peut être permutée pendant l’attente. Par conséquent, un appelant ne doit jamais tenter de transmettre des paramètres sur la pile lors de l’appel KeRemoveQueue avec WaitMode défini sur UserMode.
La spécification WaitMode en tant que KernelMode dans un appel à KeRemoveQueue empêche l’échange de la pile du noyau du thread appelant, ainsi que d’empêcher la remise des appels de procédure asynchrone en mode utilisateur (APC). Il n’empêche pas la remise d’API en mode noyau, telles que celles utilisées par le Gestionnaire d’E/S pour terminer les IRPs, lorsqu’un thread appelle KeRemoveQueue à partir du PASSIVE_LEVEL IRQL. La remise d’un TEL APC en mode noyau n’empêche pas le thread appelant d’attendre l’objet de file d’attente ni d’être distribué pour exécution avec une entrée après l’exécution du noyau APC.
Pour plus d’informations sur l’utilisation de files d’attente internes gérées par le pilote, consultez Driver-Managed files d’attente.
Exigences
| Exigence | Valeur |
|---|---|
| plateforme cible | Universel |
| d’en-tête | ntifs.h (include Ntifs.h, FltKernel.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |