CBFS Connect 2020 Python Edition

Questions / Feedback?

CBFS Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

class cbfsconnect.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 on_open_file, on_read_file, on_get_file_info, on_enumerate_directory, 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 create_storage method.
  5. Call the mount_media method to "insert storage media" into the virtual drive. (This "media" can be changed at any time later using the unmount_media and mount_media methods.)
  6. Create one or more Mounting Points for the virtual drive using the add_mounting_point 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 unmount_media method. At this point, the application could call the mount_media method again to "insert different storage media".
  8. To delete the virtual drive entirely, call the delete_storage 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.

access_denied_process_countThe number of records in the AccessDeniedProcess arrays.
access_denied_process_desired_accessThe kind of access granted or denied.
access_denied_process_include_childrenWhether child processes are affected.
access_denied_process_idThe Id of the target process.
access_denied_process_nameThe filename of the target process's executable.
access_granted_process_countThe number of records in the AccessGrantedProcess arrays.
access_granted_process_desired_accessThe kind of access granted or denied.
access_granted_process_include_childrenWhether child processes are affected.
access_granted_process_idThe Id of the target process.
access_granted_process_nameThe filename of the target process's executable.
activeWhether the class is active and handling OS requests.
file_cacheWhich file data cache implementation to use.
file_system_nameThe name of the virtual filesystem.
fire_all_open_close_eventsWhether to fire events for all file open/close operations, or just the first and last.
handle_all_fsctlsWhether to fire the Fsctl event for all FSCTL_* requests.
max_file_name_lengthThe maximum filename length supported by the virtual filesystem.
max_file_path_lengthThe maximum file path length supported by the virtual filesystem.
max_file_sizeThe maximum file size supported by the virtual filesystem.
metadata_cache_enabledWhether the metadata cache should be used.
metadata_cache_sizeThe size of the metadata cache.
mounting_point_countThe number of records in the MountingPoint arrays.
mounting_point_authentication_idThe Authentication ID used when creating the mounting point, if applicable.
mounting_point_flagsThe flags used to create the mounting point.
mounting_point_nameThe mounting point name.
non_existent_files_cache_enabledWhether the nonexistent files cache should be used.
non_existent_files_cache_sizeThe size of the nonexistent files cache.
open_files_countThe number of records in the OpenFile arrays.
open_file_handle_closedWhether the handle to the file has been closed.
open_file_nameThe name of the open file.
open_file_process_idThe Id of the process that opened the file.
open_file_process_nameThe name of the process that opened the file.
open_handles_countThe number of handles to filesystem objects in the virtual drive that are currently open.
open_objects_countThe number of filesystem objects in the virtual drive that are currently open.
process_restrictions_enabledWhether process access restrictions are enabled.
serialize_accessWhether non-intersecting operations against the same file should execute serially or in parallel.
serialize_eventsWhether events should be fired on a single worker thread, or many.
storage_characteristicsThe characteristic flags to create the virtual drive with.
storage_guidThe GUID to create the virtual drive with.
storage_presentWhether a virtual drive has been created.
storage_typeThe type of virtual drive to create.
support_change_time_attributeWhether the virtual filesystem supports the ChangeTime file attribute.
support_last_access_time_attributeWhether the virtual filesystem supports the LastAccessTime file attribute.
support_odx_read_writeWhether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.
tagStores application-defined data specific to this instance of the class.
use_alternate_data_streamsWhether the virtual filesystem supports alternate data streams.
use_case_sensitive_file_namesWhether the virtual filesystem is case-sensitive, or just case-preserving.
use_directory_empty_checkWhether the IsDirectoryEmpty event should be used.
use_disk_quotasWhether the virtual filesystem supports disk quotas.
use_hard_linksWhether the virtual filesystem supports hard links.
use_reparse_pointsWhether the virtual filesystem supports reparse points.
use_short_file_namesWhether the virtual filesystem supports short (8.3) filenames.
use_windows_securityWhether 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.

add_denied_processAdds a rule that prevents a process from accessing the virtual drive.
add_granted_processAdds a rule that allows a process to access the virtual drive.
add_mounting_pointAdds a mounting point for the virtual drive.
close_opened_files_snapshotCloses the previously-created opened files snapshot.
configSets or retrieves a configuration setting.
create_opened_files_snapshotCreates a snapshot of information about files that are currently open.
create_storageCreates the virtual drive.
delete_storageDeletes the virtual drive.
disable_route_cacheDisable the automatic routing of requests to local files.
enable_route_cacheEnable the automatic routing of requests to local files.
file_matches_maskChecks whether a particular file or directory name matches the specified mask.
get_driver_statusRetrieves the status of the system driver.
get_handle_creator_process_idRetrieves the Id of the process (PID) that opened the specified file handle.
get_handle_creator_process_nameRetrieves the name of the process that opened the specified file handle.
get_handle_creator_thread_idRetrieves the Id of the thread that opened the specified file handle.
get_handle_creator_tokenRetrieves the security token associated with the process that opened the specified file handle.
get_module_versionRetrieves the version of a given product module.
get_originator_process_idRetrieves the Id of the process (PID) that initiated the operation.
get_originator_process_nameRetrieves the name of the process that initiated the operation.
get_originator_thread_idRetrieves the Id of the thread that initiated the operation.
get_originator_tokenRetrieves 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.
is_cbfs_volumeChecks whether the specified volume is powered by CBFS.
is_icon_registeredChecks whether the specified icon is registered.
mount_mediaMounts media in the virtual drive, making it accessible for reading and writing.
notify_directory_changeNotifies the OS that a file or directory has changed.
register_iconRegisters an icon that can be displayed as an overlay on the virtual drive in Windows Explorer.
release_unused_filesInstructs the OS to release any files kept open by the cache manager.
remove_denied_processRemoves a rule that prevents a process from accessing the virtual drive.
remove_granted_processRemoves a rule that allows a process to access the virtual drive.
remove_mounting_pointRemoves a mounting point for the virtual drive.
reset_iconResets the virtual drive's icon back to default by deselecting the active overlay icon.
reset_timeoutResets the timeout duration for the current event handler.
route_to_fileInstructs the class to route future requests directly to a given file.
set_iconSelects a registered overlay icon for display on the virtual drive in Windows Explorer.
shutdown_systemShuts down or reboots the operating system.
uninstallUninstalls the product's system drivers and/or helper DLL.
unmount_mediaUnmounts media from the virtual drive.
unregister_iconUnregisters 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.

on_can_file_be_deletedFires when the driver needs to know whether a file or directory can be deleted.
on_cleanup_fileFires when the OS needs to clean up a file.
on_close_directory_enumerationFires when the OS is finished enumerating a directory's contents.
on_close_fileFires when the OS needs to close a file.
on_close_hard_links_enumerationFires when the OS is finished enumerating a file's hard links.
on_close_named_streams_enumerationFires when the OS is finished enumerating a file's named streams.
on_close_quotas_enumerationFires when the OS is finished reading or updating quota information.
on_create_fileFires when the OS wants to create a file or directory.
on_create_hard_linkFires when the OS wants to create a new hard link to an existing file.
on_delete_fileFires when the OS needs to delete a file or directory.
on_delete_reparse_pointFires when the OS wants to delete a reparse point from a file or directory.
on_ejectedFires when the media and virtual drive have been ejected.
on_enumerate_directoryFires when the OS wants to enumerate a directory's contents.
on_enumerate_hard_linksFires when the OS needs to enumerate a file's hard links.
on_enumerate_named_streamsFires when the OS needs to enumerate a file's named streams.
on_errorFires if an unhandled error occurs during an event.
on_flush_fileFires when the OS needs to flush an open file's data out to storage.
on_fsctlFires when the virtual filesystem receives a non-standard request (filesystem control code).
on_get_default_quota_infoFires when the OS needs the virtual drive's default quota information.
on_get_file_infoFires when the OS needs information about a file or directory.
on_get_file_name_by_file_idFires when the class needs to translate a file Id to a file or directory path.
on_get_file_securityFires when the OS needs to read the Windows security attributes of a file or directory.
on_get_reparse_pointFires when the OS wants to read a reparse point for a file or directory.
on_get_volume_idFire when the class needs the volume Id.
on_get_volume_labelFires when the OS needs the volume label.
on_get_volume_object_idFires when the OS needs the volume object Id and extended information.
on_get_volume_sizeFires when the OS needs information about the virtual drive's capacity and free space.
on_ioctlFires when the disk behind the virtual filesystem receives a non-standard request (I/O control code).
on_is_directory_emptyFires when the OS needs to know whether a directory is empty.
on_lock_fileFires when the OS needs to lock a range of bytes in a file.
on_mountFires after the class mounts media into the virtual drive, making it available.
on_offload_read_fileFires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.
on_offload_write_fileFires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.
on_open_fileFires when the OS wants to open a file or directory.
on_query_quotasFires when the OS needs to read quota information.
on_read_fileFires when the OS needs to read data from an open file.
on_rename_or_move_fileFires when the OS wants to rename or move a file or directory within the virtual filesystem.
on_set_allocation_sizeFires when the OS needs to set a file's allocation size.
on_set_default_quota_infoFires when the OS needs to set the virtual drive's default quota information.
on_set_file_attributesFires when the OS needs to change the attributes of an open file or directory.
on_set_file_securityFires when the OS wants to change the Windows security attributes of a file or directory.
on_set_file_sizeFires when the OS needs to change the size of an open file.
on_set_quotasFires when the OS needs to update quota information.
on_set_reparse_pointFires when the OS wants to create or update a reparse point on a file or directory.
on_set_valid_data_lengthFires when the OS needs to set a file's valid data length.
on_set_volume_labelFires when the OS wants to change the volume label.
on_set_volume_object_idFires when the OS needs to set the volume object Id and extended information.
on_unlock_fileFires when the OS needs to unlock a range of bytes in a file.
on_unmountFires after the class unmounts media from the virtual drive, making it unavailable.
on_worker_thread_creationFires just after a new worker thread is created.
on_worker_thread_terminationFires just before a worker thread is terminated.
on_write_fileFires 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.
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.
FlushFileBeforeUnlockWhether file buffers are flushed before completion of UnlockFile operation.
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.
NrDeviceQueryInfoHandlingWhether the network redirector module should respond to file-specific requests sent to non-file entries.
SectorSizeThe sector size to create the virtual drive with.
SupportPosixStyleDeletionWhether the driver should close all open handles to a file being deleted.
SupportSearchIndexerSpecifies whether the driver must take additional measures to support indexing by Windows Search.
SupportUnlockAllRequestsWhether the driver should fire the UnlockFile event for IRP_MN_UNLOCK_ALL requests or process them internally.
SynchronousCleanupFileWhether the driver should perform cleanup operations synchronously.
TranslateDOSCharsInEnumMasksWhether the DOS wildcard characters should be translated during search.
UnusedMetadataLifetimeThe time after which unused metadata cache entries are removed from the metadata cache.
UpdateFileMetadataOnOpenWhether the class should request file info and update internal records during file open.
UpdateLastWriteTimeOnContentsChangeWhether to fire SetFileAttributes when changes in file contents are made.
UseFileIdsWhether the virtual filesystem supports file IDs.
UseObjectIdsWhether the virtual filesystem supports volume object ID.
UseProtectiveFSFilterWhether the driver should use a filesystem filter to try and prevent deadlocks.
UserModeFileCacheSizeThe size of the user mode file data cache.
USNJournalPolicyHow USN Journal requests should be handled.
VolumeGuidNameThe GUID of the mounted volume.
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) 2022 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 Python Edition - Version 20.0 [Build 8348]