ALLOCATE_FUNCTION_EX função de retorno de chamada (wdm.h)

A rotina LookasideListAllocateEx aloca o armazenamento para uma nova entrada de lista lookaside quando um cliente solicita uma entrada de uma lista lookaside vazia.

Sintaxe

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parâmetros

[in] PoolType

Especifica o tipo de armazenamento a ser alocado para a nova entrada lookaside-list. O chamador define esse parâmetro como um valor de enumeração POOL_TYPE válido e, possivelmente, ORs bit a bit com um dos seguintes bits de sinalizador:

  • POOL_RAISE_IF_ALLOCATION_FAILURE
  • POOL_QUOTA_FAIL_INSTEAD_OF_RAISE
Para obter mais informações sobre o sinalizador POOL_RAISE_IF_ALLOCATION_FAILURE, consulte ExAllocatePoolWithTag. Para obter mais informações sobre o sinalizador POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, consulte ExAllocatePoolWithQuotaTag.

Se, na chamada ExInitializeLookasideListEx que inicializou a lista lookaside, o parâmetro Flags for zero, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe é o mesmo valor de parâmetro PoolType que foi passado para ExInitializeLookasideListEx.

Se, na chamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe é o OR bit a bit de POOL_RAISE_IF_ALLOCATION_FAILURE e o valor do parâmetro PoolType que foi passado para ExInitializeLookasideListEx. A rotina LookasideListAllocateEx pode passar seu valor de parâmetro PoolType , sem modificação, para a rotina ExAllocatePoolWithTag .

Se, na chamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe é o OR bit a bit de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE e o valor poolType que foi passado para ExInitializeLookasideListEx. A rotina LookasideListAllocateEx pode passar seu valor de parâmetro PoolType , sem modificação, para a rotina ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Especifica o tamanho, em bytes, da entrada lookaside-list a ser alocada.

[in] Tag

Especifica a marca de pool de quatro bytes a ser usada para marcar o armazenamento alocado para a nova entrada da lista lookaside. Para obter mais informações sobre marcas de pool, consulte a descrição do parâmetro Tag em ExAllocatePoolWithTag.

[in, out] Lookaside

Um ponteiro para uma estrutura LOOKASIDE_LIST_EX que descreve a lista lookaside. Essa estrutura foi inicializada anteriormente pela rotina ExInitializeLookasideListEx .

Valor retornado

LookasideListAllocateEx retorna um ponteiro para a entrada de lista lookaside alocada. Se a rotina não puder alocar uma entrada, ela retornará NULL.

Comentários

Um driver que cria uma lista lookaside pode implementar uma rotina LookasideListAllocateEx para alocar buffers dinamicamente para a lista. Um buffer que não está em uso é armazenado como uma entrada na lista. Todas as entradas em uma lista lookaside são buffers de um tamanho uniforme, que o driver especifica quando a lista é inicializada.

O driver fornece um ponteiro para uma rotina personalizada lookasideListAllocateEx como um parâmetro de entrada na chamada ExInitializeLookasideListEx que inicializa a lista lookaside. Se o driver definir esse parâmetro como NULL, a lista lookaside usará uma rotina de alocação padrão.

Um driver chama a rotina ExAllocateFromLookasideListEx para alocar uma entrada de uma lista lookaside. Se a lista estiver vazia (não contiver entradas), ExAllocateFromLookasideListExchamará LookasideListAllocateEx para alocar dinamicamente o armazenamento para uma nova entrada. LookasideListAllocateEx retornará um ponteiro para a entrada recém-alocada se a alocação for bem-sucedida. Caso contrário, ele retornará NULL.

Os parâmetros PoolType, NumberOfBytes, Tag e Lookaside contêm os mesmos valores que foram passados como parâmetros de entrada na chamada ExInitializeLookasideListEx que inicializou a lista lookaside.

A rotina LookasideListAllocateEx pode usar o parâmetro Lookaside para acessar dados de contexto privado que o driver associou à lista lookaside. Para obter mais informações, consulte o exemplo de código em ExInitializeLookasideListEx.

Para obter mais informações sobre listas lookaside, consulte Usando listas lookaside.

A rotina LookasideListAllocateEx é chamada no mesmo IRQL que a chamada para ExAllocateFromLookasideListEx que solicita a entrada. Para uma chamada que solicita uma entrada que reside na memória paged, o chamador deve estar executando IRQL <= APC_LEVEL. Para uma chamada que solicita uma entrada que reside na memória não paga, o chamador deve estar executando IRQL <= DISPATCH_LEVEL.

Exemplos

Para definir uma rotina de retorno de chamada LookasideListAllocateEx , primeiro você deve fornecer uma declaração de função que identifica o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada LookasideListAllocateEx nomeada MyLookasideListAllocateEx, use o tipo FREE_FUNCTION_EX conforme mostrado neste exemplo de código:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

O tipo de função FREE_FUNCTION_EX é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função FREE_FUNCTION_EX no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declareing Functions by Using Function Role Types for WDM Drivers. Para obter informações sobre Use_decl_annotations, consulte Anotar Comportamento da Função.

Requisitos

   
Cliente mínimo com suporte Com suporte no Windows Vista e versões posteriores do Windows.
Plataforma de Destino Desktop
Cabeçalho wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL Consulte a seção Observações.

Confira também

ExAllocateFromLookasideListEx

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTag

ExInitializeLookasideListEx

LOOKASIDE_LIST_EX

POOL_TYPE