Función FltGetDestinationFileNameInformation (fltkernel.h)

Artículo
12/04/2023

La rutina FltGetDestinationFileNameInformation consulta el nombre de archivo del directorio primario del destino y, a continuación, construye un nombre de ruta de acceso de destino completo para un archivo o directorio cuyo nombre se está cambiando o para el que se crea un vínculo físico NTFS.

Sintaxis

NTSTATUS FLTAPI FltGetDestinationFileNameInformation(
  [in]           PFLT_INSTANCE              Instance,
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] HANDLE                     RootDirectory,
  [in]           PWSTR                      FileName,
  [in]           ULONG                      FileNameLength,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Parámetros

[in] Instance

Puntero de instancia opaco para una instancia de controlador de minifiltro que está asociada al volumen donde reside el archivo.

[in] FileObject

Puntero al objeto de archivo del archivo. Este parámetro es obligatorio y no puede ser NULL.

[in, optional] RootDirectory

Para las operaciones de vínculo: Si el vínculo se va a crear en el mismo directorio que el archivo al que se va a vincular o si FileName contiene el nombre de ruta de acceso completo para el vínculo que se va a crear, este parámetro es NULL. De lo contrario, es un identificador para el directorio donde se va a crear el vínculo.

Para las operaciones de cambio de nombre: Si el archivo no se mueve a otro directorio o si FileName contiene el nombre de ruta de acceso completo, este parámetro es NULL. De lo contrario, es un identificador del directorio donde reside el archivo después de cambiar el nombre.

[in] FileName

Para las operaciones de vínculo: Puntero a una cadena de caracteres anchos que contiene el nombre que se va a asignar al vínculo recién creado.

Para las operaciones de cambio de nombre: Puntero a una cadena de caracteres anchos que contiene el nuevo nombre del archivo.

[in] FileNameLength

Longitud, en bytes, de la cadena de caracteres anchos a la que apunta FileName .

[in] NameOptions

Valor de FLT_FILE_NAME_OPTIONS que contiene marcas que especifican el formato de la información de nombre que se va a devolver, el método de consulta que va a usar el Administrador de filtros y marcas de nombre de archivo adicionales. Este parámetro es obligatorio y no puede ser NULL.

A continuación se muestran los valores de marca de formato de nombre. Solo se puede especificar una marca de formato de nombre. (Tenga en cuenta que FLT_FILE_NAME_SHORT no es un valor de marca válido para este parámetro).

Valor de marca de formato de nombre	Significado
FLT_FILE_NAME_NORMALIZED	El parámetro FileName recibe el nombre de destino normalizado del archivo.
FLT_FILE_NAME_OPENED	El parámetro FileName recibe el nombre de destino del archivo, según el nombre que se usó cuando se abrió el archivo. Este nombre de archivo no se normaliza.

A continuación se muestran los valores de la marca del método de consulta. Solo se puede especificar una marca de método de consulta.

Valor de marca del método de consulta	Significado
FLT_FILE_NAME_QUERY_DEFAULT	Si actualmente no es seguro consultar el sistema de archivos para el nombre de archivo de destino, FltGetDestinationFileNameInformation no hace nada. De lo contrario, FltGetDestinationFileNameInformation consulta la memoria caché de nombres del Administrador de filtros para obtener la información del nombre de archivo del directorio primario del destino y, a continuación, anexa el nombre de destino. Si el nombre resultante no se encuentra en la memoria caché, FltGetDestinationFileNameInformation consulta el sistema de archivos y almacena en caché el resultado.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetDestinationFileNameInformation consulta la caché de nombres del Administrador de filtros para obtener la información del nombre de archivo del directorio primario del destino y, a continuación, anexa el nombre de destino. No consulta el sistema de archivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetDestinationFileNameInformation consulta el sistema de archivos para obtener la información de nombre de archivo del directorio primario del destino y, a continuación, anexa el nombre de destino. No consulta la caché de nombres del Administrador de filtros y no almacena en caché el resultado de la consulta del sistema de archivos.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetDestinationFileNameInformation consulta la caché de nombres del Administrador de filtros para obtener la información del nombre de archivo del directorio primario del destino y, a continuación, anexa el nombre de destino. Si el nombre no se encuentra en la memoria caché y actualmente es seguro hacerlo, FltGetDestinationFileNameInformation consulta el sistema de archivos para obtener la información del nombre de archivo y almacena en caché el resultado.

A continuación se muestran los valores de marca de nombre de archivo. Se puede especificar cualquier combinación de estas marcas. (Tenga en cuenta que FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE no es una marca relevante para este parámetro, ya que FltGetDestinationFileNameInformation no se usa en una devolución de llamada posterior a la creación).

Valor de marca de nombre de archivo	Significado
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	FltGetDestinationFileNameInformation dirige la solicitud de nombre a la instancia de filtro que realiza la llamada para completarse.
FLT_FILE_NAME_DO_NOT_CACHE	FltGetDestinationFileNameInformation no almacena en caché el nombre de archivo recuperado. Los minifiltros de proveedor de nombres usan esta marca a medida que realizan consultas intermedias para generar un nombre.

[out] RetFileNameInformation

Puntero a una variable asignada por el autor de la llamada que recibe la dirección de una estructura de FLT_FILE_NAME_INFORMATION asignada por el sistema que contiene la información del nombre de archivo. FltGetDestinationFileNameInformation asigna esta estructura del grupo paginado. Este parámetro es obligatorio y no puede ser NULL.

Valor devuelto

FltGetDestinationFileNameInformation devuelve STATUS_SUCCESS o un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_FLT_INVALID_NAME_REQUEST	Este valor se devuelve por cualquiera de los siguientes motivos: (1) FltGetDestinationFileNameInformation no puede obtener información de nombre de archivo si el campo TopLevelIrp del subproceso actual no es NULL, porque la recursividad del sistema de archivos resultante podría provocar interbloqueos o desbordamientos de pila. (2) FLT_FILE_NAME_SHORT se especificó para la marca de formato de nombre en el parámetro NameOptions .
STATUS_INSUFFICIENT_RESOURCES	FltGetDestinationFileNameInformation encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_INVALID_PARAMETER	Se especificó un valor no válido para el parámetro NameOptions . Se trata de un código de error.
STATUS_MOUNT_POINT_NOT_RESOLVED	El nombre de la ruta de acceso de destino contiene un punto de montaje que se resuelve en un volumen distinto del que reside el archivo. (Dado que una operación de cambio de nombre o creación de vínculos físicos solo se puede realizar dentro de un volumen y no entre volúmenes, se produce un error en la operación). Se trata de un código de error.

Comentarios

Normalmente, los minifiltros llaman a FltGetDestinationFileNameInformation en una rutina de devolución de llamada de preoperación para una operación de cambio de nombre o creación de vínculos físicos, lo que significa que el nombre del archivo de destino probablemente no existe. El nombre de "destino" es:

Para un cambio de nombre de archivo, el nombre que tendrá el archivo si el cambio de nombre se realiza correctamente. Por ejemplo, al cambiar el nombre de name1 a name2, name2 es el nombre de destino.
Para una operación de creación de vínculos físicos, el nombre que se agrega al sistema de archivos. Por ejemplo, al agregar el nombre del vínculo físico2 al archivo existente denominado name1, name2 es el nombre de destino.

FltGetDestinationFileNameInformation devuelve la información del nombre de archivo de destino en formato normalizado o "archivo abierto". Para obtener más información sobre estos formatos, consulte la estructura FLT_FILE_NAME_INFORMATION .

El puntero de objeto de archivo que se pasa para el parámetro FileObject debe ser el miembro FileObject de la estructura FLT_RELATED_OBJECTS para la operación o el puntero Data-Iopb-TargetFileObject>> para la operación, donde Data es la estructura de datos de devolución de llamada para la operación (FLT_CALLBACK_DATA). El puntero del objeto de archivo no puede ser el miembro Data-Iopb-Parameters.SetFileInformation.FileObject>>, ya que este campo no se usa uniformemente en los sistemas de archivos.

Si el usuario abrió el archivo mediante el identificador de archivo, pero no tiene privilegios de recorrido para toda la ruta de acceso, FltGetDestinationFileNameInformation devuelve solo la parte de la ruta de acceso para la que el usuario tiene privilegios.

Una operación de cambio de nombre o creación de vínculos físicos solo se puede realizar dentro de un volumen y no entre volúmenes. Por lo tanto, se produce un error en esta operación si el nombre de la ruta de acceso de destino contiene un punto de montaje que se resuelve en un volumen distinto del que reside el archivo. Para obtener más información sobre las operaciones de cambio de nombre, consulte la estructura FILE_RENAME_INFORMATION . Para obtener más información sobre las operaciones de creación de vínculos físicos, consulte las estructuras de FILE_LINK_INFORMATION .

Después de una llamada correcta a FltGetDestinationFileNameInformation, el autor de la llamada es responsable de liberar el puntero devuelto en el parámetro RetFileNameInformation cuando ya no es necesario llamando a FltReleaseFileNameInformation.

El autor de la llamada no debe modificar el contenido de la estructura devuelta en el parámetro RetFileNameInformation , porque el Administrador de filtros almacena en caché esta estructura para que todos los controladores de minifiltro puedan usarlo.

En las operaciones de creación, vinculación y cambio de nombre, la tunelización de nombres de archivo puede hacer que se invalide el componente final en la información de nombre de archivo normalizada que un controlador de minifiltro recupera en una rutina de devolución de llamada de preoperación. Si un controlador de minifiltro recupera información de nombre de archivo normalizada en una rutina de devolución de llamada de preoperación (PFLT_PRE_OPERATION_CALLBACK) llamando a una rutina como FltGetDestinationFileNameInformation, debe llamar a FltGetTunneledName desde su rutina de devolución de llamada posterior a la operación para recuperar la información de nombre de archivo correcta para el archivo.

Para obtener más información sobre el nombre de archivo normalizado, vea FLT_FILE_NAME_INFORMATION.

La tunelización de nombres de archivo solo afecta a las operaciones de creación, vinculación y cambio de nombre de esta manera. No afecta a otras operaciones de E/S, como lectura y escritura.

Las siguientes operaciones emparejadas pueden hacer que el nombre del nombre de archivo se tunelizara: