Функция 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 основной функции 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 |