Função FltAllocateExtraCreateParameter (fltkernel.h)

Artigo
08/07/2023

A rotina FltAllocateExtraCreateParameter aloca o pool de memória paginada para uma estrutura de contexto ECP (parâmetro de criação extra) definida pelo usuário e gera um ponteiro para essa estrutura.

Sintaxe

NTSTATUS FLTAPI FltAllocateExtraCreateParameter(
  [in]           PFLT_FILTER                                    Filter,
  [in]           LPCGUID                                        EcpType,
  [in]           ULONG                                          SizeOfContext,
  [in]           FSRTL_ALLOCATE_ECP_FLAGS                       Flags,
  [in, optional] PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK CleanupCallback,
  [in]           ULONG                                          PoolTag,
  [out]          PVOID                                          *EcpContext
);

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] EcpType

Ponteiro para um GUID definido pelo usuário que indica o tipo da estrutura de contexto ECP. Consulte Usando GUIDs em drivers para obter mais informações.

[in] SizeOfContext

O tamanho, em bytes, da estrutura de contexto definida pelo usuário.

[in] Flags

Define as opções de alocação do pool. O seguinte descreve como o pool será alocado quando um ou mais dos valores de sinalizador listados forem combinados com o parâmetro Flags usando uma operação OR bit a bit:

FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL – o pool não paginado será alocado. Se esse valor de sinalizador não for usado, o pool paginado será alocado.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - Todo o pool alocado por essa rotina será cobrado em relação à cota de memória do processo atual.

Se mais de um sinalizador for usado, todos os efeitos associados aos valores de sinalizador utilizados ocorrerão.

[in, optional] CleanupCallback

Ponteiro opcional para uma rotina de retorno de chamada de limpeza definida por minifiltro do tipo PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. A rotina de retorno de chamada de limpeza é chamada quando a estrutura ECP (criada pela rotina FltAllocateExtraCreateParameter ) é excluída. Defina esse parâmetro como NULL se uma rotina de retorno de chamada de limpeza não for aplicável.

[in] PoolTag

Especifica a marca de pool para a memória alocada. Para obter mais informações, consulte o parâmetro Tag de ExAllocatePoolWithTag.

[out] EcpContext

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

Retornar valor

FltAllocateExtraCreateParameter pode retornar um dos seguintes valores:

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

Comentários

Por padrão, a rotina FltAllocateExtraCreateParameter aloca o pool de memória paginada para uma estrutura de contexto ECP definida pelo usuário. Se o FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL bitmask for usado conforme descrito acima, um pool de memória não paginado será alocado. Depois que esse pool tiver sido alocado e a estrutura de contexto ECP tiver sido inicializada, a rotina FltInsertExtraCreateParameter será usada para inserir a estrutura de contexto ECP (elemento de lista ECP) em uma estrutura de lista ECP (lista ECP).

O pool de memória alocado pela rotina FltAllocateExtraCreateParameter não é liberado automaticamente pelo sistema operacional. Esse pool de memória deve eventualmente ser liberado usando um dos seguintes métodos:

Chame a rotina FltRemoveExtraCreateParameter para remover a estrutura de contexto ECP da lista ECP e, em seguida, chame a rotina FltFreeExtraCreateParameter para liberar a própria estrutura de contexto ECP. A lista ECP permanece existente.
Chame a rotina FltFreeExtraCreateParameterList – isso libera a lista ECP, incluindo quaisquer elementos de lista (estruturas de contexto ECP). A lista de ECP é destruída.

No entanto, se um sistema de arquivos ou driver de filtro do sistema de arquivos anexar um ECP a um ECP_LIST existente ou recém-criado durante o processamento de uma solicitação de IRP_MJ_CREATE, esse ECP será limpo automaticamente quando o IRP for concluído. Como resultado, um driver de filtro não precisa limpo ECPs adicionados dinamicamente. Isso permite que o ECP de um driver de filtro seja propagado corretamente entre os pontos de nova análise – um processo que pode exigir que várias solicitações de IRP_MJ_CREATE sejam geradas.