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

Статья
02/07/2025

Функция 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, которые необходимо добавить в заголовок объекта после выделения заголовка. Это значение должно быть равно нулю, если ItemsListNULL.

[in, optional] ItemsList

При необходимости указывает указатель на выделенный вызывающим буфером, содержащим ряд KSOBJECT_CREATE_ITEM структур, добавляемых в заголовок объекта. Необходимо задать значение NULL, если нет элементов создания объекта.

[in] Irp

Указывает на IRP основной функции IRP_MJ_CREATE, которая содержит необходимые сведения для завершения создания заголовка объекта.

[in] Table

Указывает на инициализированную таблицу диспетчеризации для этого объекта файла.

Возвращаемое значение

Функция KsAllocateObjectHeader возвращает STATUS_SUCCESS в случае успешного выполнения запроса или STATUS_INSUFFICIENT_RESOURCES, если недостаточно ресурсов для выполнения запроса.

Замечания

Прежде чем вызывать эту подпрограмму, драйвер должен выделить системное хранилище для KSDISPATCH_TABLE и инициализировать таблицу отправки. Память для этой таблицы отправки не может быть освобождена до вызова KsFreeObjectHead er.

KsAllocateObjectHeader выделяет память для структуры KSOBJECT_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 (include Ks.h)
библиотеки	Ks.lib
IRQL	< DISPATCH_LEVEL

См. также

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader

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