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 necesario y no se puede 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 autor de la llamada debe incluir una marca de formato de nombre y una marca de método de consulta. Los controladores de minifiltros de proveedor de nombres pueden usar marcas adicionales para especificar las opciones de consulta de nombres. Este parámetro es necesario y no se puede 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, vea 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, seguidos 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 anterior a la creación.

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 no se encuentra el nombre 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 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 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 de 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 estar 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 de 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 fileName>fileObject . No use esta marca con puntos de montaje ni puntos de reanálisis simbólicos de vínculo.

[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 necesario y no se puede null.

Valor devuelto

Si se devuelve correctamente la información de nombre, 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 cualquiera de las circunstancias siguientes 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 establecida la marca FO_CLEANUP_COMPLETE). 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 de no se puede 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 memoria caché de nombres y incluye FLT_FILE_NAME_QUERY_CACHE_ONLY. -o- La información del nombre de archivo no se encuentra en la memoria caché de nombres cuando nombreOpciones incluye FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP y la información del nombre de archivo no se puede consultar 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 de su directorio primario. Este error se devuelve para las consultas de nombre normalizadas, donde el archivo era una unión o 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- El archivo es un archivo del sistema con todo el acceso denegado.

Observaciones

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 aún el archivo o directorio.

Para una operación anterior a la creación, si el CallbackData->Iopb->OperationFlags miembro contiene la marca SL_OPEN_TARGET_DIRECTORY bit a bit, 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 de 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 la protocolo deMS-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 el componente final en la información normalizada del nombre de archivo que recupera un controlador de minifiltro en una rutina de devolución de llamada de preoperación se invalide. 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 de postoperació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, FltGetFileNameInformation puede incluir un tipo de secuencia de solo cuando se llama desde la devolución de llamada previa a la creación de un filtro. Para distinguir entre la secuencia predeterminada de un archivo y los flujos de metadatos, esta llamada se debe realizar en la operación anterior a la creación. El tipo de flujo 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 recopilando 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 de archivo nombre se tunelizará:

delete (nombre)/create(nombre)
delete (nombre)/rename( origen de, nombre)
rename (name, newname)/create(name)
rename (name, newname)/rename(source,name)

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
encabezado de	fltkernel.h (incluya Fltkernel.h)
biblioteca de	FltMgr.lib
DLL de	Fltmgr.sys
irQL	<= APC_LEVEL (vea Valor devuelto)