Função KsAllocateObjectHeader (ks.h)

A função KsAllocateObjectHeader inicializa o cabeçalho de contexto de arquivo necessário.

Sintaxe

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

Aponta para o local alocado pelo chamador no qual retornar um ponteiro para o KSOBJECT_HEADER inicializado se tiver êxito.

[in] ItemsCount

Especifica o número de itens de criação de objeto na ItemsList a ser adicionado ao cabeçalho do objeto depois que o cabeçalho é alocado. Esse valor deverá ser zero se ItemsList for NULL.

[in, optional] ItemsList

Opcionalmente, especifica um ponteiro para um buffer alocado pelo chamador que contém uma série de estruturas KSOBJECT_CREATE_ITEM a serem adicionadas ao cabeçalho do objeto. Deve ser definido como NULL se não houver itens de criação de objeto.

[in] Irp

Aponta para o IRP, da função principal IRP_MJ_CREATE, que contém as informações necessárias para concluir a criação do cabeçalho do objeto.

[in] Table

Aponta para uma tabela de expedição inicializada para este objeto de arquivo.

Retornar valor

A função KsAllocateObjectHeader retornará STATUS_SUCCESS se tiver êxito ou STATUS_INSUFFICIENT_RESOURCES se não houver recursos suficientes disponíveis para atender à solicitação.

Comentários

Antes de chamar essa rotina, o driver deve alocar o armazenamento residente do sistema para um KSDISPATCH_TABLE e inicializar a tabela de expedição. A memória dessa tabela de expedição não pode ser liberada até que KsFreeObjectHeader seja chamado.

KsAllocateObjectHeader aloca a memória para a estrutura KSOBJECT_HEADER e retorna um ponteiro para o cabeçalho em Header. Os drivers não devem tentar liberar a memória por conta própria, mas sim chamar KsFreeObjectHeader quando todas as operações que exigem esse cabeçalho de objeto forem concluídas.

Se houver subobjetos para um determinado dispositivo, o driver deverá, antes de chamar KsAllocateObjectHeader, 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 o subobjeto KSOBJECT_CREATE_ITEM lista 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

KsFreeObjectHeader