Función FltGetFileNameInformationUnsafe (fltkernel.h)

Artículo
08/07/2023

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

Sintaxis

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parámetros

[in] FileObject

Puntero a un objeto de archivo para el archivo o directorio. El objeto de archivo debe estar abierto actualmente. Este parámetro es obligatorio y no se puede establecer en NULL.

[in, optional] Instance

Puntero de instancia para el autor de la llamada. Este parámetro se puede establecer en 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. Este parámetro es obligatorio y no se puede establecer en NULL.

En la tabla siguiente se describen los valores de marca de formato de nombre. Solo se puede especificar una de las marcas. Para obtener más información sobre estos formatos, consulte FLT_FILE_NAME_INFORMATION.

Valor	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.

En la tabla siguiente se describen los valores de marca del método de consulta. Solo se puede especificar una de las marcas.

Valor	Significado
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe 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é, FltGetFileNameInformationUnsafe consulta el sistema de archivos y almacena en caché el resultado.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe consulta la memoria caché de nombres del Administrador de filtros para obtener la información del nombre de archivo. FltGetFileNameInformationUnsafe no consulta el sistema de archivos.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe consulta el sistema de archivos para obtener la información del nombre de archivo. FltGetFileNameInformationUnsafe 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	FltGetFileNameInformationUnsafe 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, FltGetFileNameInformationUnsafe consulta el sistema de archivos para obtener la información del nombre de archivo y almacena en caché el resultado.

[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. FltGetFileNameInformationUnsafe asigna esta estructura del grupo paginado. Cuando esta información ya no es necesaria, el autor de la llamada debe liberar la estructura llamando a FltReleaseFileNameInformation. Este parámetro es obligatorio y no se puede establecer en NULL.

Valor devuelto

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

Código devuelto	Descripción
STATUS_FLT_INVALID_NAME_REQUEST	El objeto de archivo al que apunta el parámetro FileObject no está abierto actualmente. Se trata de un código de error.
STATUS_INVALID_PARAMETER	Se pasó un valor no válido para el parámetro FileNameInformation . Se trata de un código de error.

Comentarios

La rutina FltGetFileNameInformationUnsafe se proporciona para que pueda consultar el nombre de un objeto de archivo fuera del contexto de una operación de E/S en ese objeto de archivo; De lo contrario, debe llamar a FltGetFileNameInformation.

A diferencia de la rutina FltGetFileNameInformation , FltGetFileNameInformationUnsafe no protege al autor de la llamada contra los siguientes tipos de circunstancias, donde consultar el sistema de archivos para obtener información de nombre puede provocar interbloqueos para métodos de consulta distintos de FLT_FILE_NAME_QUERY_CACHE_ONLY:

En la ruta de acceso de E/S de paginación.
Cuando el campo TopLevelIrp del subproceso actual no es NULL. Para más información, 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.

Para Windows Vista / Server 2008 y versiones posteriores, si un minifiltro aún no tiene una instancia de filtro, como en su rutina DriverEntry , puede usar NULL para el parámetro Instance . Esto permite que las rutinas DriverEntry accedan a la información del nombre de archivo. Excepto en este caso, se reserva un NULL valor para el parámetro de instancia para el uso del sistema.

En las operaciones de creación, vinculación y cambio de nombre, la tunelización de nombres de archivo puede invalidar 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 FltGetFileNameInformationUnsafe, 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 obtener más información sobre el nombre de archivo normalizado, vea FLT_FILE_NAME_INFORMATION.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	fltkernel.h (incluya Fltkernel.h)
Library	FltMgr.lib
Archivo DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (ver comentarios)