CBFS Class

Properties   Methods   Events   Configuration Settings   Errors  

The CBFS class gives applications the ability to create a virtual filesystem.

Syntax

CBFS

Remarks

The CBFS class is used to create a virtual filesystem whose contents are stored and exposed in an application-defined manner. The CBFS class's unique and powerful event-based design gives applications the flexibility needed to support a wide range of use-cases, ranging from something as simple as translating filesystem calls to files and directories on another storage medium, to something as complex as generating the entire contents of the virtual filesystem on-the-fly based on some application-specific data source.

Getting Started

Each CBFS class instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the CBFS class if their use-case requires the creation of multiple virtual drives; the class's Tag property can be used to distinguish between instances during event handlers.

Here's how to get up and running:

  1. If the system driver hasn't been installed yet, call the Install method to do so. This only needs to be done once.
    • In production, the system driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
  2. Call the Initialize method to initialize the CBFS class. This must be done each time the application starts (if the application is using multiple CBFS class instances, only the first instance created should be used to call Initialize).
  3. Ensure that all of the necessary event handlers have been implemented. Some event handlers, such as OpenFile, ReadFile, GetFileInfo, EnumerateDirectory, etc; are mandatory and must be implemented by all applications (note that this is not an exhaustive list). Others are optional, and only need to be implemented when certain features are enabled. Please refer to the events' documentation for more information.
  4. Create a virtual drive by calling the CreateStorage method.
  5. Call the MountMedia method to "insert storage media" into the virtual drive. (This "media" can be changed at any time later using the UnmountMedia and MountMedia methods.)
  6. Create one or more Mounting Points for the virtual drive using the AddMountingPoint method. A mounting point can be a drive letter, a UNC path, or a directory on an existing NTFS-formatted drive.
  7. Later, the application can unmount the "media" from the virtual drive using the UnmountMedia method. At this point, the application could call the MountMedia method again to "insert different storage media".
  8. To delete the virtual drive entirely, call the DeleteStorage method.
  9. To uninstall the system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
    • In production, the system driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

AccessDeniedProcessCountThe number of records in the AccessDeniedProcess arrays.
AccessDeniedProcessDesiredAccessThe kind of access granted or denied.
AccessDeniedProcessIncludeChildrenWhether child processes are affected.
AccessDeniedProcessIdThe Id of the target process.
AccessDeniedProcessNameThe filename of the target process's executable.
AccessGrantedProcessCountThe number of records in the AccessGrantedProcess arrays.
AccessGrantedProcessDesiredAccessThe kind of access granted or denied.
AccessGrantedProcessIncludeChildrenWhether child processes are affected.
AccessGrantedProcessIdThe Id of the target process.
AccessGrantedProcessNameThe filename of the target process's executable.
ActiveWhether the class is active and handling OS requests.
FileCacheWhich file data cache implementation to use.
FileSystemNameThe name of the virtual filesystem.
FireAllOpenCloseEventsWhether to fire events for all file open/close operations, or just the first and last.
HandleAllFsctlsWhether to fire the Fsctl event for all FSCTL_* requests.
MaxFileNameLengthThe maximum filename length supported by the virtual filesystem.
MaxFilePathLengthThe maximum file path length supported by the virtual filesystem.
MaxFileSizeThe maximum file size supported by the virtual filesystem.
MetadataCacheEnabledWhether the metadata cache should be used.
MetadataCacheSizeThe size of the metadata cache.
MountingPointCountThe number of records in the MountingPoint arrays.
MountingPointAuthenticationIdThe Authentication ID used when creating the mounting point, if applicable.
MountingPointFlagsThe flags used to create the mounting point.
MountingPointNameThe mounting point name.
NonExistentFilesCacheEnabledWhether the nonexistent files cache should be used.
NonExistentFilesCacheSizeThe size of the nonexistent files cache.
OpenFilesCountThe number of records in the OpenFile arrays.
OpenFileHandleClosedWhether the handle to the file has been closed.
OpenFileNameThe name of the open file.
OpenFileProcessIdThe Id of the process that opened the file.
OpenFileProcessNameThe name of the process that opened the file.
OpenHandlesCountThe number of handles to filesystem objects in the virtual drive that are currently open.
OpenObjectsCountThe number of filesystem objects in the virtual drive that are currently open.
ProcessRestrictionsEnabledWhether process access restrictions are enabled.
SerializeAccessWhether non-intersecting operations against the same file should execute serially or in parallel.
SerializeEventsWhether events should be fired on a single worker thread, or many.
StorageCharacteristicsThe characteristic flags to create the virtual drive with.
StorageGUIDThe GUID to create the virtual drive with.
StoragePresentWhether a virtual drive has been created.
StorageTypeThe type of virtual drive to create.
SupportChangeTimeAttributeWhether the virtual filesystem supports the ChangeTime file attribute.
SupportLastAccessTimeAttributeWhether the virtual filesystem supports the LastAccessTime file attribute.
SupportODXReadWriteWhether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.
TagStores application-defined data specific to this instance of the class.
UseAlternateDataStreamsWhether the virtual filesystem supports alternate data streams.
UseCaseSensitiveFileNamesWhether the virtual filesystem is case-sensitive, or just case-preserving.
UseDirectoryEmptyCheckWhether the IsDirectoryEmpty event should be used.
UseDiskQuotasWhether the virtual filesystem supports disk quotas.
UseHardLinksWhether the virtual filesystem supports hard links.
UseReparsePointsWhether the virtual filesystem supports reparse points.
UseShortFileNamesWhether the virtual filesystem supports short (8.3) filenames.
UseWindowsSecurityWhether the virtual filesystem supports Windows' ACL-based security mechanisms.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

AddDeniedProcessAdds a rule that prevents a process from accessing the virtual drive.
AddGrantedProcessAdds a rule that allows a process to access the virtual drive.
AddMountingPointAdds a mounting point for the virtual drive.
CloseOpenedFilesSnapshotCloses the previously-created opened files snapshot.
ConfigSets or retrieves a configuration setting.
CreateOpenedFilesSnapshotCreates a snapshot of information about files that are currently open.
CreateStorageCreates the virtual drive.
DeleteStorageDeletes the virtual drive.
DisableRouteCacheDisable the automatic routing of requests to local files.
EnableRouteCacheEnable the automatic routing of requests to local files.
FileMatchesMaskChecks whether a particular file or directory name matches the specified mask.
GetDriverStatusRetrieves the status of the system driver.
GetHandleCreatorProcessIdRetrieves the Id of the process (PID) that opened the specified file handle.
GetHandleCreatorProcessNameRetrieves the name of the process that opened the specified file handle.
GetHandleCreatorThreadIdRetrieves the Id of the thread that opened the specified file handle.
GetHandleCreatorTokenRetrieves the security token associated with the process that opened the specified file handle.
GetModuleVersionRetrieves the version of a given product module.
GetOriginatorProcessIdRetrieves the Id of the process (PID) that initiated the operation.
GetOriginatorProcessNameRetrieves the name of the process that initiated the operation.
GetOriginatorThreadIdRetrieves the Id of the thread that initiated the operation.
GetOriginatorTokenRetrieves the security token associated with the process that initiated the operation.
InitializeInitializes the class.
InstallInstalls (or upgrades) the product's system drivers and/or helper DLL.
IsCBFSVolumeChecks whether the specified volume is powered by CBFS.
IsIconRegisteredChecks whether the specified icon is registered.
MountMediaMounts media in the virtual drive, making it accessible for reading and writing.
NotifyDirectoryChangeNotifies the OS that a file or directory has changed.
RegisterIconRegisters an icon that can be displayed as an overlay on the virtual drive in Windows Explorer.
ReleaseUnusedFilesInstructs the OS to release any files kept open by the cache manager.
RemoveDeniedProcessRemoves a rule that prevents a process from accessing the virtual drive.
RemoveGrantedProcessRemoves a rule that allows a process to access the virtual drive.
RemoveMountingPointRemoves a mounting point for the virtual drive.
ResetIconResets the virtual drive's icon back to default by deselecting the active overlay icon.
ResetTimeoutResets the timeout duration for the current event handler.
RouteToFileInstructs the class to route future requests directly to a given file.
SetIconSelects a registered overlay icon for display on the virtual drive in Windows Explorer.
ShutdownSystemShuts down or reboots the operating system.
UninstallUninstalls the product's system drivers and/or helper DLL.
UnmountMediaUnmounts media from the virtual drive.
UnregisterIconUnregisters an existing overlay icon.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

CanFileBeDeletedFires when the OS needs to know whether a file or directory can be deleted.
CleanupFileFires when the OS needs to clean up a file.
CloseDirectoryEnumerationFires when the OS is finished enumerating a directory's contents.
CloseFileFires when the OS needs to close a file.
CloseHardLinksEnumerationFires when the OS is finished enumerating a file's hard links.
CloseNamedStreamsEnumerationFires when the OS is finished enumerating a file's named streams.
CloseQuotasEnumerationFires when the OS is finished reading or updating quota information.
CreateFileFires when the OS wants to create a file or directory.
CreateHardLinkFires when the OS wants to create a new hard link to an existing file.
DeleteFileFires when the OS needs to delete a file or directory.
DeleteReparsePointFires when the OS wants to delete a reparse point from a file or directory.
EjectedFires when the media and virtual drive have been ejected.
EnumerateDirectoryFires when the OS wants to enumerate a directory's contents.
EnumerateHardLinksFires when the OS needs to enumerate a file's hard links.
EnumerateNamedStreamsFires when the OS needs to enumerate a file's named streams.
ErrorFires if an unhandled error occurs during an event.
FlushFileFires when the OS needs to flush an open file's data out to storage.
FsctlFires when the virtual filesystem receives a non-standard request (filesystem control code).
GetDefaultQuotaInfoFires when the OS needs the virtual drive's default quota information.
GetFileInfoFires when the OS needs information about a file or directory.
GetFileNameByFileIdFires when the class needs to translate a file Id to a file or directory path.
GetFileSecurityFires when the OS needs to read the Windows security attributes of a file or directory.
GetReparsePointFires when the OS wants to read a reparse point for a file or directory.
GetVolumeIdFire when the class needs the volume Id.
GetVolumeLabelFires when the OS needs the volume label.
GetVolumeObjectIdFires when the OS needs the volume object Id and extended information.
GetVolumeSizeFires when the OS needs information about the virtual drive's capacity and free space.
IoctlFires when the disk behind the virtual filesystem receives a non-standard request (I/O control code).
IsDirectoryEmptyFires when the OS needs to know whether a directory is empty.
LockFileFires when the OS needs to lock a range of bytes in a file.
MountFires after the class mounts media into the virtual drive, making it available.
OffloadReadFileFires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.
OffloadWriteFileFires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.
OpenFileFires when the OS wants to open a file or directory.
QueryQuotasFires when the OS needs to read quota information.
ReadFileFires when the OS needs to read data from an open file.
RenameOrMoveFileFires when the OS wants to rename or move a file or directory within the virtual filesystem.
SetAllocationSizeFires when the OS needs to set a file's allocation size.
SetDefaultQuotaInfoFires when the OS needs to set the virtual drive's default quota information.
SetFileAttributesFires when the OS needs to change the attributes of an open file or directory.
SetFileSecurityFires when the OS wants to change the Windows security attributes of a file or directory.
SetFileSizeFires when the OS needs to change the size of an open file.
SetQuotasFires when the OS needs to update quota information.
SetReparsePointFires when the OS wants to create or update a reparse point on a file or directory.
SetValidDataLengthFires when the OS needs to set a file's valid data length.
SetVolumeLabelFires when the OS wants to change the volume label.
SetVolumeObjectIdFires when the OS needs to set the volume object Id and extended information.
UnlockFileFires when the OS needs to unlock a range of bytes in a file.
UnmountFires after the class unmounts media from the virtual drive, making it unavailable.
WorkerThreadCreationFires just after a new worker thread is created.
WorkerThreadTerminationFires just before a worker thread is terminated.
WriteFileFires when the OS needs to write data to an open file.

Configuration Settings


The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.

AllowOriginatorBufferMappingWhether read file, write file, and enumerate directory requests may pass original buffers to event handlers.
AllowReadOutsideEofWhether read requests beyond the end of a file are surfaced, or automatically denied.
AsyncDeleteStorageNotificationsWhether system broadcasts for virtual drive deletion are sent asynchronously.
ClusterSizeThe cluster size to create the virtual drive with.
CorrectAllocationSizesWhether to perform automatic allocation size correction.
DeviceChangeBroadcastsEnabledWhether the user-mode API broadcasts WM_DEVICECHANGE messages.
FastRenameMoveWhether open files are closed and re-opened during a rename or move operation.
FileCachePolicyPurgeOnCloseWhether file data should be purged from the cache when the file is closed.
FileCachePolicyWriteThroughWhether file data should be written to storage as it is written to the cache.
FireSetFileSizeOnWriteWhether to fire SetFileSize before WriteFile if writing would expand the file.
ForceFileCloseWhether the driver should force files to close after the last handle to them is closed.
LoggingEnabledWhether extended logging is enabled.
MaxReadBlockSizeThe maximum buffer size allowed for the ReadFile event.
MaxWorkerThreadCountThe maximum number of worker threads to use to fire events.
MaxWriteBlockSizeThe maximum buffer size allowed for the WriteFile event.
MinWorkerThreadCountThe minimum number of worker threads to use to fire events.
SectorSizeThe sector size to create the virtual drive with.
USNJournalPolicyHow USN Journal requests should be handled.
UseProtectiveFSFilterWhether the CBFS Connect driver should use a filesystem filter to try and prevent deadlocks.
UserModeFileCacheSizeThe size of the user mode file data cache.
WorkerInitialStackSizeThe initial stack size to create worker threads with.
ZeroOriginatorBufferBeforeMappingWhether the allocated buffer should be zeroed before it's passed to the event handler.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 C++ Edition - Version 20.0 [Build 7545]