KeInsertHeadQueue-Funktion (ntifs.h)

Artikel
02/29/2024

Die KeInsertHeadQueue-Routine fügt einen Eintrag am Anfang der angegebenen Warteschlange ein, wenn sie den Eintrag nicht sofort verwenden kann, um eine Threadwartezeit zu erfüllen.

Syntax

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

Parameter

[in, out] Queue

Zeiger auf ein initialisiertes Warteschlangenobjekt, für das der Aufrufer residenten Speicher im nicht ausgelagerten Pool bereitstellt. Diese Struktur ist wie folgt definiert:

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

Mitglied	Bedeutung
Kopfzeile	Warteschlangenheader
EntryListHead	Zeiger auf den ersten Eintrag in der Warteschlange
CurrentCount	Anzahl der Einträge in der Warteschlange
MaximumCount	Maximale Anzahl von Einträgen, die die Warteschlange enthalten kann
ThreadListHead	Zeiger auf den ersten Eintrag in der Threadliste

[in, out] Entry

Zeiger auf den Warteschlangeneintrag, der eingefügt werden soll. Bei diesem Zeiger muss es sich um eine adressebasierte Systemraumadresse handeln.

Rückgabewert

KeInsertHeadQueue gibt den vorherigen Signalzustand der angegebenen Warteschlange zurück. Wenn er vor dem Aufruf von KeInsertHeadQueue auf 0 (nicht signalisiert) festgelegt wurde, gibt KeInsertHeadQueue null zurück, was bedeutet, dass keine Einträge in die Warteschlange eingereiht wurden. Wenn es ungleich null (signalisiert) war, gibt KeInsertHeadQueue die Anzahl der Einträge zurück, die vor dem Aufruf von KeInsertHeadQueue in die Warteschlange eingereiht wurden.

Hinweise

Einträge, die von KeInsertHeadQueue in die Warteschlange gestellt werden sollen, müssen aus einem nicht ausseitigen Pool zugeordnet werden. Beispielsweise kann der Arbeitsspeicher für vom Aufrufer definierte Einträge mit ExAllocatePoolWithTag zugeordnet werden. Wenn der Aufrufer Einträge einer festen Größe zuordnet, ist das Erstellen einer Lookaside-Liste mit ExInitializeNPagedLookasideList und das Zuweisen mit ExAllocateFromNPagedLookasideList effizienter als häufige Aufrufe von ExAllocatePoolWithTag, insbesondere für Einträge, deren Größe kein Vielfaches von PAGE_SIZE ist.

Wenn Threads auf das Warteschlangenobjekt warten, wenn KeInsertHeadQueue aufgerufen wird, wird die Wartezeit eines einzelnen Threads durch diesen Aufruf erfüllt. Der Thread wird zur Ausführung mit dem angegebenen Entry-Zeiger verteilt.

Wenn beim Aufrufen von KeInsertHeadQueue derzeit keine Threads auf das Warteschlangenobjekt warten, wird der angegebene Eintrag in die Warteschlange eingefügt, und der Signalzustand des Warteschlangenobjekts wird erhöht.

Weitere Informationen zur Verwendung von vom Treiber verwalteten internen Warteschlangen finden Sie unter Vom Treiber verwaltete Warteschlangen.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport)