Expand Minimize

FltGetFileNameInformation routine

The FltGetFileNameInformation routine returns name information for a file or directory.

Syntax


NTSTATUS FltGetFileNameInformation(
  _In_   PFLT_CALLBACK_DATA CallbackData,
  _In_   FLT_FILE_NAME_OPTIONS NameOptions,
  _Out_  PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameters

CallbackData [in]

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

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. (Additional flags can be used by name provider minifilter drivers to specify name query options. For more information, see FLT_FILE_NAME_OPTIONS.) This parameter is required and cannot be NULL.

Following are the name format flag values. Only one of the following flags can be specified. (For an explanation of these formats, see FLT_FILE_NAME_INFORMATION.)

ValueMeaning

FLT_FILE_NAME_NORMALIZED

The FileNameInformation parameter receives the address of a structure containing the normalized name for the file.

FLT_FILE_NAME_OPENED

The FileNameInformation parameter receives the address of a structure containing the name that was used when the file was opened.

FLT_FILE_NAME_SHORT

The FileNameInformation parameter receives the address of a structure containing the short (8.3) name for the file. The short name consists of up to 8 characters, followed immediately by a period and up to 3 more characters. The short name for a file does not include the volume name, directory path, or stream name.

Not valid in the pre-create path.

 

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, FltGetFileNameInformation does nothing. Otherwise, FltGetFileNameInformation queries the Filter Manager's name cache for the file name information. If the name is not found in the cache, FltGetFileNameInformation queries the file system and caches the result.

FLT_FILE_NAME_QUERY_CACHE_ONLY

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

FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY

FltGetFileNameInformation queries the file system for the file name information. FltGetFileNameInformation 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

FltGetFileNameInformation 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, FltGetFileNameInformation queries the file system for the file name information and caches the result.

 

Name provider minifilters use the following flags to specify the properties of file name operations.

ValueMeaning

FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER

A name provider minifilter can use this flag to specify that a name query request should be redirected to itself (the name provider minifilter) rather than being satisfied by the name providers lower in the stack.

FLT_FILE_NAME_DO_NOT_CACHE

This flag denotes that the name retrieved from this query should not be cached. Name provider minifilters use this flag as they perform intermediate queries to generate a name.

FLT_FILE_NAME_ALLOW_QUERY_ON_REPARSE

A name provider minifilter can use this flag to specify that it is safe to query the name in the post-create path even if STATUS_REPARSE was returned. It is the caller's responsibility to ensure that the FileObject->FileName field was not changed. Do not use this flag with mount points or symbolic link reparse points.

This flag is available on Microsoft Windows Server 2003 SP1 and later. This flag is also available on Windows 2000 SP4 with Update Rollup 1 and later.

 

FileNameInformation [out]

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

Return value

If the name information is successfully returned, FltGetFileNameInformation returns STATUS_SUCCESS. Otherwise, it returns an appropriate NTSTATUS value such as one of the following:

Return codeDescription
STATUS_FLT_INVALID_NAME_REQUEST

One of the following:

  • FltGetFileNameInformation 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.)

  • FltGetFileNameInformation cannot get file name information in the paging I/O path.

  • FltGetFileNameInformation cannot get file name information in the post-close path.

  • FltGetFileNameInformation cannot get the short name of a file in the pre-create path.

STATUS_FLT_INVALID_NAME_REQUEST is an error code.

STATUS_INSUFFICIENT_RESOURCES

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

STATUS_INVALID_PARAMETER

One of the following:

  • The FileNameInformation parameter cannot be NULL.

  • The CallbackData parameter cannot be NULL.

STATUS_INVALID_PARAMETER is an error code.

STATUS_FLT_NAME_CACHE_MISS

The file name information is not found in the name cache and NameOptions includes FLT_FILE_NAME_QUERY_CACHE_ONLY.

-or-

The file name information is not found in the name cache when NameOptions includes FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP and the file name information cannot be queried from the file system.

An additional call to FltGetFileNameInformation with FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY set in NameOptions may return the file name information.

STATUS_ACCESS_DENIED

If the user opened the file by file ID but does not have traverse privileges for the entire path, FltGetFileNameInformation fails with this return value.

STATUS_ACCESS_DENIED is an error code.

-or-

The file is a system file with all access denied.

 

Remarks

FltGetFileNameInformation returns the requested name information for the file or directory that is represented by the file object that is the target of the I/O operation.

For a pre-create operation, if the CallbackData ->Iopb ->OperationFlags member contains the SL_OPEN_TARGET_DIRECTORY bitwise flag, FltGetFileNameInformation returns the name of the containing (parent) directory for the given file. This name is the actual path that the create operation opens.

To parse the contents of the FLT_FILE_NAME_INFORMATION structure returned by FltGetFileNameInformation, call FltParseFileNameInformation. (For more information about file name formats, see FLT_FILE_NAME_INFORMATION.)

After a successful call to FltGetFileNameInformation, the caller is responsible for releasing the pointer returned in the FileNameInformation parameter when the pointer is no longer needed. The caller does this by calling FltReleaseFileNameInformation.

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

If FltGetFileNameInformation is called in the preoperation callback routine for a create operation to retrieve the opened name, FltGetFileNameInformation succeeds even if the path to the file being opened does not exist on the volume. If FltGetFileNameInformation is called in the preoperation callback routine for a create operation to retrieve the normalized name, FltGetFileNameInformation succeeds even if the final component of the path to the file being opened does not exist on the volume.

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 FltGetFileNameInformation, it must call FltGetTunneledName from its postoperation callback (PFLT_POST_OPERATION_CALLBACK) routine to retrieve the correct file name information for the file.

Prior to Windows 8, Filter Manager obtained the normalized name for a file or directory by collecting the name information for each component of the file path. This required multiple queries to the file system to compile the complete path. Starting with Windows 8, local file systems support the FileNormalizedNameInformation file information class and only a single query is necessary to obtain the normalized name. Remote file systems may not support the FileNormalizedNameInformation file information class. When this is the case, a query for each component of the file path is still required to assemble the normalized name. Under certain network conditions, a full name query can require a significant amount of time to complete.

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

FLT_CALLBACK_DATA
FLT_FILE_NAME_INFORMATION
FLT_FILE_NAME_OPTIONS
FltGetDestinationFileNameInformation
FltGetFileNameInformationUnsafe
FltGetTunneledName
FltParseFileNameInformation
FltReferenceFileNameInformation
FltReleaseFileNameInformation
IoGetTopLevelIrp
PFLT_POST_OPERATION_CALLBACK
PFLT_PRE_OPERATION_CALLBACK

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft