Função FsRtlAllocateExtraCreateParameter (ntifs.h)

Artigo
12/21/2024

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

Sintaxe

NTSTATUS FsRtlAllocateExtraCreateParameter(
  [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] EcpType

Um ponteiro para um GUID 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.

[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 sinalizadores 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 de páginas será alocado.
FSRTL_ALLOCATE_ECPLIST_FLAG_CHARGE_QUOTA - Todo o pool alocado por FsRtlAllocateExtraCreateParameter será cobrado contra a 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 filtro do tipo PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK. A rotina de retorno de chamada de limpeza é chamada quando a estrutura ECP (criada pelo FsRtlAllocateExtraCreateParameter rotina) é excluída. Defina esse parâmetro para 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 alocar pool suficiente, o valor apontado por EcpContext será NULL e FsRtlAllocateExtraCreateParameter retornará o código de status STATUS_INSUFFICIENT_RESOURCES.

Valor de retorno

FltAllocateExtraCreateParameter retorna um código de status, como um dos seguintes:

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

Observações

Por padrão, a rotina FsRtlAllocateExtraCreateParameter aloca o pool de memória paged para uma estrutura de contexto ECP. Se a máscara de bits FSRTL_ALLOCATE_ECP_FLAG_NONPAGED_POOL for usada conforme descrito no parâmetro Flags, um pool de memória não paged será alocado. Depois que esse pool tiver sido alocado e a estrutura de contexto ECP tiver sido inicializada, a rotina FltInsertExtraCreateParameter é usada para inserir a estrutura de contexto ECP (elemento de lista ECP) em uma estrutura de lista ECP (ECP_LIST).

Se o chamador aloca ECP_LIST e um ou mais ECPs são usados em uma chamada para IoCreateFileEx, a descrição anterior está correta. Nesse caso, o sistema não libera nenhum dos ECPs, portanto, o chamador pode fazer várias chamadas para IoCreateFileEx com o mesmo conjunto de ECP. No entanto, se um driver de filtro do sistema de arquivos ou sistema de arquivos anexar um ECP a um ECP_LIST existente ou recém-criado durante o processamento de uma solicitação IRP_MJ_CREATE, esse ECP será limpo automaticamente quando o IRP for concluído. Como resultado, um driver de filtro não precisa limpar 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 IRP_MJ_CREATE sejam geradas.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	A rotina FsRtlAllocateExtraCreateParameter está disponível a partir do Windows Vista.
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (inclua Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL

Consulte também

ECP_LIST

FltAllocateExtraCreateParameterFromLookasideList

FltAllocateExtraCreateParameterList

FltCreateFileEx2

FltFreeExtraCreateParameter

FltFreeExtraCreateParameterList

FltGetEcpListFromCallbackData

FltInsertExtraCreateParameter

FltRemoveExtraCreateParameter

FltSetEcpListIntoCallbackData

IoCreateFileEx

PFSRTL_EXTRA_CREATE_PARAMETER_CLEANUP_CALLBACK

Compartilhar via