Función KsAllocateDeviceHeader (ks.h)
La función KsAllocateDeviceHeader asigna e inicializa el encabezado de extensión de dispositivo necesario.
Sintaxis
KSDDKAPI NTSTATUS KsAllocateDeviceHeader(
[out] KSDEVICE_HEADER *Header,
[in] ULONG ItemsCount,
[in, optional] PKSOBJECT_CREATE_ITEM ItemsList
);
Parámetros
[out] Header
Apunta a la ubicación en la que se va a devolver un puntero al encabezado inicializado.
[in] ItemsCount
Especifica el número de subelementos del ItemsList. Debe ser cero si no se pasa un ItemsList.
[in, optional] ItemsList
Opcional. Apunta a una estructura KSOBJECT_CREATE_ITEM para cada subelemento. Si no hay subelementos, este valor debe ser NULL y ItemsCount debe ser cero.
Valor devuelto
La función KsAllocateDeviceHeader devuelve STATUS_SUCCESS si se ejecuta correctamente o STATUS_INSUFFICIENT_RESOURCES si no puede asignar los recursos necesarios.
Observaciones
La función KsAllocateDeviceHeader asigna memoria para la estructura de KSDEVICE_HEADER para un dispositivo. Cuando el encabezado ya no es necesario, el controlador debe llamar a la función KsFreeDeviceHeader para liberar la memoria asignada.
Si existen subobjetos para un dispositivo determinado, el controlador debe, antes de llamar a KsAllocateDeviceHeader, 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.
Requisitos
| Requisito | Valor |
|---|---|
| de la plataforma de destino de | Universal |
| encabezado de | ks.h (incluya Ks.h) |
| biblioteca de | Ks.lib |
| irQL | < DISPATCH_LEVEL |