Función FltGetTunneledName (fltkernel.h)

Artículo
08/07/2023

La rutina FltGetTunneledName recupera el nombre tunelizado de un archivo, dado el nombre normalizado devuelto para el archivo por una llamada anterior a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation.

Sintaxis

NTSTATUS FLTAPI FltGetTunneledName(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  [out] PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Parámetros

[in] CallbackData

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

[in] FileNameInformation

Puntero a una estructura de FLT_FILE_NAME_INFORMATION que contiene información de nombre normalizada devuelta por una llamada anterior a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation para el archivo.

[out] RetTunneledFileNameInformation

Puntero a una variable asignada por el autor de la llamada que recibe la dirección de una estructura recién asignada que contiene el nombre de archivo tunelizado. Si no se encuentra ningún nombre tunelizado, esta variable recibe NULL. Este parámetro es obligatorio y no puede ser NULL en la entrada.

Valor devuelto

FltGetTunneledName devuelve STATUS_SUCCESS si se encuentra el nombre tunelizado o si no hay ningún nombre tunelizado para el archivo. De lo contrario, devuelve un valor NTSTATUS, como el siguiente:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	FltGetTunneledName encontró un error de asignación de grupo. Se trata de un código de error.

Comentarios

Los sistemas de archivos, como NTFS y FAT, usan una caché de túnel por volumen para conservar brevemente los nombres de archivo y otros metadatos de los archivos cuyo nombre se va a cambiar, vincular o eliminar. La tunelización de nombres de archivo puede hacer que el componente final de la información de nombre de archivo normalizada devuelta por una llamada de preoperación a FltGetFileNameInformation, FltGetFileNameUnsafe o FltGetDestinationFileNameInformation se invalide.

Si un controlador de minifiltro recupera información de nombre de archivo normalizada en la rutina de devolución de llamada de preoperación (PFLT_PRE_OPERATION_CALLBACK) para crear (IRP_MJ_CREATE), un vínculo físico (IRP_MJ_SET_INFORMATION con FILE_INFORMATION_CLASS establecido enFileRenameInformation) o la operación de cambio de nombre (IRP_MJ_SET_INFORMATION con FILE_INFORMATION_CLASS establecida en FileLinkInformation), debe llamar a FltGetTunneledName desde su rutina de devolución de llamada de postoperación (PFLT_POST_OPERATION_CALLBACK) para recuperar la información correcta del nombre de archivo del archivo.

Solo la información normalizada del nombre de archivo se ve afectada por la tunelización. El Administrador de filtros no puede asegurarse de que el componente final se normalice hasta que se haya producido la operación de creación, vínculo físico o cambio de nombre, ya que la tunelización puede hacer que se cambie un nombre corto a un nombre largo. Por lo tanto, un controlador de minifiltro debe llamar a FltGetTunneledName desde su rutina de devolución de llamada posterior a la operación para determinar si la información de nombre de archivo normalizada recuperada en la rutina de devolución de llamada de preoperación es válida.

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

Los controladores de minifiltro que solo recuperan información de nombre de archivo corto o abierto no deben llamar a FltGetTunneledName.

Después de llamar a FltGetFileNameInformation, FltGetFileNameInformationUnsafe o FltGetDestinationFileNameInformation en la rutina de devolución de llamada de preoperación, el controlador de minifiltro debe almacenar el puntero FileNameInformation devuelto en la estructura CompletionContext de la rutina de devolución de llamada de preoperación para que la devolución de llamada posterior a la operación pueda pasar este puntero en el parámetro FileNameInformation a FltGetTunneledName.

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)

Si no se encuentra ningún nombre tunelizado para el archivo, el parámetro RetTunneledFileNameInformation recibe NULL.

Después de una llamada correcta a FltGetTunneledName, el autor de la llamada es responsable de liberar los punteros RetTunneledFileNameInformation y FileNameInformation cuando ya no son necesarios llamando a FltReleaseFileNameInformation.

Solo se debe llamar a FltGetTunneledName desde una rutina de devolución de llamada posterior a la operación del controlador minifiltro para IRP_MJ_CREATE o IRP_MJ_SET_INFORMATION. Llamar a FltGetTunneledName desde una rutina de devolución de llamada de postoperación para cualquier otro tipo de operación de E/S, o llamarlo desde una rutina de devolución de llamada de preoperación, es un error de programación.

El autor de la llamada no debe modificar el contenido de la estructura devuelta en el parámetro RetTunneledFileNameInformation , ya que esta estructura está almacenada en caché por el Administrador de filtros para que todos los controladores de minifiltro puedan usarlo.

La tunelización de archivos permite la compatibilidad con programas que dependen de sistemas de archivos para conservar la metainformación de archivos durante un breve período de tiempo; por ejemplo, para el proceso de guardado seguro. La tunelización conserva la asociación entre el nombre largo y corto (8.3) de un archivo. Cuando se quita un nombre de archivo de un directorio (cambiar el nombre o eliminar), su par de nombres cortos y largos y el tiempo de creación se guardan en una caché de túnel, con clave por el nombre que se quitó. Cuando se agrega un nombre a un directorio (cambiar el nombre o crear), se busca la memoria caché para determinar si hay información que restaurar. La memoria caché es efectiva por instancia de un directorio. Si se elimina un directorio, se quita su memoria caché.