© 2004 microsoft corporation. all rights reserved. 1 file name management

© 2004 Microsoft Corporation. All rights reserved. 1

File Name Management


What does Filter Manager’s Name Support Do?

Copy-free retrieval of file names Gets the name for a given file object

as appropriate for the current operation

Can get the name in one of three formats: Normalized name Opened name Short name


What does Filter Manager’s Name Support Do? (cont)

When possible, name is cached Allow caller to specify whether to

query cache or file system, just file system, or just cache

FltMgr manages when names are invalidated due to renames, hardlink creations, etc.


What does Filter Manager’s Name Support Do? (cont) The case of returned names may not

match how they are actually stored on disk

Support for filters that modify the name space Use the name provider interfaces to properly

work with Filter Manager’s name support Returned name information structures are

allocated from PagedPool Can not access them at DPC level


Performance Benefits

Cache is shared among all filters in the system Reduced duplication of name retrieval

work among filters When requesting a name, you get

a referenced counted structure containing the name No copying of the name is done


Name Provider Support Filters which affect the name space must register

additional callbacks so they see they can intercept the name query operations

PFLT_GENERATE_FILE_NAME Called when a filter above provider has requested a

name PFLT_NORMALIZE_NAME_COMPONENT

Called when a path component of name this filter has provided needs to be expanded to a long name

PFLT_NORMALIZE_CONTEXT_CLEANUP Called when all components in a path are normalized Name provider may need some context between path

components and this context allows that to be passed A name provider sample is coming


FLT_FILE_NAME_INFORMATION NOTE: Filter should NEVER modify any data in this

structure

typedef struct _FLT_FILE_NAME_INFORMATION {

USHORT Size;

FLT_FILE_NAME_PARSED_FLAGS NamesParsed;FLT_FILE_NAME_OPTIONS Format;

UNICODE_STRING Name; UNICODE_STRING Volume; UNICODE_STRING Share;

// Set by calling FltParseFileNameInformation() UNICODE_STRING Extension; UNICODE_STRING Stream; UNICODE_STRING FinalComponent; UNICODE_STRING ParentDir;

} FLT_FILE_NAME_INFORMATION, *PFLT_FILE_NAME_INFORMATION;


FLT_FILE_NAME_OPTIONS

Contains flags that are broken into 3 parts: Name format

Normalized, Opened, or Short Query method Control flags for name providers


Name Format Options Caller specifies the type of name to get:

FLT_FILE_NAME_NORMALIZED Contains full path All short names have been converted to long

names FLT_FILE_NAME_OPENED

Contains full path May contain combination of short & long names

FLT_FILE_NAME_SHORT Does not contain any path/volume information Contains the short name only

FltGetFileNameFormat()


Name Query Options Caller specifies how the name should be retrieved

through the query method: FLT_FILE_NAME_QUERY_DEFAULT

Cache or file system are only queried if it is safe to query the operating system

Get consistent behavior as to whether or not you can get the name, doesn’t rely on caching behavior

FLT_FILE_NAME_QUERY_CACHE_ONLY Will check the cache, but will not query the file system if cache

miss FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY

Will never look in cache (for testing purposes only) WARNING: Should avoid because of negative performance

impacts FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP

Regardless of whether it is safe to query file system, check cache for the name and return it if present

If not present query the file system if safe FltGetFileNameQueryMethod()


Name Query Flags Useful for filters that are name

providers since they may have to use the name routines to generate names

FLT_FILE_NAME_REQUEST_FROM_CURRENT_PROVIDER Name query request will come back to this

provider, not just the providers lower in the stack FLT_FILE_NAME_DO_NOT_CACHE

Tells the filter manager not to cache the results of this query


File Name Retrieval APIs FltGetFileNameInformation()

Given a CallbackData, retrieves the file name in the format requested for the TargetFileObject

Specify name format, query method via flags Will fail if detected that name query at current

call location will lead to system deadlock Name, Volume and Share components of

structure already parsed on return


File Name Retrieval APIs FltGetFileNameInformationUnsafe()

