PFLT_NORMALIZE_NAME_COMPONENT_EX 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 tipo PFLT_NORMALIZE_NAME_COMPONENT_EX como normalizeNameComponentExCallback do driver de minifiltro rotina de retorno de chamada.

Sintaxe

PFLT_NORMALIZE_NAME_COMPONENT_EX PfltNormalizeNameComponentEx;

NTSTATUS PfltNormalizeNameComponentEx(
  [in]      PFLT_INSTANCE Instance,
  [in]      PFILE_OBJECT FileObject,
  [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] FileObject

Ponteiro para o objeto de arquivo para o arquivo cujo nome está sendo solicitado ou o arquivo que é o destino da operação IRP_MJ_SET_INFORMATION se o sinalizador de FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME estiver definido. Consulte o parâmetro sinalizadores de abaixo para obter mais informações.

[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. Se o sinalizador FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME estiver definido, FileObject representará o arquivo/diretório que é o destino da operação de IRP_MJ_SET_INFORMATION. Se o sinalizador FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME não estiver definido, FileObject representará o arquivo/diretório cujo nome está sendo solicitado.

[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

A principal diferença entre a rotina de retorno de chamada NormalizeNameComponentExCallback e a rotina de retorno de chamada NormalizeNameComponentCallback (do tipo PFLT_NORMALIZE_NAME_COMPONENT) é que o parâmetro NormalizeNameComponentExCallback de retorno de chamada dá suporte ao parâmetro de fileObject adicional. O objeto de arquivo (FileObject) pode ser usado pelo driver de minifiltro para recuperar a estrutura de TXN_PARAMETER_BLOCK para a operação em que o arquivo/diretório está participando chamando a rotina de IoGetTransactionParameterBlock. A estrutura de TXN_PARAMETER_BLOCK pode ser usada pelo driver de minifiltro para emitir suas próprias solicitações de criação no contexto da transação em que esse objeto de arquivo está participando.

Para registrar essa rotina de retorno de chamada, o driver de minifiltro armazena o endereço de uma rotina do tipo PFLT_NORMALIZE_NAME_COMPONENT_EX no NormalizeNameComponentExCallback 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.