Função FltAllocateExtraCreateParameterList (fltkernel.h)

Artigo
08/07/2023

A rotina FltAllocateExtraCreateParameterList aloca memória de pool paginado para uma estrutura de lista de parâmetro de criação extra (ECP) e gera um ponteiro para essa estrutura.

Sintaxe

NTSTATUS FLTAPI FltAllocateExtraCreateParameterList(
  [in]  PFLT_FILTER                  Filter,
  [in]  FSRTL_ALLOCATE_ECPLIST_FLAGS Flags,
  [out] PECP_LIST                    *EcpList
);

Parâmetros

[in] Filter

Ponteiro de filtro opaco para o driver de minifiltro. Esse ponteiro identifica exclusivamente o driver de minifiltro e permanece constante desde que o driver de minifiltro seja carregado.

[in] Flags

Define as opções de alocação do pool. Se o sinalizador FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA for combinado com o parâmetro Flags usando uma operação OR bit a bit, qualquer pool alocado pela rotina será cobrado em relação à cota de memória do processo atual.

[out] EcpList

Recebe um ponteiro para uma estrutura de lista ECP inicializada. Se a rotina não conseguir alocar pool suficiente, *EcpList será NULL e a rotina retornará status código STATUS_INSUFFICIENT_RESOURCES.

Retornar valor

FltAllocateExtraCreateParameterList pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INSUFFICIENT_RESOURCES	FltAllocateExtraCreateParameterList não pôde alocar memória suficiente para uma estrutura de lista ECP. Nesse caso, EcpList será NULL*.
STATUS_SUCCESS	A estrutura de lista de ECP foi alocada e inicializada com êxito. Nesse caso, um ponteiro para a estrutura de lista inicializada é retornado no parâmetro *EcpList .

Comentários

Se o sistema operacional libera automaticamente a memória alocada por FltAllocateExtraCreateParameterList depende de quando FltAllocateExtraCreateParameterList é chamado, conforme mostrado nas seguintes situações:

Um chamador pode invocar FltAllocateExtraCreateParameterList para alocar o ECP_LIST e adicionar uma ou mais estruturas de contexto ECP antes que o chamador invoque a rotina FltCreateFileEx2 . Nessa situação, o sistema operacional não libera nenhuma das estruturas de contexto ECP. Portanto, o chamador pode fazer várias chamadas para FltCreateFileEx2 com o mesmo conjunto de ECP. Quando o chamador terminar com o ECP_LIST, o chamador deverá chamar a rotina FltFreeExtraCreateParameterList para liberar o ECP_LIST.
Enquanto um driver de filtro do sistema de arquivos processa uma solicitação de IRP_MJ_CREATE , o driver de filtro do sistema de arquivos pode chamar FltInsertExtraCreateParameter para anexar um ECP a um ECP_LIST existente. Se o ECP_LIST não existir, o chamador deverá chamar FltAllocateExtraCreateParameterList para criar o ECP_LIST. Nessa situação, o ECP_LIST e a estrutura de contexto ECP são limpos automaticamente pelo gerenciador de E/S quando a operação de criação é concluída. Isso permite que o ECP de um driver de filtro seja propagado corretamente no processamento de pontos de nova análise. Esse processo pode exigir que várias solicitações de IRP_MJ_CREATE sejam geradas.

Se o sinalizador FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA for usado com o parâmetro Flags , conforme descrito acima, um pool paginável normal será alocado. Caso contrário, um pool paginável será alocado usando uma lista lookaside interna.

estrutura ECP_LIST

ECP_LIST é uma estrutura opaca declarada pelo sistema operacional. ECP_LIST contém uma lista de entradas de parâmetro de criação extra (ECP).

A rotina FltAllocateExtraCreateParameterList deve ser usada para alocar memória para a estrutura ECP_LIST . A memória alocada por FltAllocateExtraCreateParameterList não é liberada automaticamente pelo sistema operacional; ele deve ser desalocado explicitamente chamando a rotina FltFreeExtraCreateParameterList . Observe que todos os elementos restantes da lista ECP serão liberados automaticamente quando FltFreeExtraCreateParameterList for chamado.

O tipo de dados PECP_LIST é usado para declarar um ponteiro para uma variável do tipo ECP_LIST.

Syntax

struct ECP_LIST {
  ;      // Reserved.
};

A estrutura ECP_LIST é declarada em Ntifs.h (inclua Ntifs.h).

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Essa rotina está disponível a partir do Windows Vista.
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
IRQL	<= APC_LEVEL