FltGetFileNameInformation function (fltkernel.h)

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

Syntax

NTSTATUS FLTAPI FltGetFileNameInformation(
  [in]  PFLT_CALLBACK_DATA         CallbackData,
  [in]  FLT_FILE_NAME_OPTIONS      NameOptions,
  [out] PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Parameters

[in] CallbackData

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

[in] NameOptions

A 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. The caller must include a name format flag and a query method flag. Additional flags can be used by name provider minifilter drivers to specify name query options. This parameter is required and cannot be NULL.

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

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

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

[out] FileNameInformation

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:

Remarks

FltGetFileNameInformation returns the requested name information for the file or directory that is the target of the operation described by CallbackData, in the specified format. The file or directory does not need to be opened yet by the file system.

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.

For Windows 8.1 and earlier, FltGetFileNameInformation can include a stream type only when called from a filter’s pre-create callback. To distinguish between a file’s default stream and metadata streams, this call should be made in the pre-create operation. The resulting stream type will remain valid across the lifetime of 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.

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)

Requirements

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