Fonction KeRemoveQueue (ntifs.h)

La routine KeRemoveQueue donne au thread appelant un pointeur vers une entrée de file d’attente supprimée de l’objet file d’attente donné ou permet à l’appelant d’attendre, jusqu’à un intervalle de délai d’expiration facultatif, sur l’objet 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 est en attente, qui peut être KernelMode ou UserMode. Si un élément de sa pile est accessible à l’adresse IRQL >= DISPATCH_LEVEL, l’appelant doit spécifier KernelMode.

[in, optional] Timeout

Pointeur vers une variable qui spécifie l’heure absolue ou relative, 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, il est absolu. Les heures d’expiration absolues suivent toute modification de l’heure système ; les heures d’expiration relatives ne sont pas affectées par les changements d’heure système. Ce pointeur peut avoir la valeur NULL.

Valeur retournée

KeRemoveQueue retourne l’un des éléments suivants :

• Pointeur vers une entrée en file d’attente supprimée de l’objet de file d’attente donné, le cas échéant.
• STATUS_TIMEOUT, si l’intervalle de délai d’expiration donné a expiré avant qu’une entrée soit disponible
• STATUS_USER_APC, si un APC en mode utilisateur a été fourni 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 le délai d’attente 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*Timeout 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 passer des paramètres sur la pile lors de l’appel de KeRemoveQueue avec WaitMode défini sur UserMode.

La spécification de WaitMode en tant que KernelMode dans un appel à KeRemoveQueue empêche l’échange de la pile du noyau du thread appelant, ainsi que la remise d’appels de procédure asynchrone en mode utilisateur (APC). Cela n’empêche pas la remise d’API en mode noyau, tels que ceux utilisés par le Gestionnaire d’E/S pour terminer les IRPs, lorsqu’un thread appelle KeRemoveQueue à partir d’IRQL PASSIVE_LEVEL. La remise d’un tel APC en mode noyau n’empêche pas le thread appelant d’attendre sur l’objet de file d’attente ni d’être distribué pour exécution avec une entrée après l’exécution de l’APC du noyau.

Pour plus d’informations sur l’utilisation des files d’attente internes gérées par les pilotes, consultez Files d’attente gérées par les pilotes.

Configuration requise

Voir aussi

KeInsertHeadQueue

KeInsertQueue