Función KsAllocateObjectHeader (ks.h)
La función KsAllocateObjectHeader inicializa el encabezado de contexto de archivo necesario.
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
Apunta a la ubicación asignada por el autor de la llamada en la que se va a devolver un puntero al KSOBJECT_HEADER inicializado si se ejecuta correctamente.
[in] ItemsCount
Especifica el número de elementos de creación de objetos en el ItemsList que se agregarán al encabezado de objeto una vez asignado el encabezado. Este valor debe ser cero si itemsList es NULL.
[in, optional] ItemsList
Opcionalmente, especifica un puntero a un búfer asignado por el autor de la llamada que contiene una serie de estructuras de KSOBJECT_CREATE_ITEM que se van a agregar al encabezado de objeto. Debe establecerse en null si no hay ningún elemento de creación de objetos.
[in] Irp
Apunta al IRP, de la función principal IRP_MJ_CREATE, que contiene la información necesaria para completar la creación del encabezado de objeto.
[in] Table
Apunta a una tabla de distribución inicializada para este objeto de archivo.
La función KsAllocateObjectHeader devuelve STATUS_SUCCESS si se ejecuta correctamente o STATUS_INSUFFICIENT_RESOURCES si no hay suficientes recursos disponibles para satisfacer la solicitud.
Antes de llamar a esta rutina, el controlador debe asignar almacenamiento residente en el sistema para un KSDISPATCH_TABLE e inicializar la tabla de distribución. La memoria de esta tabla de distribución no se puede liberar hasta que se llame a KsFreeObjectHeader.
KsAllocateObjectHeader asigna la memoria para la estructura KSOBJECT_HEADER y devuelve un puntero al encabezado en Encabezado. Los controladores no deben intentar liberar la propia memoria, sino llamar a KsFreeObjectHeader cuando se hayan completado todas las operaciones que requieren este encabezado de objeto.
Si existen subobjetos para un dispositivo determinado, el controlador debe, antes de llamar a KsAllocateObjectHeader, asignar un búfer de memoria paginada o no paginada de tamaño suficiente para contener una estructura de KSOBJECT_CREATE_ITEM para cada subobjeto. Por ejemplo:
/* 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) ;
Los controladores no deben liberar la memoria asignada para el subobjeto KSOBJECT_CREATE_ITEM lista hasta después de llamar a KsFreeDeviceHeader. Si no lo hace, se puede producir una condición de comprobación de errores.
| Requisito | Valor |
|---|---|
| de la plataforma de destino de | Universal |
| encabezado de | ks.h (incluya Ks.h) |
| biblioteca de | Ks.lib |
| irQL | < DISPATCH_LEVEL |