FltGetTunneledName routine

The FltGetTunneledName routine retrieves the tunneled name for a file, given the normalized name returned for the file by a previous call to FltGetFileNameInformation, FltGetFileNameInformationUnsafe, or FltGetDestinationFileNameInformation.

Syntax


NTSTATUS FltGetTunneledName(
  _In_  PFLT_CALLBACK_DATA         CallbackData,
  _In_  PFLT_FILE_NAME_INFORMATION FileNameInformation,
  _Out_ PFLT_FILE_NAME_INFORMATION *RetTunneledFileNameInformation
);

Parameters

CallbackData [in]

Pointer to the callback data structure for the I/O operation (FLT_CALLBACK_DATA). This parameter is required and cannot be NULL.

FileNameInformation [in]

Pointer to an FLT_FILE_NAME_INFORMATION structure containing normalized name information returned by a previous call to FltGetFileNameInformation, FltGetFileNameInformationUnsafe, or FltGetDestinationFileNameInformation for the file.

RetTunneledFileNameInformation [out]

Pointer to a caller-allocated variable that receives the address of a newly allocated structure containing the tunneled file name. If no tunneled name is found, this variable receives NULL. This parameter is required and cannot be NULL on input.

Return value

FltGetTunneledName returns STATUS_SUCCESS if the tunneled name is found or if there is no tunneled name for the file. Otherwise, it returns an NTSTATUS value, such as the following:

Return codeDescription
STATUS_INSUFFICIENT_RESOURCES

FltGetTunneledName encountered a pool allocation failure. This is an error code.

 

Remarks

File systems, such as NTFS and FAT, use a per-volume tunnel cache to briefly preserve file names and other metadata for files that are being renamed, linked to, or deleted. File name tunneling can cause the final component in normalized file name information returned by a preoperation call to FltGetFileNameInformation, FltGetFileNameInformationUnsafe, or FltGetDestinationFileNameInformation to be invalidated. If a minifilter driver retrieves normalized file name information in the preoperation callback routine (PFLT_PRE_OPERATION_CALLBACK) for a create, hard-link, or rename operation, it must call FltGetTunneledName from its postoperation callback routine (PFLT_POST_OPERATION_CALLBACK) to retrieve the correct file name information for the file.

Only normalized file name information is affected by tunneling. The Filter Manager cannot ensure that the final component is normalized until after the create, hard-link, or rename operation has actually occurred, because tunneling can cause a short name to be changed to a long name. Thus a minifilter driver must call FltGetTunneledName from its postoperation callback routine to determine whether the normalized file name information retrieved in the preoperation callback routine is valid.

For more information about normalized file name information, see FLT_FILE_NAME_INFORMATION.

Minifilter drivers that only retrieve short or opened file name information should not call FltGetTunneledName.

After calling FltGetFileNameInformation, FltGetFileNameInformationUnsafe, or FltGetDestinationFileNameInformation in the preoperation callback routine, the minifilter driver must store the returned FileNameInformation pointer in the preoperation callback routine's CompletionContext structure so that the postoperation callback can pass this pointer in the FileNameInformation parameter to FltGetTunneledName.

Note   File name tunneling affects only create, hard-link, and rename operations in this way. It does not affect other I/O operations, such as read and write.
 

The following paired operations can cause the file name name to be tunneled:

  • delete(name)/create(name)

  • delete(name)/rename(source, name)

  • rename(name, newname)/create(name)

  • rename(name, newname)/rename(source, name)

If no tunneled name is found for the file, the RetTunneledFileNameInformation parameter receives NULL.

After a successful call to FltGetTunneledName, the caller is responsible for releasing the RetTunneledFileNameInformation and FileNameInformation pointers when they are no longer needed by calling FltReleaseFileNameInformation.

FltGetTunneledName should only be called from a minifilter driver's postoperation callback routine for IRP_MJ_CREATE or IRP_MJ_SET_INFORMATION. Calling FltGetTunneledName from a postoperation callback routine for any other type of I/O operation, or calling it from a preoperation callback routine, is a programming error.

The caller must not modify the contents of the structure returned in the RetTunneledFileNameInformation parameter, because this structure is cached by the Filter Manager so that all minifilter drivers can use it.

For more information about file name tunneling, see Microsoft Knowledge Base Article 172190.

Requirements

Target platform

Universal

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

DLL

Fltmgr.sys

IRQL

<= APC_LEVEL

See also

FLT_CALLBACK_DATA
FLT_FILE_NAME_INFORMATION
FltGetDestinationFileNameInformation
FltGetFileNameInformation
FltGetFileNameInformationUnsafe
FltParseFileNameInformation
FltReferenceFileNameInformation
FltReleaseFileNameInformation
PFLT_POST_OPERATION_CALLBACK
PFLT_PRE_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show: