Função KsAllocateDeviceHeader (ks.h)

A função KsAllocateDeviceHeader aloca e inicializa o cabeçalho de extensão do dispositivo necessário.

Sintaxe

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

Parâmetros

[out] Header

Aponta para o local no qual retornar um ponteiro para o cabeçalho inicializado.

[in] ItemsCount

Especifica o número de subitems na ItemsList. Isso deverá ser zero se um ItemsList não for passado.

[in, optional] ItemsList

Opcional. Aponta para uma estrutura de KSOBJECT_CREATE_ITEM para cada subitem. Se não houver subitens, esse valor deverá ser NULL e ItemsCount deverá ser zero.

Retornar valor

A função KsAllocateDeviceHeader retornará STATUS_SUCCESS se tiver êxito ou STATUS_INSUFFICIENT_RESOURCES se não for possível alocar os recursos necessários.

Comentários

A função KsAllocateDeviceHeader aloca memória para a estrutura KSDEVICE_HEADER para um dispositivo. Quando o cabeçalho não for mais necessário, o driver deverá chamar a função KsFreeDeviceHeader para liberar a memória alocada.

Se houver subobjetos para um determinado dispositivo, o driver deverá, antes de chamar KsAllocateDeviceHeader, alocar um buffer de memória paginada ou não paga de tamanho suficiente para manter uma estrutura KSOBJECT_CREATE_ITEM para cada subobjeto. Por exemplo:

/* 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) ;

Os drivers não devem liberar a memória alocada para a lista de KSOBJECT_CREATE_ITEM do subobjeto até depois de chamar KsFreeDeviceHeader. A falha ao fazer isso pode resultar em um bug marcar condição.

Requisitos

Confira também

KSOBJECT_CREATE_ITEM

KsFreeDeviceHeader