Función FltGetDestinationFileNameInformation (fltkernel.h)
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:
- delete(name)/create(name)
- delete(name)/rename(source, name)
- rename(name, newname)/create(name)
- rename(name, newname)/rename(source, name)
Requisitos
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Encabezado | fltkernel.h (incluya Fltkernel.h) |
| Library | FltMgr.lib |
| Archivo DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |
Consulte también
FltGetFileNameInformationUnsafe
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de