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

Статья
02/29/2024

Функция KsAllocateDeviceHeader выделяет и инициализирует необходимый заголовок расширения устройства.

Синтаксис

KSDDKAPI NTSTATUS KsAllocateDeviceHeader(
  [out]          KSDEVICE_HEADER       *Header,
  [in]           ULONG                 ItemsCount,
  [in, optional] PKSOBJECT_CREATE_ITEM ItemsList
);

Параметры

[out] Header

Указывает на расположение, в котором возвращается указатель на инициализированный заголовок.

[in] ItemsCount

Указывает количество подэлементов в ItemsList. Значение должно быть равно нулю, если элемент ItemsList не передается.

[in, optional] ItemsList

Необязательный элемент. Указывает на структуру KSOBJECT_CREATE_ITEM для каждого подэлемента. Если подэлементы отсутствуют, это значение должно иметь значение NULL , а ItemsCount — ноль.

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

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

Функция KsAllocateDeviceHeader выделяет память для структуры KSDEVICE_HEADER устройства. Если заголовок больше не нужен, драйвер должен вызвать функцию KsFreeDeviceHeader , чтобы освободить выделенную память.

Если подобъекты существуют для данного устройства, драйвер должен перед вызовом KsAllocateDeviceHeader выделить буфер страничной или невыгружаемой памяти достаточного размера для хранения структуры 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

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