Fonction KeInsertHeadQueue (ntifs.h)

Article
03/01/2024

La routine KeInsertHeadQueue insère une entrée en tête de la file d’attente donnée si elle ne peut pas utiliser immédiatement l’entrée pour satisfaire une attente de thread.

Syntaxe

LONG KeInsertHeadQueue(
  [in, out] PRKQUEUE    Queue,
  [in, out] PLIST_ENTRY Entry
);

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é. Cette structure est définie comme suit :

typedef struct _KQUEUE {
    DISPATCHER_HEADER Header;
    LIST_ENTRY EntryListHead;
    ULONG CurrentCount;
    ULONG MaximumCount;
    LIST_ENTRY ThreadListHead;
} KQUEUE, *PKQUEUE, *RESTRICTED_POINTER PRKQUEUE;

Membre	Signification
En-tête	En-tête de file d’attente
EntryListHead	Pointeur vers la première entrée de la file d’attente
Currentcount	Nombre d’entrées dans la file d’attente
MaximumCount	Nombre maximal d’entrées que la file d’attente peut contenir
ThreadListHead	Pointeur vers la première entrée de la liste des threads

[in, out] Entry

Pointeur vers l’entrée de file d’attente à insérer. Ce pointeur doit être une adresse d’espace système résidente.

Valeur retournée

KeInsertHeadQueue retourne l’état du signal précédent de la file d’attente donnée. S’il a été défini sur zéro (non signalé) avant l’appel de KeInsertHeadQueue , KeInsertHeadQueue retourne zéro, ce qui signifie qu’aucune entrée n’a été mise en file d’attente. S’il était différent de zéro (signalé), KeInsertHeadQueue retourne le nombre d’entrées qui ont été mises en file d’attente avant l’appel de KeInsertHeadQueue .

Remarques

Les entrées à mettre en file d’attente par KeInsertHeadQueue doivent être allouées à partir d’un pool non paginé. Par exemple, la mémoire pour les entrées définies par l’appelant peut être allouée avec ExAllocatePoolWithTag. Si l’appelant alloue des entrées d’une taille fixe, la création d’une liste de recherche avec ExInitializeNPagedLookasideList et l’allocation à partir de celle-ci avec ExAllocateFromNPagedLookasideList est plus efficace que d’effectuer des appels fréquents à ExAllocatePoolWithTag, en particulier pour les entrées dont la taille n’est pas un multiple de PAGE_SIZE.

Si des threads sont en attente sur l’objet file d’attente lorsque KeInsertHeadQueue est appelé, l’attente d’un thread unique est satisfaite par cet appel. Le thread est distribué pour l’exécution avec le pointeur d’entrée donné.

Si aucun thread n’attend actuellement sur l’objet file d’attente lorsque KeInsertHeadQueue est appelé, l’entrée donnée est insérée dans la file d’attente et l’état du signal de l’objet file d’attente est incrémenté.

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

Condition requise	Valeur
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport)