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

Artigo
08/07/2023

Um driver de minifiltro que fornece nomes de arquivo para o cache de nomes do gerenciador de filtros pode registrar uma rotina do tipo PFLT_NORMALIZE_NAME_COMPONENT_EX como a rotina de retorno de chamada NormalizeNameComponentExCallback do driver de minifiltro.

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 opaco para a instância de driver de minifiltro para a qual essa rotina de retorno de chamada está registrada.

[in] FileObject

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

[in] ParentDirectory

Ponteiro para uma estrutura 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 para a qual o parâmetro ParentDirectory aponta.

[in] Component

Ponteiro para uma estrutura 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 parâmetro ExpandComponentName aponta.

[in] Flags

Sinalizadores de normalização de nome. 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 a 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.

Retornar valor

Essa rotina de retorno de chamada retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado. Se o componente name 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 de 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 status que o sistema de arquivos retorna.

Comentários

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 a rotina de retorno de chamada NormalizeNameComponentExCallback dá suporte ao parâmetro FileObject adicional. O objeto de arquivo (FileObject) pode ser usado pelo driver de minifiltro para recuperar a estrutura TXN_PARAMETER_BLOCK para a operação em que o arquivo/diretório está participando chamando a rotina IoGetTransactionParameterBlock . A estrutura 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 membro NormalizeNameComponentExCallback 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 obter 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.