Функция KsAllocateObjectHeader (ks.h)

Статья
02/29/2024

Функция 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 основной функции IRP_MJ_CREATE, которая содержит сведения, необходимые для завершения создания заголовка объекта.

[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) ;

Драйверы не должны освобождать память, выделенную для списка KSOBJECT_CREATE_ITEM подобъекта, пока не вызовет KsFreeDeviceHeader. Если это не сделать, это может привести к ошибке проверка условию.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	ks.h (включая Ks.h)
Библиотека	Ks.lib
IRQL	< DISPATCH_LEVEL

См. также раздел

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader

Поделиться через