KsAllocateObjectHeader 函数 (ks.h)

KsAllocateObjectHeader 函数初始化所需的文件上下文标头。

语法

KSDDKAPI NTSTATUS KsAllocateObjectHeader(
  [out]          KSOBJECT_HEADER        *Header,
  [in]           ULONG                  ItemsCount,
  [in, optional] PKSOBJECT_CREATE_ITEM  ItemsList,
  [in]           PIRP                   Irp,
  [in]           const KSDISPATCH_TABLE *Table
);

参数

[out] Header

指向调用方分配的位置，如果成功，将在该位置返回指向初始化 KSOBJECT_HEADER 的指针。

[in] ItemsCount

指定在分配标头后要添加到对象标头的 ItemsList 中的对象创建项的数目。 如果 ItemsList 为 NULL，则此值应为 零。

[in, optional] ItemsList

（可选）指定指向调用方分配的缓冲区的指针，该缓冲区包含要添加到对象标头的一系列 KSOBJECT_CREATE_ITEM 结构。 如果没有对象创建项，则必须设置为 NULL 。

[in] Irp

指向主要函数 IRP_MJ_CREATE的 IRP，其中包含完成对象标头创建所需的信息。

[in] Table

指向此文件对象的初始化调度表。

返回值

如果成功， KsAllocateObjectHeader 函数返回 STATUS_SUCCESS ;如果没有足够的资源来满足请求，则 返回STATUS_INSUFFICIENT_RESOURCES 。

注解

在调用此例程之前，驱动程序必须为 KSDISPATCH_TABLE 分配系统驻留存储并初始化调度表。 在调用 KsFreeObjectHeader 之前，无法释放此调度表的内存。

KsAllocateObjectHeader 为 KSOBJECT_HEADER 结构分配内存，并返回指向 Header 处标头的指针。 驱动程序不得尝试自行释放内存，而是在完成需要此对象标头的所有操作时调用 KsFreeObjectHeader 。

如果给定设备存在子对象，则在调用 KsAllocateObjectHeader 之前，驱动程序必须分配足够大小的分页内存或非分页内存的缓冲区，以便为每个子对象保留 KSOBJECT_CREATE_ITEM 结构。 例如：

/* Allocate a buffer for 4 subobjects for a given streaming device */
PKSOBJECT_CREATE_ITEM createBuffer ;
ULONG bufferSize  = (sizeof (KSOBJECT_CREATE_ITEM)) * 4 ;

createBuffer = (PKSOBJECT_CREATE_ITEM)
               ExAllocatePoolWithTag (PagedPool, bufferSize) ;

在调用 KsFreeDeviceHeader 之前，驱动程序不得释放为子对象KSOBJECT_CREATE_ITEM列表分配的内存。 否则可能会导致 bug 检查条件。

要求

另请参阅

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader