Función KsAllocateObjectHeader (ks.h)
La función KsAllocateObjectHeader inicializa el encabezado de contexto de archivo necesario.
Sintaxis
KSDDKAPI NTSTATUS KsAllocateObjectHeader(
[out] KSOBJECT_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList,
[in] PIRP Irp,
[in] const KSDISPATCH_TABLE *Table
);
Parámetros
[out] Header
Apunta a la ubicación asignada por el autor de la llamada en la que se devuelve un puntero al KSOBJECT_HEADER inicializado si se ejecuta correctamente.
[in] ItemsCount
Especifica el número de elementos de creación de objetos en itemsList que se van a agregar 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.
Valor devuelto
La función KsAllocateObjectHeader devuelve STATUS_SUCCESS si es correcta o STATUS_INSUFFICIENT_RESOURCES si no hay suficientes recursos disponibles para satisfacer la solicitud.
Comentarios
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 de KSOBJECT_HEADER y devuelve un puntero al encabezado en Header. Los controladores no deben intentar liberar la memoria en sí, 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 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.
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Encabezado | ks.h (incluye Ks.h) |
| Library | Ks.lib |
| IRQL | < DISPATCH_LEVEL |