File Name Management
© 2004 Microsoft Corporation. All rights reserved.
1
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
© 2004 Microsoft Corporation. All rights reserved.
2
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.
© 2004 Microsoft Corporation. All rights reserved.
3
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
© 2004 Microsoft Corporation. All rights reserved.
4
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
© 2004 Microsoft Corporation. All rights reserved.
5
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


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 a filter above provider has requested a name
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
© 2004 Microsoft Corporation. All rights reserved.
6
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;
© 2004 Microsoft Corporation. All rights reserved.
7
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
© 2004 Microsoft Corporation. All rights reserved.
8
Name Format Options

Caller specifies the type of name to get:

FLT_FILE_NAME_NORMALIZED



FLT_FILE_NAME_OPENED



Contains full path
May contain combination of short & long names
FLT_FILE_NAME_SHORT



Contains full path
All short names have been converted to long names
Does not contain any path/volume information
Contains the short name only
FltGetFileNameFormat()
© 2004 Microsoft Corporation. All rights reserved.
9
Name Query Options

Caller specifies how the name should be retrieved through the
query method:

FLT_FILE_NAME_QUERY_DEFAULT



FLT_FILE_NAME_QUERY_CACHE_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



Will check the cache, but will not query the file system if cache miss
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY


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
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()
© 2004 Microsoft Corporation. All rights reserved.
10
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
© 2004 Microsoft Corporation. All rights reserved.
11
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
© 2004 Microsoft Corporation. All rights reserved.
12
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
© 2004 Microsoft Corporation. All rights reserved.
13
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
© 2004 Microsoft Corporation. All rights reserved.
14
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
© 2004 Microsoft Corporation. All rights reserved.
15
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
© 2004 Microsoft Corporation. All rights reserved.
16
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


Characteristics that are tunneled:





Default – within 15 seconds
Long Name
Short Name
Object ID
Creation Time
Operations which may tunnel



Create file
Rename file
Create HardLink
© 2004 Microsoft Corporation. All rights reserved.
17
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
© 2004 Microsoft Corporation. All rights reserved.
18
Normalized Name



All short names expanded
Any extraneous :$DATA has been
removed from stream name
All mount points have been resolved
© 2004 Microsoft Corporation. All rights reserved.
19
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\”
© 2004 Microsoft Corporation. All rights reserved.
20
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\”
© 2004 Microsoft Corporation. All rights reserved.
21
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
© 2004 Microsoft Corporation. All rights reserved.
22
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\”
© 2004 Microsoft Corporation. All rights reserved.
23
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\”
© 2004 Microsoft Corporation. All rights reserved.
24
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
© 2004 Microsoft Corporation. All rights reserved.
25
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



© 2004 Microsoft Corporation. All rights reserved.
26