Expand Minimize

FltGetDestinationFileNameInformation routine

The FltGetDestinationFileNameInformation routine constructs a full destination path name for a file or directory that is being renamed or for which an NTFS hard link is being created.

Syntax


NTSTATUS FltGetDestinationFileNameInformation(
  _In_      PFLT_INSTANCE Instance,
  _In_      PFILE_OBJECT FileObject,
  _In_opt_  HANDLE RootDirectory,
  _In_      PWSTR FileName,
  _In_      ULONG FileNameLength,
  _In_      FLT_FILE_NAME_OPTIONS NameOptions,
  _Out_     PFLT_FILE_NAME_INFORMATION *RetFileNameInformation
);

Parameters

Instance [in]

Opaque instance pointer for a minifilter driver instance that is attached to the volume where the file resides.

FileObject [in]

Pointer to the file object for the file. This parameter is required and cannot be NULL.

RootDirectory [in, optional]

Link operations: If the link is to be created in the same directory as the file that is being linked to, or if the FileName parameter contains the full pathname for the link to be created, this parameter is NULL. Otherwise it is a handle for the directory where the link is to be created.

Rename operations: If the file is not being moved to a different directory, or if the FileName parameter contains the full pathname, this parameter is NULL. Otherwise it is a handle for the directory where the file resides after it is renamed.

FileName [in]

Link operations: Pointer to a wide-character string containing the name to be assigned to the newly created link.

Rename operations: Pointer to a wide-character string containing the new name for the file.

FileNameLength [in]

Length, in bytes, of the wide-character string that FileName points to.

NameOptions [in]

FLT_FILE_NAME_OPTIONS value containing flags that specify the format of the name information to be returned, as well as the query method that the Filter Manager is to use. This parameter is required and cannot be NULL.

Following are the name format flag values. Only one of the following flags can be specified.

ValueMeaning

FLT_FILE_NAME_NORMALIZED

The FileName parameter receives the normalized destination name for the file.

FLT_FILE_NAME_OPENED

The FileName parameter receives the destination name for the file, based on the name that was used when the file was opened. This file name is not normalized.

 

Note that FLT_FILE_NAME_SHORT is not a valid flag value for this parameter.

Following are the query method flag values. Only one of the following flags can be specified.

ValueMeaning

FLT_FILE_NAME_QUERY_DEFAULT

If it is not currently safe to query the file system for the file name, FltGetDestinationFileNameInformation does nothing. Otherwise, FltGetDestinationFileNameInformation queries the Filter Manager's name cache for the file name information. If the name is not found in the cache, FltGetDestinationFileNameInformation queries the file system and caches the result.

FLT_FILE_NAME_QUERY_CACHE_ONLY

FltGetDestinationFileNameInformation queries the Filter Manager's name cache for the file name information. FltGetDestinationFileNameInformation does not query the file system.

FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY

FltGetDestinationFileNameInformation queries the file system for the file name information. FltGetDestinationFileNameInformation does not query the Filter Manager's name cache, and does not cache the result of the file system query.

FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP

FltGetDestinationFileNameInformation queries the Filter Manager's name cache for the file name information. If the name is not found in the cache, and it is currently safe to do so, FltGetDestinationFileNameInformation queries the file system for the file name information and cache the result.

 

RetFileNameInformation [out]

Pointer to a caller-allocated variable that receives the address of a system-allocated FLT_FILE_NAME_INFORMATION structure containing the file name information. FltGetDestinationFileNameInformation allocates this structure from paged pool. This parameter is required and cannot be NULL.

Return value

FltGetDestinationFileNameInformation returns STATUS_SUCCESS or an appropriate NTSTATUS value such as one of the following:

Return codeDescription
STATUS_FLT_INVALID_NAME_REQUEST

This return value means one of the following:

  • FltGetDestinationFileNameInformation cannot get file name information if the TopLevelIrp field of the current thread is not NULL, because the resulting file system recursion could cause deadlocks or stack overflows. (For more information about this issue, see IoGetTopLevelIrp.)

  • FLT_FILE_NAME_SHORT was specified for the name format flag in the NameOptions parameter.

STATUS_INSUFFICIENT_RESOURCES

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

STATUS_INVALID_PARAMETER

An invalid value was specified for the NameOptions parameter. This is an error code.

STATUS_MOUNT_POINT_NOT_RESOLVED

The destination path name contains a mount point that resolves to a volume other than the one where the file resides. (Because a rename or hard-link-creation operation can only be performed within a volume and not across volumes, the operation fails.) This is an error code.

 

Remarks

FltGetDestinationFileNameInformation returns the file name information in either normalized or "opened file" format. For more information on these formats, see the FLT_FILE_NAME_INFORMATION structure.

The file object pointer that is passed for the FileObject parameter must be either the FileObject member of the FLT_RELATED_OBJECTS structure for the operation or the Data->Iopb->TargetFileObject pointer for the operation, where Data is the callback data structure for the operation (FLT_CALLBACK_DATA). The file object pointer cannot be the Data->Iopb->Parameters.SetFileInformation.FileObject member, because this field is not used uniformly across file systems.

If the user opened the file by using the file ID but does not have traverse privilege for the entire path, FltGetDestinationFileNameInformation returns only the portion of the path that the user has privilege for.

A rename or hard-link-creation operation can only be performed within a volume and not across volumes. Therefore, such an operation fails if the destination path name contains a mount point that resolves to a volume other than the one where the file resides. For more information about rename operations, see the FILE_RENAME_INFORMATION structure. For more information about hard-link creation operations, see the FILE_LINK_INFORMATION structures.

After a successful call to FltGetDestinationFileNameInformation, the caller is responsible for releasing the pointer returned in the RetFileNameInformation parameter when it is no longer needed by calling FltReleaseFileNameInformation.

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

In create, hard-link, and rename operations, file name tunneling can cause the final component in normalized file name information that a minifilter driver retrieves in a preoperation callback routine to be invalidated. If a minifilter driver retrieves normalized file name information in a preoperation callback (PFLT_PRE_OPERATION_CALLBACK) routine by calling a routine such as FltGetDestinationFileNameInformation, it must call FltGetTunneledName from its postoperation callback (PFLT_POST_OPERATION_CALLBACK) routine to retrieve the correct file name information for the file.

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

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)

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

Requirements

Header

Fltkernel.h (include Fltkernel.h)

Library

FltMgr.lib

IRQL

<= APC_LEVEL

See also

FILE_LINK_INFORMATION
FILE_RENAME_INFORMATION
FLT_CALLBACK_DATA
FLT_FILE_NAME_INFORMATION
FLT_FILE_NAME_OPTIONS
FLT_RELATED_OBJECTS
FltGetFileNameInformation
FltGetFileNameInformationUnsafe
FltGetTunneledName
FltParseFileNameInformation
FltReferenceFileNameInformation
FltReleaseFileNameInformation
IoGetTopLevelIrp
PFLT_POST_OPERATION_CALLBACK
PFLT_PRE_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft