File Name Management

1. File Name Management © 2004 Microsoft Corporation. All rights reserved.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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 © 2004 Microsoft Corporation. All rights reserved.

7. 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.

8. 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.

9. 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() © 2004 Microsoft Corporation. All rights reserved.

10. 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() © 2004 Microsoft Corporation. All rights reserved.

11. 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.

12. 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.

13. 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.

14. 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.

15. 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.

16. 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.

17. 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 © 2004 Microsoft Corporation. All rights reserved.

18. 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.

19. 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.

20. 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.

21. 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.

22. 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.

23. 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.

24. 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.

25. 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_FOUNDif there is no short name for this file © 2004 Microsoft Corporation. All rights reserved.

26. Short Name Example \Device\HarddiskVolume1\Documents and Settings\MyUser\My Documents\TestResults.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.