PFLT_NORMALIZE_NAME_COMPONENT_EX función de devolución de llamada (fltkernel.h)

Artículo
08/07/2023

Un controlador de minifiltro que proporciona nombres de archivo para la caché de nombres del administrador de filtros puede registrar una rutina de tipo PFLT_NORMALIZE_NAME_COMPONENT_EX como rutina de devolución de llamada normalizeNameComponentExCallback del controlador minifiltro.

Sintaxis

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

Puntero de instancia opaco para la instancia del controlador de minifiltro para la que está registrada esta rutina de devolución de llamada.

[in] FileObject

Puntero al objeto de archivo para el archivo cuyo nombre se solicita o el archivo que es el destino de la operación de IRP_MJ_SET_INFORMATION si se establece la marca FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME. Consulte el parámetro Flags siguiente para obtener más información.

[in] ParentDirectory

Puntero a una estructura de UNICODE_STRING que contiene el nombre del directorio primario para este componente de nombre.

[in] VolumeNameLength

Longitud, en bytes, del nombre del directorio primario que se almacena en la estructura a la que apunta el parámetro ParentDirectory .

[in] Component

Puntero a una estructura de UNICODE_STRING que contiene el componente de nombre que se va a expandir.

[out] ExpandComponentName

Puntero a una estructura de FILE_NAMES_INFORMATION que recibe la información del nombre de archivo expandido (normalizado) para el componente de nombre.

[in] ExpandComponentNameLength

Longitud, en bytes, del búfer al que apunta el parámetro ExpandComponentName .

[in] Flags

Marcas de normalización de nombres. FLTFL_NORMALIZE_NAME_CASE_SENSITIVE especifica que el nombre que se va a normalizar distingue mayúsculas de minúsculas. FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME especifica que se ha llamado a la rutina de devolución de llamada para atender una llamada rutinaria FltGetDestinationFileNameInformation . Si se establece la marca FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME, FileObject representa el archivo o directorio que es el destino de la operación de IRP_MJ_SET_INFORMATION. Si no se establece la marca FLTFL_NORMALIZE_NAME_DESTINATION_FILE_NAME, FileObject representa el archivo o directorio cuyo nombre se solicita.

[in, out] NormalizationContext

Puntero a la información de contexto proporcionada por el controlador minifiltro que se pasará en las llamadas posteriores a esta rutina de devolución de llamada que se realizan para normalizar los componentes restantes en la misma ruta de acceso de nombre de archivo.

Valor devuelto

Esta rutina de devolución de llamada devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado. Si el componente de nombre que especifica el parámetro Component no existe en el directorio primario que especifica el parámetro ParentDirectory , esta rutina de devolución de llamada debe devolver STATUS_NO_SUCH_FILE. Si esta rutina de devolución de llamada emite una solicitud de IRP_MN_QUERY_DIRECTORY (FileNamesInformation) al directorio primario, el sistema de archivos devuelve el código de estado correcto. En esta situación, esta devolución de llamada simplemente puede devolver el código de estado que devuelve el sistema de archivos.

Comentarios

La diferencia principal entre la rutina de devolución de llamada NormalizeNameComponentExCallback y la rutina de devolución de llamada NormalizeNameComponentCallback (de tipo PFLT_NORMALIZE_NAME_COMPONENT) es que la rutina de devolución de llamada NormalizeNameComponentExCallback admite el parámetro FileObject adicional. El controlador minifiltro puede usar el objeto de archivo (FileObject) para recuperar la estructura de TXN_PARAMETER_BLOCK para la operación en la que participa el archivo o directorio llamando a la rutina IoGetTransactionParameterBlock . El controlador de minifiltro puede usar la estructura TXN_PARAMETER_BLOCK para emitir sus propias solicitudes de creación en el contexto de la transacción en la que participa este objeto de archivo.

Para registrar esta rutina de devolución de llamada, el controlador de minifiltro almacena la dirección de una rutina de tipo PFLT_NORMALIZE_NAME_COMPONENT_EX en el miembro NormalizeNameComponentExCallback de la estructura FLT_REGISTRATION que el controlador de minifiltro pasa como parámetro a FltRegisterFilter.

El administrador de filtros llama a esta rutina de devolución de llamada para consultar al controlador de minifiltro los nombres normalizados de los componentes de la ruta de acceso del nombre de archivo cuyos nombres ha modificado el controlador de minifiltro. Si la ruta de acceso del nombre de archivo contiene más de un componente de este tipo, el administrador de filtros puede llamar a esta rutina de devolución de llamada varias veces en el proceso de normalizar todos los componentes de la ruta de acceso. El controlador minifiltro puede usar el parámetro NormalizationContext para pasar información de contexto a las llamadas posteriores a esta rutina de devolución de llamada.

Si el controlador minifiltro usa el parámetro NormalizationContext , también debe registrar una rutina de devolución de llamada de limpieza del contexto de normalización. Para obtener más información, consulte la entrada de referencia para PFLT_NORMALIZE_CONTEXT_CLEANUP.