KeInsertHeadQueue 函数 (ntifs.h)

项目
02/26/2024

如果 KeInsertHeadQueue 例程无法立即使用该条目来满足线程等待，则 KeInsertHeadQueue 例程会在给定队列的头插入一个条目。

语法

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

参数

[in, out] Queue

指向初始化的队列对象的指针，调用方为其在非分页池中提供常驻存储。此结构定义如下：

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

成员	含义
标头	队列标头
EntryListHead	指向队列中第一个条目的指针
CurrentCount	队列中的条目数
MaximumCount	队列可以包含的最大条目数
ThreadListHead	指向线程列表中的第一个条目的指针

[in, out] Entry

指向要插入的队列条目的指针。此指针必须是常驻系统空间地址。

返回值

KeInsertHeadQueue 返回给定队列的上一个信号状态。如果它设置为零 (在调用 KeInsertHeadQueue 之前未发出) 信号， 则 KeInsertHeadQueue 返回零，这意味着没有排队的条目。如果是非零 () 发出信号， 则 KeInsertHeadQueue 返回在调用 KeInsertHeadQueue 之前排队的条目数。

注解

KeInsertHeadQueue 排队的条目必须从非分页池中分配。例如，可以使用 ExAllocatePoolWithTag 分配调用方定义的条目的内存。如果调用方分配固定大小的条目，则使用 ExInitializeNPagedLookasideList 创建 lookaside 列表并使用 ExAllocateFromNPagedLookasideList 从该列表进行分配比频繁调用 ExAllocatePoolWithTag 更高效，尤其是对于大小不是PAGE_SIZE倍数的条目。

如果在调用 KeInsertHeadQueue 时，任何线程都在队列对象上等待，则此调用将满足单个线程的等待。使用给定 的 Entry 指针调度线程以执行。

如果在调用 KeInsertHeadQueue 时当前没有线程在队列对象上等待，则会在队列中插入给定条目，并且队列对象的信号状态会递增。

有关使用驱动程序管理的内部队列的详细信息，请参阅驱动程序托管队列。

要求

要求	值
目标平台	通用
标头	ntifs.h (包括 Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport)