Función FltGetFileNameInformation (fltkernel.h)

Artículo
08/07/2023

La rutina FltGetFileNameInformation devuelve información de nombre para un archivo o directorio.

Sintaxis

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parámetros

[in] CallbackData

Puntero a una estructura de FLT_CALLBACK_DATA , que es la estructura de datos de devolución de llamada para la operación de E/S. Este parámetro es obligatorio y no puede ser NULL.

[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, así como el método de consulta que va a usar el Administrador de filtros. El llamador debe incluir una marca de formato de nombre y una marca de método de consulta. Los controladores de minifiltros del proveedor de nombres pueden usar marcas adicionales para especificar las opciones de consulta de nombres. Este parámetro es obligatorio y no puede ser NULL.

A continuación se muestran los valores de marca de formato de nombre de archivo. Solo se puede especificar una de las marcas siguientes. Para obtener una explicación de estos formatos, consulte FLT_FILE_NAME_INFORMATION.

Valor de marca de formato de nombre	Significado
FLT_FILE_NAME_NORMALIZED	El parámetro FileNameInformation recibe la dirección de una estructura que contiene el nombre normalizado del archivo.
FLT_FILE_NAME_OPENED	El parámetro FileNameInformation recibe la dirección de una estructura que contiene el nombre que se usó cuando se abrió el archivo.
FLT_FILE_NAME_SHORT	El parámetro FileNameInformation recibe la dirección de una estructura que contiene el nombre corto (8.3) del archivo. El nombre corto consta de hasta 8 caracteres, seguido inmediatamente de un punto y hasta 3 caracteres más. El nombre corto de un archivo no incluye el nombre del volumen, la ruta de acceso del directorio ni el nombre de la secuencia. No es válido en la ruta de acceso de creación previa.

A continuación se muestran los valores de marca del método de consulta de nombre de archivo. Solo se puede especificar una de las marcas siguientes.

Valor de marca de 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, FltGetFileNameInformation no hace nada. De lo contrario, FltGetFileNameInformation consulta la memoria caché de nombres del Administrador de filtros para obtener la información del nombre de archivo. Si el nombre no se encuentra en la memoria caché, FltGetFileNameInformation consulta el sistema de archivos y almacena en caché el resultado.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformation consulta la memoria caché de nombres del Administrador de filtros para obtener la información del nombre de archivo. FltGetFileNameInformation no consulta el sistema de archivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformation consulta el sistema de archivos para obtener la información del nombre de archivo. FltGetFileNameInformation 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	FltGetFileNameInformation consulta la memoria caché de nombres del Administrador de filtros para obtener la información del nombre de archivo. Si el nombre no se encuentra en la memoria caché y actualmente es seguro hacerlo, FltGetFileNameInformation consulta el sistema de archivos para obtener la información del nombre de archivo y almacena en caché el resultado.

Los minifiltros del proveedor de nombres usan las marcas siguientes para especificar las propiedades de las operaciones de nombre de archivo.

Valor de marca del proveedor de nombres	Significado
FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER	Un minifiltro de proveedor de nombres puede usar esta marca para especificar que se debe redirigir una solicitud de consulta de nombre a sí misma (el minifiltro del proveedor de nombres) en lugar de ser satisfecho por los proveedores de nombres inferiores en la pila.
FLT_FILE_NAME_DO_NOT_CACHE	Esta marca indica que el nombre recuperado de esta consulta no debe almacenarse en caché. Los minifiltros del proveedor de nombres usan esta marca a medida que realizan consultas intermedias para generar un nombre.
FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE	Un minifiltro de proveedor de nombres puede usar esta marca para especificar que es seguro consultar el nombre en la ruta de acceso posterior a la creación incluso si se devolvió STATUS_REPARSE. Es responsabilidad del autor de la llamada asegurarse de que no se cambió el campo FileObject-FileName>. No use esta marca con puntos de montaje o puntos de reanálisis de vínculos simbólicos.

[out] FileNameInformation

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. FltGetFileNameInformation asigna esta estructura del grupo paginado. Este parámetro es obligatorio y no puede ser NULL.

Valor devuelto

Si la información del nombre se devuelve correctamente, FltGetFileNameInformation devuelve STATUS_SUCCESS. De lo contrario, devuelve un valor NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_FLT_INVALID_NAME_REQUEST	FltGetFileNameInformation no puede obtener información de nombre de archivo en ninguna de las siguientes circunstancias si no se puede satisfacer la consulta desde la caché de nombres del Administrador de filtros: En la ruta de acceso de E/S de paginación. Cuando 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. (Para obtener más información sobre este problema, consulte IoGetTopLevelIrp). Una vez completada una operación de IRP_MJ_CLEANUP ; es decir, en la ruta de acceso posterior a la limpieza, el cierre previo o posterior (el objeto de archivo de destino tiene la marca FO_CLEANUP_COMPLETE establecida). En una rutina de devolución de llamada de preoperación (PFLT_PRE_OPERATION_CALLBACK) o postoperación (PFLT_POST_OPERATION_CALLBACK) para cualquiera de las siguientes operaciones: IRP_MJ_ACQUIRE_FOR_CC_FLUSH IRP_MJ_ACQUIRE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_CC_FLUSH IRP_MJ_RELEASE_FOR_MOD_WRITE IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION En una rutina de devolución de llamada de postoperación para IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION. Cuando todas las API están deshabilitadas; es decir, cuando KeAreAllApcsDisabled devuelve TRUE. FltGetFileNameInformation no puede obtener el nombre corto de un archivo en la ruta de acceso anterior a la creación. STATUS_FLT_INVALID_NAME_REQUEST es un código de error.
STATUS_INSUFFICIENT_RESOURCES	FltGetFileNameInformation encontró un error de asignación de grupo. Se trata de un código de error.
STATUS_INVALID_PARAMETER	Se devuelve cuando se pasa un parámetro no válido, como uno de los siguientes: El parámetro FileNameInformation no puede ser NULL. El parámetro CallbackData no puede ser NULL. STATUS_INVALID_PARAMETER es un código de error.
STATUS_FLT_NAME_CACHE_MISS	La información del nombre de archivo no se encuentra en la caché de nombres y NameOptions incluye FLT_FILE_NAME_QUERY_CACHE_ONLY. O bien La información del nombre de archivo no se encuentra en la memoria caché de nombres cuando NameOptions incluye FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP y no se puede consultar la información del nombre de archivo desde el sistema de archivos. Una llamada adicional a FltGetFileNameInformation con FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY establecido en NameOptions puede devolver la información del nombre de archivo.
STATUS_NOT_SAME_DEVICE	El archivo que se consulta durante la creación previa está en un volumen diferente al directorio primario. Este error se devuelve para las consultas de nombres normalizadas, donde el archivo era una unión o un vínculo simbólico que se resolvió en un volumen diferente.
STATUS_ACCESS_DENIED	Si el usuario abrió el archivo por identificador de archivo, pero no tiene privilegios de recorrido para toda la ruta de acceso, FltGetFileNameInformation produce un error con este valor devuelto. STATUS_ACCESS_DENIED es un código de error. O bien El archivo es un archivo del sistema con todo el acceso denegado.

Comentarios

FltGetFileNameInformation devuelve la información de nombre solicitada para el archivo o directorio que es el destino de la operación descrita por CallbackData, en el formato especificado. El sistema de archivos no necesita abrir el archivo o directorio todavía.

Para una operación de creación previa, si el miembro CallbackData-Iopb-OperationFlags>> contiene la marca bit a bit SL_OPEN_TARGET_DIRECTORY, FltGetFileNameInformation devuelve el nombre del directorio contenedor (primario) del archivo especificado. Este nombre es la ruta de acceso real que se abre la operación de creación.

Para analizar el contenido de la estructura FLT_FILE_NAME_INFORMATION devuelta por FltGetFileNameInformation, llame a FltParseFileNameInformation. (Para obtener más información sobre los formatos de nombre de archivo, vea FLT_FILE_NAME_INFORMATION).

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

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

Si se llama a FltGetFileNameInformation en la rutina de devolución de llamada de preoperación para una operación de creación para recuperar el nombre abierto, FltGetFileNameInformation se realiza correctamente incluso si la ruta de acceso al archivo que se abre no existe en el volumen.

Si se llama a FltGetFileNameInformation en la rutina de devolución de llamada de preoperación para una operación de creación para recuperar el nombre normalizado, FltGetFileNameInformation se realiza correctamente incluso si el componente final de la ruta de acceso al archivo que se abre no existe en el volumen.

Nota

Compatibilidad con el bloque de mensajes del servidor (SMB) para consultar nombres de archivo normalizados en un volumen remoto varía en diferentes versiones de Windows 10. Consulte el protocolo MS-SMB2 para obtener más información.

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 FltGetFileNameInformation, debe llamar a FltGetTunneledName desde su rutina de devolución de llamada posterior a la operación (PFLT_POST_OPERATION_CALLBACK) para recuperar la información de nombre de archivo correcta para el archivo.

Para Windows 8.1 y versiones anteriores, FltGetFileNameInformationsolo puede incluir un tipo de secuencia cuando se llama desde la devolución de llamada previa a la creación de un filtro. Para distinguir entre el flujo predeterminado de un archivo y los flujos de metadatos, esta llamada se debe realizar en la operación previa a la creación. El tipo de secuencia resultante seguirá siendo válido durante la vigencia del archivo.

Antes de Windows 8, el Administrador de filtros obtuvo el nombre normalizado de un archivo o directorio mediante la recopilación de la información de nombre de cada componente de la ruta de acceso del archivo. Esto requería varias consultas en el sistema de archivos para compilar la ruta de acceso completa. A partir de Windows 8, los sistemas de archivos locales admiten la clase de información de archivo FileNormalizedNameInformation y solo es necesaria una sola consulta para obtener el nombre normalizado. Es posible que los sistemas de archivos remotos no admitan la clase de información de archivo FileNormalizedNameInformation . Cuando este es el caso, se sigue necesitando una consulta para cada componente de la ruta de acceso del archivo para ensamblar el nombre normalizado. En determinadas condiciones de red, una consulta de nombre completo puede requerir una cantidad significativa de tiempo para completarse.

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

Nota

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 (vea Valor devuelto)