Given a FileObject and Instance, retrieves the file name in the format requested for the FileObject

Specify name format and query type – same as FltGetFileNameInformation()

Does not do additional checks to ensure against deadlock during name query

Name, Volume, Share components of structure already parsed on return


Parsing File Name API

FltParseFileNameInformation() Parses the remaining fields of the FLT_FILE_NAME_INFORMATION structure as necessary

Does not copy names, initializes existing UNICODE_STRINGS with address and length from the original full file name


Releasing Name Information Structures FltReleaseFileNameInformation()

Called when finished using a FLT_FILE_NAME_INFORMATION structure

A name information structure may be held from the preOperation callback

FltReferenceFileNameInformation() Adds reference to the name information

structure Call FltReleaseFileNameInformation() to

remove added reference


Destination Name Support API FltGetDestinationFileNameInformation()

Used during rename and hardlink creation to get the full name for the target file in the operation

Can retrieve normalized or opened name


Name Tunneling Preserves a set of file characteristics when a

file is removed and then quickly added back to the name space using the same name for both operations

Default – within 15 seconds Characteristics that are tunneled:

Long Name Short Name Object ID Creation Time

Operations which may tunnel Create file Rename file Create HardLink


Name Tunneling API FltGetTunneledName()

Used to get the tunneled name if tunneling occurred Needed for NORMALIZED names only Should be called from postOperation if:

a name was already retrieved during the preOperation you care that the preOperation name could be

invalidated by tunneling Names and operations that may be affected by name

tunneling: File name from pre-CREATE Destination name from pre-RENAME Destination name from pre-HARDLINK_CREATE


Normalized Name

All short names expanded Any extraneous :$DATA has been

removed from stream name All mount points have been

resolved


Normalized Name Example – Local File\Device\HarddiskVolume1\Documents and Settings\

MyUser\My Documents\Test Results.txt:stream1

Name: (above) Volume: “\Device\HarddiskVolume1” Share: NULL Extension: “.txt” Stream: “:stream1” FinalComponent: “Test Results.txt:stream1” ParentDir:

“\Documents and Settings\MyUser\My Documents\”


Normalized Name Example – Remote File\Device\LanManRedirector\mollybro-dev\c_drive\

Documents and Settings\MyUser\My Documents\Test Results.txt:stream1

Name: (above) Volume: “\Device\LanManRedirector” Share: “\mollybro-dev\c_drive” Extension: “.txt” Stream: “:stream1” FinalComponent: “Test Results.txt:stream1”

ParentDir: “\Documents and Settings\MyUser\My Documents\”


Opened Name

Get the name the user used to open this handle

Could have short or long names If a related file object is specified

Its name is expanded Its name and the original name are

concatenated together


Opened Name Example – Local File System\Device\HarddiskVolume1\Docume~1\MyUser\

My Documents\TestRe~1.txt:stream1

Name: (above) Volume: “\Device\HarddiskVolume1” Share: NULL Extension: “.txt” Stream: “:stream1” FinalComponent: “TestRe~1.txt:stream1” ParentDir:

“\Docume~1\MyUser\My Documents\”


Opened Name Example – Remote File System\Device\LanManRedirector\mollybro-dev\c_drive\

Docume~1\MyUser\My Documents\TestRe~1.txt:stream1

Name: (above) Volume: “\Device\LanManRedirector” Share: “\mollybro-dev\c_drive” Extension: “.txt” Stream: “:stream1” FinalComponent: “TestRe~1.txt:stream1” ParentDir:

“\Docume~1\MyUser\My Documents\”


Short Name Returns the short name for the final

component of the file object specified No path components are returned

Not available for unopened file objects, e.g., in Pre-CREATE operation

Not available for stream file objects Can still get STATUS_OBJECT_NAME_NOT_FOUND if there is no short name for this file


Short Name Example\Device\HarddiskVolume1\Documents and Settings\

MyUser\My Documents\Test Results.txt

Name: “TestRe~1.txt” Volume: NULL Share: NULL Extension: “.txt” Stream: NULL FinalComponent: “TestRe~1.txt” ParentDir: NULL