PFLT_NORMALIZE_NAME_COMPONENT função de retorno de chamada (fltkernel.h)

Artigo
02/06/2025

Um driver de minifiltro que fornece nomes de arquivo para o cache de nomes do gerenciador de filtros pode registrar uma rotina de PFLT_NORMALIZE_NAME_COMPONENT de tipo como normalizeNameComponentCallback do driver de minifiltro rotina.

Sintaxe

PFLT_NORMALIZE_NAME_COMPONENT PfltNormalizeNameComponent;

NTSTATUS PfltNormalizeNameComponent(
  [in]      PFLT_INSTANCE Instance,
  [in]      PCUNICODE_STRING ParentDirectory,
  [in]      USHORT VolumeNameLength,
  [in]      PCUNICODE_STRING Component,
  [out]     PFILE_NAMES_INFORMATION ExpandComponentName,
  [in]      ULONG ExpandComponentNameLength,
  [in]      FLT_NORMALIZE_NAME_FLAGS Flags,
  [in, out] PVOID *NormalizationContext
)
{...}

Parâmetros

[in] Instance

Ponteiro de instância opaca para a instância do driver de minifiltro para a qual essa rotina de retorno de chamada está registrada.

[in] ParentDirectory

Ponteiro para uma estrutura de UNICODE_STRING que contém o nome do diretório pai para esse componente de nome.

[in] VolumeNameLength

Comprimento, em bytes, do nome do diretório pai armazenado na estrutura à qual o parâmetro ParentDirectory aponta.

[in] Component

Ponteiro para uma estrutura de UNICODE_STRING que contém o componente de nome a ser expandido.

[out] ExpandComponentName

Ponteiro para uma estrutura de FILE_NAMES_INFORMATION que recebe as informações de nome de arquivo expandidas (normalizadas) para o componente de nome.

[in] ExpandComponentNameLength

Comprimento, em bytes, do buffer para o qual o ExpandComponentName parâmetro aponta.

[in] Flags

Nomear sinalizadores de normalização. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE especifica que o nome a ser normalizado diferencia maiúsculas de minúsculas. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME especifica que a rotina de retorno de chamada foi chamada para atender uma chamada de rotina FltGetDestinationFileNameInformation.

[in, out] NormalizationContext

Ponteiro para informações de contexto fornecidas pelo driver de minifiltro a serem passadas em todas as chamadas subsequentes para essa rotina de retorno de chamada que são feitas para normalizar os componentes restantes no mesmo caminho de nome de arquivo.

Valor de retorno

Essa rotina de retorno de chamada retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado. Se o componente de nome especificado pelo parâmetro Component não existir no diretório pai especificado pelo parâmetro ParentDirectory, essa rotina de retorno de chamada deverá retornar STATUS_NO_SUCH_FILE. Se essa rotina de retorno de chamada emitir uma solicitação IRP_MN_QUERY_DIRECTORY (FileNamesInformation) para o diretório pai, o sistema de arquivos retornará o código de status correto. Nessa situação, esse retorno de chamada pode simplesmente retornar o código de status que o sistema de arquivos retorna.

Observações

Para registrar essa rotina de retorno de chamada, o driver de minifiltro armazena o endereço de uma rotina de PFLT_NORMALIZE_NAME_COMPONENT de tipo no NormalizeNameComponentCallback membro da estrutura FLT_REGISTRATION que o driver de minifiltro passa como um parâmetro para FltRegisterFilter.

O gerenciador de filtros chama essa rotina de retorno de chamada para consultar o driver de minifiltro para os nomes normalizados para componentes no caminho do nome do arquivo cujos nomes o driver de minifiltro modificou. Se o caminho do nome do arquivo contiver mais de um desses componentes, o gerenciador de filtros poderá chamar essa rotina de retorno de chamada várias vezes no processo de normalização de todos os componentes no caminho. O driver de minifiltro pode usar o parâmetro NormalizationContext para passar informações de contexto para chamadas subsequentes para essa rotina de retorno de chamada.

Se o driver de minifiltro usar o parâmetro NormalizationContext, ele também deverá registrar uma rotina de retorno de chamada de limpeza de contexto de normalização. Para obter mais informações, consulte a entrada de referência para PFLT_NORMALIZE_CONTEXT_CLEANUP.