Funzione KeInsertHeadQueue (ntifs.h)

Articolo
02/29/2024

La routine KeInsertHeadQueue inserisce una voce all'inizio della coda specificata se non può utilizzare immediatamente la voce per soddisfare un'attesa del thread.

Sintassi

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

Parametri

[in, out] Queue

Puntatore a un oggetto coda inizializzato per il quale il chiamante fornisce l'archiviazione residente nel pool non di paging. Questa struttura è definita come segue:

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

Membro	Significato
Intestazione	Intestazione della coda
EntryListHead	Puntatore alla prima voce nella coda
CurrentCount	Numero di voci nella coda
MaximumCount	Numero massimo di voci che la coda può contenere
ThreadListHead	Puntatore alla prima voce nell'elenco di thread

[in, out] Entry

Puntatore alla voce della coda da inserire. Questo puntatore deve essere un indirizzo dello spazio di sistema residente.

Valore restituito

KeInsertHeadQueue restituisce lo stato del segnale precedente della coda specificata. Se è stato impostato su zero (non segnalato) prima della chiamata a KeInsertHeadQueue , KeInsertHeadQueue restituisce zero, ovvero nessuna voce è stata accodata. Se è diverso da zero (segnalato), KeInsertHeadQueue restituisce il numero di voci accodate prima della chiamata a KeInsertHeadQueue .

Commenti

Le voci da accodare da KeInsertHeadQueue devono essere allocate dal pool non di paging. Ad esempio, la memoria per le voci definite dal chiamante può essere allocata con ExAllocatePoolWithTag. Se il chiamante alloca le voci di una dimensione fissa, la creazione di un elenco lookaside con ExInitializeNPagedLookasideList e l'allocazione da essa con ExAllocateFromNPagedLookasideList è più efficiente rispetto all'esecuzione di chiamate frequenti a ExAllocatePoolWithTag, in particolare per le voci le cui dimensioni non sono un multiplo di PAGE_SIZE.

Se un thread è in attesa dell'oggetto coda quando viene chiamato KeInsertHeadQueue , l'attesa di un singolo thread viene soddisfatta da questa chiamata. Il thread viene inviato per l'esecuzione con il puntatore di ingresso specificato.

Se nessun thread è attualmente in attesa sull'oggetto coda quando viene chiamato KeInsertHeadQueue , la voce specificata viene inserita nella coda e lo stato del segnale dell'oggetto coda viene incrementato.

Per altre informazioni sull'uso delle code interne gestite dal driver, vedere Code gestite da driver.

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport)