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

Consulte también

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader

KsFreeObjectHeader