Reparse Points
For filesystems that support them, reparse points are essentially storage containers for some application-specific data associated with a file or directory. The format of the data held by a reparse point is in general determined by the application that stored it; the data is treated as opaque by the OS, which in turn delegates the interpretation of it to some filesystem filter. The notable exceptions are symbolic links and NFS links, implemented using reparse points and handled by the OS and a filesystem.
To assist the OS in determining which filesystem filter to use, each reparse point includes a reparse tag that uniquely identifies the data's format. When the filesystem encounters a reparse point, it attempts to find the filesystem filter associated with the data format identified by this tag. If a matching filesystem filter is found, it is invoked to process the file/directory using the reparse point's data.
Some reparse tags are predefined by Microsoft, while others are third-party-defined (though still assigned by Microsoft, to ensure uniqueness). All Microsoft-defined tags are listed in this MSDN article; there is no central list of third-party tags.
A complete reparse point (tag, data, etc.) is always represented as either a REPARSE_GUID_DATA_BUFFER structure, or (for certain Microsoft-reserved tags) a REPARSE_DATA_BUFFER structure. That said, the CBFS class interacts with reparse points in a very limited fashion, and its API exposes reparse point structures as nothing more than opaque blobs of data for the application to store and retrieve.
Reparse points are a powerful and complex feature of Windows filesystems; and for clarity and brevity, this overview omits many details not relevant to understanding how the CBFS class interacts with them. To learn more about reparse points, please refer to Microsoft's Reparse Point articles.
Supporting Reparse Points with CBFS
In CBFS, the UseReparsePoints property is used to indicate whether a virtual filesystem supports reparse points; it is disabled by default. When a virtual filesystem has reparse point support enabled, the associated CBFS-based application is responsible for storing reparse points created within the virtual filesystem.
When reparse point support is enabled, the following events must be handled by the class:
Here is a generalized flow for reparse point support:
- When a reparse point is created somewhere within the virtual filesystem, the SetReparsePoint event will fire. To properly handle this event, the application must store the data provided in the ReparseBuffer parameter in some persistent manner (note that this data should not replace other file/directory data, it should be stored in addition to such). In addition, it must record (in some manner) the fact that the file/directory specified by the event has a reparse point associated with it.
- Anytime information about a file/directory is requested via the EnumerateDirectory and/or GetFileInfo events, the application must check whether a reparse point is associated with it. If so, the FILE_ATTRIBUTE_REPARSE_POINT (0x00000400) flag must be included in the returned Attributes event parameter value.
- Anytime the OS encounters a file/directory with the aforementioned file attribute flag set, it will request the reparse point data before continuing so that it knows how to process the file/directory correctly. Such requests cause the GetReparsePoint event to fire, at which point the application must return the requested reparse point data.
- When a reparse point is deleted somewhere within the virtual filesystem, the DeleteReparsePoint event will fire. At this point, the application should delete the data it had stored for that reparse point, and should update its records for the file/directory accordingly (to indicate there is no longer a reparse point associated with it).
Please refer to each of the above events' documentation for more information about how to properly handle each one.