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
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Cabeçalho | ks.h (inclua Ks.h) |
| Biblioteca | Ks.lib |
| IRQL | < DISPATCH_LEVEL |