Struct cbfsconnect::CBFS

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

cbfsconnect::CBFS

Remarks

The CBFS struct is used to create a virtual filesystem whose contents are stored and exposed in an application-defined manner. The CBFS struct'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 struct instance controls a single virtual filesystem, and therefore a single virtual drive. Applications can use multiple instances of the CBFS struct if their use case requires the creation of multiple virtual drives; the struct'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 has not been installed yet, call the install method to do so. This needs to be done only 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 struct. This must be done each time the application starts (if the application is using multiple CBFS struct 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, and on_enumerate_directory are mandatory and must be implemented by all applications (this is not an exhaustive list). Others are optional, and only need to be implemented when certain features are enabled. Please refer to the event's 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.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSConnect. Due to this, the CBFS struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBFS when you have finished using the instance.

Property List


The following is the full list of the properties of the struct 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.
activeThis property specifies whether the struct is active and handling OS requests.
file_cacheThis property specifies which file data cache implementation to use.
file_system_nameThe name of the virtual filesystem.
fire_all_open_close_eventsThis property specifies whether to fire events for all file open/close operations, or just the first and last.
handle_all_fsctlsThis property specifies whether or not to fire the Fsctl event for all FSCTL_* requests.
max_file_name_lengthThis property includes the maximum file name length supported by the virtual filesystem.
max_file_path_lengthThis property includes the maximum file path length supported by the virtual filesystem.
max_file_sizeThis property includes the maximum file size supported by the virtual filesystem.
metadata_cache_enabledThis property specifies whether or not the metadata cache should be used.
metadata_cache_sizeThis property includes the 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_enabledThis property specifies whether or not the nonexistent files cache should be used.
non_existent_files_cache_sizeThis property includes the size of the nonexistent files cache.
open_files_countThe number of records in the OpenFile arrays.
open_file_handle_closedThis property reflects whether the handle to the file has been closed.
open_file_nameThis property reflects the name of the open file.
open_file_process_idThis property reflects the Id of the process that opened the file.
open_file_process_nameThis property reflects the name of the process that opened the file.
open_handles_countThis property includes the number of handles to filesystem objects in the virtual drive that are currently open.
open_objects_countThis property includes the number of filesystem objects in the virtual drive that are currently open.
process_restrictions_enabledWhether process access restrictions are enabled.
serialize_accessThis property specifies whether nonintersecting 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 (Windows only).
storage_guidThe GUID to create the virtual drive with.
storage_presentThis property specifies whether a virtual drive has been created.
storage_typeThe type of virtual drive to create (Windows only).
support_change_time_attributeThis property specifies whether the virtual filesystem supports the ChangeTime file attribute.
support_compressed_attributeThis property specifies whether the virtual filesystem supports the Compressed file attribute.
support_extended_attributesThis property specifies whether the virtual filesystem supports Extended Attributes of files and operations on them.
support_last_access_time_attributeThis property specifies whether the virtual filesystem supports the LastAccessTime file attribute.
support_odx_read_writeThis property specifies whether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.
support_sparse_file_attributeThis property specifies whether the virtual filesystem supports operations with sparse files.
tagThis property stores application-defined data specific to a particular instance of the struct.
use_alternate_data_streamsThis property specifies whether or not the virtual filesystem supports alternate data streams.
use_case_sensitive_file_namesThis property specifies whether the virtual filesystem is case-sensitive or just case-preserving.
use_directory_empty_checkThis property specifies whether the IsDirectoryEmpty event should be used.
use_disk_quotasThis property specifies whether the virtual filesystem supports disk quotas.
use_file_idsThis property specifies whether the virtual filesystem supports file Ids.
use_hard_linksThis property specifies whether the virtual filesystem supports hard links.
use_object_idsThis property specifies whether the virtual filesystem supports object Id operations.
use_reparse_pointsThis property specifies whether the virtual filesystem supports reparse points.
use_short_file_namesThis property specifies whether the virtual filesystem supports short (8.3) file names.
use_windows_securityThis property specifies whether the virtual filesystem supports Windows' ACL-based security mechanisms.

Method List


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

add_denied_processAdds a rule that prevents a process from accessing the virtual drive (Windows only).
add_granted_processAdds a rule that allows a process to access the virtual drive (Windows only).
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_storageThis method creates the virtual drive.
delete_storageThis method deletes the virtual drive.
disable_route_cacheThis method disables the automatic routing of requests to local files.
dispatch_eventsReserved, do not use.
enable_route_cacheThis method enables the automatic routing of requests to local files.
file_matches_maskThis method checks whether a particular file or directory name matches the specified mask.
flush_fileThis method flushes cached data of a file or its part.
get_driver_statusRetrieves the status of the system driver.
get_event_file_nameThis method retrieves the name of the file or directory, to which the event applies.
get_handle_creator_process_idThis method retrieves the Id of the process (PID) that opened the specified file handle.
get_handle_creator_process_nameThis method retrieves the name of the process that opened the specified file handle.
get_handle_creator_thread_idThis method retrieves the Id of the thread that opened the specified file handle.
get_handle_creator_tokenThis method retrieves 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 (Windows only).
get_originator_process_nameRetrieves the name of the process that initiated the operation (Windows only).
get_originator_thread_idRetrieves the Id of the thread that initiated the operation (Windows only).
get_originator_tokenRetrieves the security token associated with the process that initiated the operation (Windows only).
initializeThis method initializes the struct.
installInstalls (or upgrades) the product's system drivers and/or the helper DLL (Windows only).
is_cbfs_volumeThis method checks whether the specified volume is powered by CBFS.
is_icon_registeredChecks whether the specified icon is registered (Windows only).
mount_mediaThis method mounts media in the virtual drive, making it accessible for reading and writing.
notify_directory_changeThis method notifies 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 File Explorer (Windows only).
release_unused_filesThis method instructs 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 (Windows only).
remove_granted_processRemoves a rule that allows a process to access the virtual drive (Windows only).
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 (Windows only).
reset_timeoutThis method resets the timeout duration for the current event handler.
route_to_fileThis method instructs the struct to route future requests directly to a given file.
set_iconSelects a registered overlay icon for display on the virtual drive in Windows File Explorer (Windows only).
shutdown_systemShuts down or reboots the operating system.
uninstallUninstalls the product's system drivers and/or helper DLL (Windows only).
unmount_mediaThis method unmounts media from the virtual drive.
unregister_iconUnregisters an existing overlay icon (Windows only).

Event List


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

on_can_file_be_deletedThis event fires when the driver needs to know whether a file or directory can be deleted.
on_cleanup_fileThis event fires when the OS needs to clean up a file.
on_close_directory_enumerationThis event fires when the OS is finished enumerating a directory's contents.
on_close_fileThis event fires when the OS needs to close a file.
on_close_hard_links_enumerationThis event fires when the OS is finished enumerating a file's hard links.
on_close_named_streams_enumerationThis event fires when the OS is finished enumerating a file's named streams.
on_close_quotas_enumerationThis event fires when the OS is finished reading or updating quota information.
on_create_fileThis event fires when the OS wants to create a file or directory.
on_create_hard_linkThis event fires when the OS wants to create a new hard link to an existing file.
on_delete_fileThis event fires when the OS needs to delete a file or directory.
on_delete_object_idThis event fires when the OS needs to remove the object Id and extended information from a volume or a filesystem entry.
on_delete_reparse_pointThis event fires 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 (Windows only).
on_enumerate_directoryThis event fires when the OS wants to enumerate a directory's contents.
on_enumerate_hard_linksThis event fires when the OS needs to enumerate a file's hard links.
on_enumerate_named_streamsThis event fires when the OS needs to enumerate a file's named streams.
on_errorThis event fires if an unhandled error occurs during an event.
on_flush_fileThis event fires when the OS needs to flush an open file's data out to storage.
on_fsctlThis event fires when the virtual filesystem receives a nonstandard request (filesystem control code).
on_get_default_quota_infoThis event fires when the OS needs the virtual drive's default quota information.
on_get_file_infoThis event fires when the OS needs information about a file or directory.
on_get_file_name_by_file_idThis event fires when the struct needs to translate a file Id to a file or directory path.
on_get_file_securityThis event fires when the OS needs to read the Windows security attributes of a file or directory.
on_get_object_idThis event fires when the OS needs the object Id and extended information of a volume or a filesystem entry.
on_get_reparse_pointThis event fires when the OS wants to read a reparse point for a file or directory.
on_get_volume_idThis event fires when the struct needs the volume Id.
on_get_volume_labelThis event fires when the OS needs the volume label.
on_get_volume_sizeThis event fires when the OS needs information about the virtual drive's capacity and free space.
on_ioctlThis event fires when the disk behind the virtual filesystem receives a nonstandard request (I/O control code).
on_is_directory_emptyThis event fires when the OS needs to know whether a directory is empty.
on_lock_fileThis event fires when the OS needs to lock a range of bytes in a file.
on_mountThis event fires after the struct mounts media into the virtual drive, making it available.
on_offload_read_fileThis event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.
on_offload_write_fileThis event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.
on_open_fileThis event fires when the OS wants to open a file or directory.
on_query_allocated_rangesThis event fires when the OS needs to query valid ranges within a file.
on_query_compression_infoThis event fires when the OS needs to query the information about a compressed file.
on_query_eaThis event fires when the OS needs to query extended attributes of a file.
on_query_quotasThis event fires when the OS needs to read quota information.
on_read_fileThis event fires when the OS needs to read data from an open file.
on_rename_or_move_fileThis event fires when the OS wants to rename or move a file or directory within the virtual filesystem.
on_set_allocation_sizeThis event fires when the OS needs to set a file's allocation size.
on_set_default_quota_infoThis event fires when the OS needs to set the virtual drive's default quota information.
on_set_eaThis event fires when the OS needs to set extended attributes of a file.
on_set_file_attributesThis event fires when the OS needs to change the attributes of an open file or directory.
on_set_file_securityThis event fires when the OS wants to change the Windows security attributes of a file or directory.
on_set_file_sizeThis event fires when the OS needs to change the size of an open file.
on_set_object_idThis event fires when the OS needs to set the object Id and extended information of a volume or of a filesystem entry.
on_set_quotasThis event fires when the OS needs to update quota information.
on_set_reparse_pointThis event fires when the OS wants to create or update a reparse point on a file or directory.
on_set_valid_data_lengthThis event fires when the OS needs to set a file's valid data length.
on_set_volume_labelThis event fires when the OS wants to change the volume label.
on_unlock_fileThis event fires when the OS needs to unlock a range of bytes in a file.
on_unmountThis event fires after the struct 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_fileThis event fires when the OS needs to write data to an open file.
on_zeroize_file_rangeThis event fires when the OS needs to write a block of zeros to a file.

Config Settings


The following is a list of config settings for the struct 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.
AlwaysFireIsDirectoryEmptySpecifies whether the IsDirectoryEmpty event should fire even when the driver has the needed information.
AsyncDeleteStorageNotificationsWhether system broadcasts for virtual drive deletion are sent asynchronously.
CacheDuringLockGetSizeSpecifies whether the file size should be requested via the GetFileInfo event when a file is locked.
CacheDuringLockPurgeSpecifies the strategy of handling the cached data when a file is locked.
ClusterSizeThe cluster size to create the virtual drive with.
CorrectAllocationSizesWhether to perform automatic allocation size correction.
DockerContainerIdId of the running Docker container, in which the virtual drive should be created.
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.
ForceFileCloseDelaySpecifies the timeout between the closing of a last handle of a file and the moment the driver tries to close the file.
ImplicitAttributeUpdatesWhether SetFileAttributes fires when a file is modified.
LockRetryIntervalTime between repeated lock attempts.
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.
OmitEventFilenamesWhether the file name parameter should be empty in events.
SectorSizeThe sector size to create the virtual drive with.
StorageNamePrefixThe fixed prefix to use in device object names.
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 struct should request file info and update internal records during file open.
UpdateLastWriteTimeOnContentsChangeWhether to fire SetFileAttributes when changes in file contents are made.
UpdateMetadataOfOpenFilesWhether times and attributes returned by GetFileInfo replace existing information if a file is opened.
UseProtectiveFSFilterWhether the driver should use a filesystem filter to try and prevent deadlocks.
UserModeFileCacheSizeThe size of the user mode file data cache.
UserModeLockFirstDefines the order of file range locking, whether a kernel-mode lock goes before or after the LockFile event is fired.
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.

access_denied_process_count Property (CBFS Struct)

The number of records in the AccessDeniedProcess arrays.

Syntax

fn access_denied_process_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at access_denied_process_count - 1.

This property is read-only.

Data Type

i32

access_denied_process_desired_access Property (CBFS Struct)

The kind of access granted or denied.

Syntax

fn access_denied_process_desired_access(&self , AccessDeniedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

STG_DACCESS_READ0x00000001Grant/deny read access.

STG_DACCESS_WRITE0x00000002Grant/deny write access.

STG_DACCESS_READWRITE0x00000003Grant/deny read and write access.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only.

Data Type

i32

access_denied_process_include_children Property (CBFS Struct)

Whether child processes are affected.

Syntax

fn access_denied_process_include_children(&self , AccessDeniedProcessIndex : i32) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

Whether child processes are affected.

This property indicates whether the rule applies to children of the target process.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only.

Data Type

bool

access_denied_process_id Property (CBFS Struct)

The Id of the target process.

Syntax

fn access_denied_process_id(&self , AccessDeniedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by access_denied_process_process_name, or -1 if the rule applies to all processes.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only.

Data Type

i32

access_denied_process_name Property (CBFS Struct)

The filename of the target process's executable.

Syntax

fn access_denied_process_name(&self , AccessDeniedProcessIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

The filename of the target process's executable.

This property reflects the full file name of the target process's executable. Will be empty if the target process was specified by access_denied_process_process_id (or if the rule applies to all processes, in which case access_denied_process_process_id will be -1).

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only.

Data Type

String

access_granted_process_count Property (CBFS Struct)

The number of records in the AccessGrantedProcess arrays.

Syntax

fn access_granted_process_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at access_granted_process_count - 1.

This property is read-only.

Data Type

i32

access_granted_process_desired_access Property (CBFS Struct)

The kind of access granted or denied.

Syntax

fn access_granted_process_desired_access(&self , AccessGrantedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

STG_DACCESS_READ0x00000001Grant/deny read access.

STG_DACCESS_WRITE0x00000002Grant/deny write access.

STG_DACCESS_READWRITE0x00000003Grant/deny read and write access.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only.

Data Type

i32

access_granted_process_include_children Property (CBFS Struct)

Whether child processes are affected.

Syntax

fn access_granted_process_include_children(&self , AccessGrantedProcessIndex : i32) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

Whether child processes are affected.

This property indicates whether the rule applies to children of the target process.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only.

Data Type

bool

access_granted_process_id Property (CBFS Struct)

The Id of the target process.

Syntax

fn access_granted_process_id(&self , AccessGrantedProcessIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by access_granted_process_process_name, or -1 if the rule applies to all processes.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only.

Data Type

i32

access_granted_process_name Property (CBFS Struct)

The filename of the target process's executable.

Syntax

fn access_granted_process_name(&self , AccessGrantedProcessIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

The filename of the target process's executable.

This property reflects the full file name of the target process's executable. Will be empty if the target process was specified by access_granted_process_process_id (or if the rule applies to all processes, in which case access_granted_process_process_id will be -1).

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only.

Data Type

String

active Property (CBFS Struct)

This property specifies whether the struct is active and handling OS requests.

Syntax

fn active(&self ) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

This property reflects whether the struct is currently active and handling OS requests.

The property will be true once both create_storage and mount_media have been called.

This property is read-only.

Data Type

bool

file_cache Property (CBFS Struct)

This property specifies which file data cache implementation to use.

Syntax

fn file_cache(&self ) -> Result<i32, CBFSConnectError> 
fn set_file_cache(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies which file data cache implementation a virtual drive should use, if any. Possible values are as follows:

  • fcNone (0): Do not use file data caching.
  • fcSystem (1, default): Delegate file data caching to the Windows file management system cache (recommended).
  • fcInternalKernelMode (2): Use the CBFS kernel mode file data cache implementation.
  • fcInternalUserMode (3): Use the CBFS user mode file data cache implementation.
When the cache is enabled, commonly used file data will be cached to help reduce the number of times the on_read_file and on_write_file events are fired.

When set to fcInternalUserMode (3), the UserModeFileCacheSize configuration setting can be used to control the cache size.

Please refer to the Caching topic for detailed information on each of the cache implementations.

Note: This property cannot be changed within events.

Data Type

i32

file_system_name Property (CBFS Struct)

The name of the virtual filesystem.

Syntax

fn file_system_name(&self ) -> Result<String, CBFSConnectError> 
fn set_file_system_name(&self, value : String) -> Option<CBFSConnectError> fn set_file_system_name_ref(&self, value : &String) -> Option<CBFSConnectError>

Default Value

String::default()

Remarks

This property specifies the name of the virtual filesystem. Windows, and some other applications, use this name to identify the filesystem.

In general, the filesystem name can be any reasonable string up to 10 characters in length. However, some versions of Windows and some third-party programs may behave differently when they encounter an unknown filesystem name (i.e., anything other than FAT, FAT32, exFAT, NTFS, etc.). Applications should keep this restriction in mind when choosing a filesystem name.

This property is set to FAT32 by default, which may cause some applications to fail when attempting to copy large (>4GB) files to and from the virtual drive. It is recommended that applications set this property to exFAT if such issues occur.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

String

fire_all_open_close_events Property (CBFS Struct)

This property specifies whether to fire events for all file open/close operations, or just the first and last.

Syntax

fn fire_all_open_close_events(&self ) -> Result<bool, CBFSConnectError> 
fn set_fire_all_open_close_events(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies when the struct should fire the on_create_file/on_open_file and on_cleanup_file/on_close_file events.

When this property is disabled (default), the struct will not fire on_create_file/on_open_file for a file if another handle is already open for it. Similarly, the on_cleanup_file/on_close_file events will not be fired unless the handle being closed is the last handle open for the file in question. This behavior results in better overall performance because the number of event firings is minimized, but there are some drawbacks as well:

  • If the file is opened only for reading initially, and then another process opens it for writing, the application will not be notified about the new mode, and may not be prepared to respond to the "unexpected" on_write_file events that will arrive should the second process start writing to the file. (Such an application may be able to mitigate this issue by always opening the file data from the backend store in read-write mode.)
  • The HandleInfo parameter of various events has no effect; they carry handle-specific information that is not accessible to the application if this property is disabled.

When this property is enabled, the struct fires the on_create_file/on_open_file and on_cleanup_file/on_close_file events every time a file handle is opened or closed.

This table shows when events will fire based on how this property is set:

Operation on FileDisabledEnabled
1. Opened by process A X X
2. Opened by process B X
3. Closed by process B X
4. Opened by process C X
5. Closed by process A X
6. Closed by process C X X

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

handle_all_fsctls Property (CBFS Struct)

This property specifies whether or not to fire the Fsctl event for all FSCTL_* requests.

Syntax

fn handle_all_fsctls(&self ) -> Result<bool, CBFSConnectError> 
fn set_handle_all_fsctls(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies when the struct should fire the on_fsctl event. When disabled (default), the on_fsctl event will fire only for FSCTLs whose function codes are in the 2400-4096 range (these codes are reserved by CBFS Connect for application use). When enabled, this on_fsctl will fire for every FSCTL, except those processed by CBFS Connect itself.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

max_file_name_length Property (CBFS Struct)

This property includes the maximum file name length supported by the virtual filesystem.

Syntax

fn max_file_name_length(&self ) -> Result<i32, CBFSConnectError> 
fn set_max_file_name_length(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies the virtual filesystem's maximum supported file name length, measured in characters. Setting this property to a value less than its default of 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

i32

max_file_path_length Property (CBFS Struct)

This property includes the maximum file path length supported by the virtual filesystem.

Syntax

fn max_file_path_length(&self ) -> Result<i32, CBFSConnectError> 
fn set_max_file_path_length(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies the virtual filesystem's maximum supported file path length, measured in characters; where file path means "a string containing all directory names plus the name of the file itself". Setting this property to a value of less than 260 characters, which corresponds to Windows' MAX_PATH constant, is not recommended.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

i32

max_file_size Property (CBFS Struct)

This property includes the maximum file size supported by the virtual filesystem.

Syntax

fn max_file_size(&self ) -> Result<i64, CBFSConnectError> 
fn set_max_file_size(&self, value : i64) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies the maximum file size, in bytes, supported by the virtual filesystem. The default value of 0 means "no limit".

Note: This property cannot be changed within events.

Data Type

i64

metadata_cache_enabled Property (CBFS Struct)

This property specifies whether or not the metadata cache should be used.

Syntax

fn metadata_cache_enabled(&self ) -> Result<bool, CBFSConnectError> 
fn set_metadata_cache_enabled(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property controls whether the file metadata cache is enabled for a virtual drive. The size of the file metadata cache can be controlled using the metadata_cache_size property.

When enabled, the struct caches file information obtained via on_enumerate_directory and on_get_file_info events and uses the cached metadata to serve operating system requests, thus reducing how often the on_get_file_info events fire.

While a file or directory is open, its metadata is kept available in a special record called a File Control Block, regardless of whether or not the metadata cache is enabled.

For closed files and directories, the metadata is kept in the cache for the time, defined by the UnusedMetadataLifetime configuration setting.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

Data Type

bool

metadata_cache_size Property (CBFS Struct)

This property includes the size of the metadata cache.

Syntax

fn metadata_cache_size(&self ) -> Result<i32, CBFSConnectError> 
fn set_metadata_cache_size(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies the size of the file metadata cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the metadata_cache_enabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

Data Type

i32

mounting_point_count Property (CBFS Struct)

The number of records in the MountingPoint arrays.

Syntax

fn mounting_point_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at mounting_point_count - 1.

This property is read-only.

Data Type

i32

mounting_point_authentication_id Property (CBFS Struct)

The Authentication ID used when creating the mounting point, if applicable.

Syntax

fn mounting_point_authentication_id(&self , MountingPointIndex : i32) -> Result<i64, CBFSConnectError> 

Default Value

0

Remarks

The Authentication ID used when creating the mounting point, if applicable.

If the STGMP_LOCAL flag is included in the mounting_point_flags value, this property reflects the Authentication ID of the user session in which the mounting point was added. Will be 0 if the mounting point was added in the current user session or globally.

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

i64

mounting_point_flags Property (CBFS Struct)

The flags used to create the mounting point.

Syntax

fn mounting_point_flags(&self , MountingPointIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

The flags used to create the mounting point.

This property reflects the flags used to create the mounting point. It is a combination of zero or more of the following:

STGMP_SIMPLE0x00010000Create a simple mounting point.

Simple mounting points may be local or global; and when local, can be made visible in either the current user session or another one.

This flag cannot be combined with STGMP_MOUNT_MANAGER or STGMP_NETWORK, and is implied if neither of those flags are present.

STGMP_MOUNT_MANAGER0x00020000Create a mounting point that appears to the system as a physical device.

When the storage_type property is set to STGT_DISK_PNP, mounting points created using the system mount manager appear as physical devices in the Disk Management snap-in of the Microsoft Management Console (mmc.exe).

This flag is a necessary prerequisite for creating a folder mounting point, which makes a drive accessible via an otherwise empty directory on another NTFS volume.

This flag cannot be combined with STGMP_SIMPLE, STGMP_NETWORK, or STGMP_LOCAL.

Only one mounting point of this type can be added to a virtual drive.

An application cannot add a STGMP_MOUNT_MANAGER mounting point for a virtual drive created in a Docker container.

STGMP_NETWORK0x00040000Create a network mounting point.

Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows File Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

When a virtual drive is created in a Docker container by an application running on the host, it cannot add a mounting point of STGMP_NETWORK type. If an application is running in the container, STGMP_NETWORK type may be used.

STGMP_LOCAL0x10000000Specifies that a local mounting point should be created.

This flag specifies that a local mounting point should be created rather than a global one. When this flag is set, applications must also pass an appropriate value for the add_mounting_point method's AuthenticationId parameter.

Passing 0 for AuthenticationId will make the mounting point visible in the current user session. To make the mounting point visible in a different user session instead, pass the target session's Authentication ID.

This flag is valid when combined with STGMP_SIMPLE or STGMP_NETWORK; it cannot be combined with STGMP_MOUNT_MANAGER. Please note that a mounting point can be made available to other computers as a network share, and network shares are always globally visible on the local machine, even if this flag is set.

STGMP_NETWORK_ALLOW_MAP_AS_DRIVE0x00000001Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows File Explorer).

STGMP_NETWORK_HIDDEN_SHARE0x00000002Indicates that the share should be skipped during enumeration.

Such shares are only accessible when their name is already known to the accessor.

STGMP_NETWORK_READ_ACCESS0x00000004Makes a read-only share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the struct use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_WRITE_ACCESS0x00000008Makes a read/write share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the struct use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_CLAIM_SERVER_NAME0x00000010Specifies that the server name is unique.

When this flag is specified, the driver handles IOCTL_REDIR_QUERY_PATH[_EX] requests by instructing the OS to direct all requests going to the <Server Name> part of the MountingPoint parameter's value to the driver instead.

This flag should be used when the <Server Name> is unique within the local system (e.g., when the application's name is used). Using this flag allows the system to avoid delays caused by certain network requests made by various processes.

This flag is also required for "net view" command to be able to show the share in the list.
STGMP_DRIVE_LETTER_NOTIFY_ASYNC0x20000000Causes the method to return immediately without waiting for mounting notifications to be sent to the system.

STGMP_AUTOCREATE_DRIVE_LETTER0x40000000Tells the struct that it should assign the drive letter automatically.

When this flag is specified, the struct will automatically assign a drive letter from the list of available letters. The assigned letter is added to the end of the list of mounting points, and can be retrieved from there.

Do not include a drive letter in the MountingPoint parameter's value when specifying this flag.

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

i32

mounting_point_name Property (CBFS Struct)

The mounting point name.

Syntax

fn mounting_point_name(&self , MountingPointIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

The mounting point name.

This property reflects the name of the mounting point (i.e., the value passed to the add_mounting_point method's MountingPoint parameter).

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only.

Data Type

String

non_existent_files_cache_enabled Property (CBFS Struct)

This property specifies whether or not the nonexistent files cache should be used.

Syntax

fn non_existent_files_cache_enabled(&self ) -> Result<bool, CBFSConnectError> 
fn set_non_existent_files_cache_enabled(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property controls whether the nonexistent files cache is enabled for a virtual drive. The size of the nonexistent files cache can be controlled using the non_existent_files_cache_size property.

When enabled, the struct will cache any on_get_file_info responses that indicate that the requested file does not exist. If another request is later made for the same file, the struct will use this information to automatically report a file not found error rather than firing the on_get_file_info event again.

Please refer to the Caching topic for more information.

Note: This property cannot be changed within events.

Data Type

bool

non_existent_files_cache_size Property (CBFS Struct)

This property includes the size of the nonexistent files cache.

Syntax

fn non_existent_files_cache_size(&self ) -> Result<i32, CBFSConnectError> 
fn set_non_existent_files_cache_size(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies the maximum size of the nonexistent files cache as a number of entries. The value must be a positive number. The maximum valid value is 65536.

Please refer to the non_existent_files_cache_enabled property, as well as the Caching topic, for more information.

Note: This property cannot be changed within events.

Data Type

i32

open_files_count Property (CBFS Struct)

The number of records in the OpenFile arrays.

Syntax

fn open_files_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at open_files_count - 1.

This property is read-only.

Data Type

i32

open_file_handle_closed Property (CBFS Struct)

This property reflects whether the handle to the file has been closed.

Syntax

fn open_file_handle_closed(&self , OpenFileIndex : i32) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

This property reflects whether the handle to the file has been closed.

This property reflects whether the handle to the file has been closed.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only.

Data Type

bool

open_file_name Property (CBFS Struct)

This property reflects the name of the open file.

Syntax

fn open_file_name(&self , OpenFileIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

This property reflects the name of the open file.

This property reflects the name of the open file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only.

Data Type

String

open_file_process_id Property (CBFS Struct)

This property reflects the Id of the process that opened the file.

Syntax

fn open_file_process_id(&self , OpenFileIndex : i32) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property reflects the Id of the process that opened the file.

This property reflects the Id of the process (PID) that opened the file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only.

Data Type

i32

open_file_process_name Property (CBFS Struct)

This property reflects the name of the process that opened the file.

Syntax

fn open_file_process_name(&self , OpenFileIndex : i32) -> Result<String, CBFSConnectError> 

Default Value

String::default()

Remarks

This property reflects the name of the process that opened the file.

This property reflects the name of the process that opened the file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only.

Data Type

String

open_handles_count Property (CBFS Struct)

This property includes the number of handles to filesystem objects in the virtual drive that are currently open.

Syntax

fn open_handles_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property reflects the number of handles to filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when create_opened_files_snapshot is called, and cleared when close_opened_files_snapshot is called; please refer to those methods for more information.

This property's value may differ from that of the open_objects_count property, and from the number of items in the OpenFile* properties. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

Note: The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

This property is read-only.

Data Type

i32

open_objects_count Property (CBFS Struct)

This property includes the number of filesystem objects in the virtual drive that are currently open.

Syntax

fn open_objects_count(&self ) -> Result<i32, CBFSConnectError> 

Default Value

0

Remarks

This property reflects the number of filesystem objects (e.g., files, directories) in the virtual drive that are currently open. It is populated when create_opened_files_snapshot is called and cleared when close_opened_files_snapshot is called; please refer to those methods for more information.

This property's value may differ from that of the open_handles_count property, and from the number of items in the OpenFile* properties. This occurs because each object can be opened several times, and because the OS may keep files open even after all handles to them have been closed.

Note: The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

This property is read-only.

Data Type

i32

process_restrictions_enabled Property (CBFS Struct)

Whether process access restrictions are enabled.

Syntax

fn process_restrictions_enabled(&self ) -> Result<bool, CBFSConnectError> 
fn set_process_restrictions_enabled(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property controls whether the struct should enforce per-process access restrictions; by default, it is disabled. When enabled, the add_granted_process and add_denied_process methods can be used to add process-specific access rules for the struct to enforce across the entire virtual drive.

When an application enables this propery, it should use the add_granted_process method to add at least one pocess as allowed; otherwise, the data will be inaccessible.

The current process access rules are reflected by the AccessGrantedProcess* and AccessDeniedProcess* properties.

Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

Data Type

bool

serialize_access Property (CBFS Struct)

This property specifies whether nonintersecting operations against the same file should execute serially or in parallel.

Syntax

fn serialize_access(&self ) -> Result<bool, CBFSConnectError> 
fn set_serialize_access(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the struct should force nonintersecting operations against a single file or directory to execute serially (default), or allow them to execute in parallel.

Parallel processing can speed up operations, to a certain extent. When this property is disabled, and two or more requests (which do not change filesystem information) are made against the same file or directory, those requests are surfaced in parallel through the appropriate events (assuming that enough worker threads are available to service them at the time). By default, this property is enabled, and such requests are serialized. Please refer to the Threading and Concurrency topic for more information.

Note: For parallel processing to work, the serialize_events property must be disabled, and the MinWorkerThreadCount and MaxWorkerThreadCount configuration settings must be set such that parallel processing can actually occur.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

serialize_events Property (CBFS Struct)

Whether events should be fired on a single worker thread, or many.

Syntax

fn serialize_events(&self ) -> Result<i32, CBFSConnectError> 
fn set_serialize_events(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies whether the struct should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

0 (seOnMultipleThreads) The struct fires events in the context of multiple worker threads. The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control how many worker threads are used for this.
1 (seOnOneWorkerThread) The struct fires events in the context of one background worker thread.

Please note that, in general, the struct will always fire events related to a single file sequentially (though not necessarily on the same worker thread all the time), regardless of how this property is set. The one exception is that, if this property is set to seOnMultipleThreads, the serialize_access property can be enabled to allow multiple read requests made against a single file to execute concurrently. Please refer to the Threading and Concurrency topic for more information.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

i32

storage_characteristics Property (CBFS Struct)

The characteristic flags to create the virtual drive with (Windows only).

Syntax

fn storage_characteristics(&self ) -> Result<i32, CBFSConnectError> 
fn set_storage_characteristics(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

The system, as well as other applications, use these flags to optimize their use of the virtual drive. This property should be set by OR'ing together zero or more of the following flags:

STGC_FLOPPY_DISKETTE0x00000001The storage is a floppy disk device.

This flag is not supported when storage_type is set to STGT_DISK_PNP.

STGC_READONLY_DEVICE0x00000002The storage is a read-only device.

STGC_WRITE_ONCE_MEDIA0x00000008The storage device's media can only be written to once.

This flag is not supported when storage_type is set to STGT_DISK_PNP.

STGC_REMOVABLE_MEDIA0x00000010The storage device's media is removable.

Users may remove the storage media from the virtual drive at any time. (Note that this flag does not indicate that the virtual drive itself is removable.)

STGC_AUTOCREATE_DRIVE_LETTER0x00002000The system should automatically create a drive letter for the storage device.

Deprecated: Include the STGMP_AUTOCREATE_DRIVE_LETTER flag in the value passed for the add_mounting_point method's Flags parameter instead.

When this flag is present, the storage_guid property must be set. This flag only works when storage_type is set to STGT_DISK_PNP.

STGC_SHOW_IN_EJECTION_TRAY0x00004000The storage device should be shown in the 'Safely Remove Hardware and Eject Media' menu in the system notification area (system tray).

This flag only works when storage_type is set to STGT_DISK_PNP.

STGC_ALLOW_EJECTION0x00008000The storage device can be ejected.

Users may eject the virtual drive at any time. When the virtual drive is ejected, it is destroyed.

This flag only works when storage_type is set to STGT_DISK_PNP.

STGC_RESERVED_10x00010000Reserved, do not use.

STGC_RESERVED_20x00020000Reserved, do not use.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

i32

storage_guid Property (CBFS Struct)

The GUID to create the virtual drive with.

Syntax

fn storage_guid(&self ) -> Result<String, CBFSConnectError> 
fn set_storage_guid(&self, value : String) -> Option<CBFSConnectError> fn set_storage_guid_ref(&self, value : &String) -> Option<CBFSConnectError>

Default Value

String::default()

Remarks

This property is used to specify a GUID for the virtual drive, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property may be left empty; in the latter case, the driver will generate a unique value when a drive is mounted.

Some software uses a drive's GUID for the purpose of setting and maintaining certain configuration parameters. Therefore, applications are expected to use the same GUID when repeatedly creating a virtual drive that represents the same data.

In multiuser environments (Terminal Server, Citrix and similar software) where the application may be run concurrently by different users, using the same GUID for all users will cause a name conflict. To avoid it, mix the constant GUID value with the user-unique information such as the hash of the username or SID. This way, each user will use a constant but distinct GUID for their virtual drive.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

String

storage_present Property (CBFS Struct)

This property specifies whether a virtual drive has been created.

Syntax

fn storage_present(&self ) -> Result<bool, CBFSConnectError> 

Default Value

false

Remarks

This property reflects whether a virtual drive has been created; it is automatically updated by the struct whenever the virtual drive's presence changes (e.g., due to calls to create_storage, delete_storage).

This property is read-only.

Data Type

bool

storage_type Property (CBFS Struct)

The type of virtual drive to create (Windows only).

Syntax

fn storage_type(&self ) -> Result<i32, CBFSConnectError> 
fn set_storage_type(&self, value : i32) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property specifies what type of virtual drive should be created. Windows File Explorer uses this information to display the appropriate icon and apply the appropriate security settings for the virtual drive. Other applications may also make use of this information in various ways.

Possible values are:

STGT_DISK0x00000000Create a regular disk device.

STGT_CDROM0x00000001Create a CD-ROM or DVD device.

STGT_DISK_PNP0x00000003Create a plug-and-play storage device.

Important: The CBFS Connect system driver must be installed in PnP mode for this option to function properly.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Plug-and-play Virtual Drives

Virtual drives created as plug-and-play (STGT_DISK_PNP) require that a "physical device" be visible in the Disk Manager snap-in of the Microsoft Management Console (mmc.exe). This can be accomplished by calling the add_mounting_point method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.

In addition to supporting the STGC_REMOVABLE_MEDIA storage_characteristics flag, which specifies whether a virtual drive's media is removable or non-removable, plug-and-play virtual drives also support the STGC_ALLOW_EJECTION flag, which specifies whether a virtual drive itself is removable or non-removable.

Data Type

i32

support_change_time_attribute Property (CBFS Struct)

This property specifies whether the virtual filesystem supports the ChangeTime file attribute.

Syntax

fn support_change_time_attribute(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_change_time_attribute(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the ChangeTime file attribute, which tracks the last time a file's metadata (e.g., permissions) or content was changed. The ChangeTime attribute is optional, and applications can choose not to handle it in events by simply leaving the value of the corresponding parameter unchanged.

Note: If the application is identifying its virtual filesystem (via file_system_name) as NTFS, and this property is disabled, the struct will still handle the ChangeTime attribute implicitly by setting it equal to LastWriteTime.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

support_compressed_attribute Property (CBFS Struct)

This property specifies whether the virtual filesystem supports the Compressed file attribute.

Syntax

fn support_compressed_attribute(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_compressed_attribute(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

When enabled, this property tells the driver to report support of compression to the operating system. The struct supports and reports to the OS only one compression algorithm - COMPRESSION_FORMAT_DEFAULT.

When such a support is reported, processes may read or change the Compressed attribute of a file. An implementation of a virtual filesystem should provide the Compressed status through the file attributes in the on_get_file_info and on_enumerate_directory events. The attribute may be changed by the system, and such a change is communicated to the implementation by the Attributes parameter in the on_set_file_attributes event.

Besides supporting the attribute, the implementation should handle on_query_compression_info, on_query_allocated_ranges, and on_zeroize_file_range events as described in the corresponding topics.

If the implementation performs actual compression of the data, it should return the size of data in compressed form (i.e., the smaller size) in the on_query_compression_info event and the size of the original uncompressed data (the larger size) in on_get_file_info and on_enumerate_directory.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

support_extended_attributes Property (CBFS Struct)

This property specifies whether the virtual filesystem supports Extended Attributes of files and operations on them.

Syntax

fn support_extended_attributes(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_extended_attributes(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

When enabled, this property tells the driver to report support of Extended Attributes to the operating system. When such a support is reported, processes may read or change extended attributes of a file. An implementation of a virtual filesystem should provide the information about these attributes through the on_query_ea event. Additionally, the implementation should provide the information (the size) of extended attributes together with other file-related information when handling the on_get_file_info and on_enumerate_directory events. The attributes may be changed by the system, and such a change is communicated to the implementation by the on_set_ea event.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

support_last_access_time_attribute Property (CBFS Struct)

This property specifies whether the virtual filesystem supports the LastAccessTime file attribute.

Syntax

fn support_last_access_time_attribute(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_last_access_time_attribute(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports the LastAccessTime file attribute, which tracks the last time a file's contents were accessed.

When this property is enabled (default), a file's LastAccessTime attribute gets updated whenever the file is closed (unless fewer than 60 seconds have elapsed since the previous LastAccessTime). When this property is disabled, a file's LastAccessTime is still tracked and passed along with its LastWriteTime when the latter is changed, but it is not updated separately when the file is closed.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

support_odx_read_write Property (CBFS Struct)

This property specifies whether the virtual filesystem supports ODX (Offloaded Data Transfer) operations.

Syntax

fn support_odx_read_write(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_odx_read_write(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports ODX (Offloaded Data Transfer) operations. Please refer to Microsoft's Offloaded Data Transfer article for more information.

If this property is enabled, the application must properly handle the on_offload_read_file and on_offload_write_file events, which will fire anytime the OS sends an offload read or offload write request to the virtual filesystem.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

support_sparse_file_attribute Property (CBFS Struct)

This property specifies whether the virtual filesystem supports operations with sparse files.

Syntax

fn support_sparse_file_attribute(&self ) -> Result<bool, CBFSConnectError> 
fn set_support_sparse_file_attribute(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

When enabled, this property tells the driver to report support of sparse files to the operating system. A Sparse file is a file that may contain multiple valid data blocks scattered across the file. This is opposite to regular files, which have a single continuous block of valid data that starts at the beginning of the file. Sparse files are used when there should be a huge file created but real data must be placed only at some positions.

When support for Sparse files is reported, processes may read or change the Sparse attribute of a file.

An implementation of a virtual filesystem should provide the Sparse status through the file attributes in the on_get_file_info and on_enumerate_directory events. The attribute may be changed by the system, and such a change is communicated to the implementation by the Attributes parameter in the on_set_file_attributes event.

Besides supporting the attribute, the implementation should handle on_query_compression_info, on_query_allocated_ranges, and on_zeroize_file_range events as described in the corresponding topics.

If the implementation performs actual management of valid data blocks, it should return the size of valid data (i.e., the smaller size) in the on_query_compression_info event and the size of the complete file (the larger size) in on_get_file_info and on_enumerate_directory.

Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.

Data Type

bool

tag Property (CBFS Struct)

This property stores application-defined data specific to a particular instance of the struct.

Syntax

fn tag(&self ) -> Result<i64, CBFSConnectError> 
fn set_tag(&self, value : i64) -> Option<CBFSConnectError>

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the struct.

Data Type

i64

use_alternate_data_streams Property (CBFS Struct)

This property specifies whether or not the virtual filesystem supports alternate data streams.

Syntax

fn use_alternate_data_streams(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_alternate_data_streams(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether or not the virtual filesystem should indicate to the system that it supports alternate data streams (ADS, otherwise known as "named streams"). Alternate data streams can be present in both files and directories.

If this property is enabled, the application must properly handle the on_enumerate_named_streams and on_close_named_streams_enumeration events for alternate data streams to function correctly. Additionally, the application's on_get_file_info and on_enumerate_directory event handlers must take into account requests made by the OS to work with the alternate data streams.

Note: Alternate data streams are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via file_system_name) as NTFS, supporting alternate data streams is recommended.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_case_sensitive_file_names Property (CBFS Struct)

This property specifies whether the virtual filesystem is case-sensitive or just case-preserving.

Syntax

fn use_case_sensitive_file_names(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_case_sensitive_file_names(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it is case-sensitive (true) or just case-preserving (false; default).

Traditionally, Windows uses a case-insensitive filesystem architecture. The NTFS filesystem has a case-sensitive mode, however, to support a POSIX subsystem; enabling this property will make the struct behave in a manner similar to NTFS with regards to case-sensitivity by doing the following:

  • Informing Windows that it supports preserving file name casing (which the application must actually do in its code).
  • Working in a case-sensitive manner when managing caches.
  • Firing the on_get_file_info event to obtain a real file name if a mixed-case name is encountered.

In addition to enabling this property, a flag must be set in the registry for case-sensitive file name support to work. Specifically, in the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\kernel registry key, the DWORD ObCaseInsensitive must be set to 0.

Note: The struct always attempts to work with case-sensitive file names, regardless of how this property is set. When a file is being opened, the CBFS Connect driver looks for the name of the file in the metadata cache, if an exact match is not found, the on_get_file_info event is fired to allow the application to supply a corrected file name through the RealFileName parameter. If the application chooses not to do so, the case-insensitive name will be used.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_directory_empty_check Property (CBFS Struct)

This property specifies whether the IsDirectoryEmpty event should be used.

Syntax

fn use_directory_empty_check(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_directory_empty_check(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the struct should fire the on_is_directory_empty event when the OS needs to check whether a directory is empty. Such checks typically are performed just before the OS requests that a directory be deleted.

If this property is enabled (default), the application must properly handle the on_is_directory_empty event.

Note: Use of the on_is_directory_empty event is efficient only if the virtual filesystem has a fast way to check whether directories contain any entries (e.g., files, subdirectories, links). If such a check would require enumerating child entries, it is more efficient for the application to disable this property and perform the check directly within the on_can_file_be_deleted event instead.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_disk_quotas Property (CBFS Struct)

This property specifies whether the virtual filesystem supports disk quotas.

Syntax

fn use_disk_quotas(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_disk_quotas(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports disk quota management.

If this property is enabled, the application must properly handle the on_query_quotas, on_set_quotas, on_get_default_quota_info, and on_set_default_quota_info events for quota management to function correctly. The on_get_file_name_by_file_id event must be handled as well.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_file_ids Property (CBFS Struct)

This property specifies whether the virtual filesystem supports file Ids.

Syntax

fn use_file_ids(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_file_ids(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports File IDs.

If this property is enabled, the application must properly handle the on_get_file_info and on_enumerate_directory events and return proper file Ids for files and directories. The on_get_file_name_by_file_id event must be handled as well.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_hard_links Property (CBFS Struct)

This property specifies whether the virtual filesystem supports hard links.

Syntax

fn use_hard_links(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_hard_links(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports hard links to files.

If this property is enabled, the application must properly handle the on_create_hard_link, on_enumerate_hard_links, and on_close_hard_links_enumeration events for hard links to function correctly. The on_get_file_name_by_file_id event must be handled as well, and the on_get_file_info must always be sure to return the number of hard links a file has by setting the HardLinkCount event parameter appropriately.

Note: Hard links are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via file_system_name) as NTFS, supporting hard links is recommended.

Please refer to the Hard Links topic for more information.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_object_ids Property (CBFS Struct)

This property specifies whether the virtual filesystem supports object Id operations.

Syntax

fn use_object_ids(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_object_ids(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports object Id operations. This includes setting, retrieval, and deletion of the system-provided data block (currently, 64 bytes of data) associated with a volume or a file or directory on this volume.

If this property is true, the application must properly handle the on_get_object_id and on_set_object_id events. Set this property to false to tell the OS that the object Id operations are not supported.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_reparse_points Property (CBFS Struct)

This property specifies whether the virtual filesystem supports reparse points.

Syntax

fn use_reparse_points(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_reparse_points(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports reparse points.

If this property is enabled, the application must properly handle the on_set_reparse_point, on_get_reparse_point, and on_delete_reparse_point events for reparse points to function correctly.

Note: Reparse points are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via file_system_name) as NTFS, supporting reparse points is recommended. Reparse point support is also expected by the NFS sharing components of the OS.

Please refer to the Reparse Points topic for more information.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_short_file_names Property (CBFS Struct)

This property specifies whether the virtual filesystem supports short (8.3) file names.

Syntax

fn use_short_file_names(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_short_file_names(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports short file names (also known as 8.3 file names). Short file name support may be necessary for some older third-party applications to be able to access the virtual filesystem's files.

If this property is enabled, the application must be sure to return short filenames when handling the on_enumerate_directory and on_get_file_info events; and must be able to handle any event firing with a short file name rather than a normal one.

Please refer to the Short File Names topic for more information.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

use_windows_security Property (CBFS Struct)

This property specifies whether the virtual filesystem supports Windows' ACL-based security mechanisms.

Syntax

fn use_windows_security(&self ) -> Result<bool, CBFSConnectError> 
fn set_use_windows_security(&self, value : bool) -> Option<CBFSConnectError>

Default Value

false

Remarks

This property specifies whether the virtual filesystem should indicate to the system that it supports Windows' standard security mechanisms, which are based on ACLs (access control lists).

If this property is enabled, the application must properly handle the on_get_file_security and on_set_file_security events for Windows' security mechanisms to function properly.

Note: Windows' security attributes are an expected feature of the NTFS filesystem; if the application is identifying its virtual filesystem (via file_system_name) as NTFS, supporting Windows' security attributes is recommended.

Please refer to the Security Checks topic for more information.

Note: This property cannot be changed when active is true, and it cannot be changed within events.

Data Type

bool

add_denied_process Method (CBFS Struct)

Adds a rule that prevents a process from accessing the virtual drive (Windows only).

Syntax

fn add_denied_process(&self, process_file_name : &String, process_id : i32, child_processes : bool, desired_access : i32) -> Option<CBFSConnectError>

Remarks

When the process_restrictions_enabled property is enabled, this method can be used to add an access rule that denies the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full file name of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to deny; valid values are:

STG_DACCESS_READ0x00000001Grant/deny read access.

STG_DACCESS_WRITE0x00000002Grant/deny write access.

STG_DACCESS_READWRITE0x00000003Grant/deny read and write access.

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the remove_denied_process method.

Note: This method can be called only when active is true, and it cannot be called within events.

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

add_granted_process Method (CBFS Struct)

Adds a rule that allows a process to access the virtual drive (Windows only).

Syntax

fn add_granted_process(&self, process_file_name : &String, process_id : i32, child_processes : bool, desired_access : i32) -> Option<CBFSConnectError>

Remarks

When the process_restrictions_enabled property is enabled, this method can be used to add an access rule that grants the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.

Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full file name of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to grant; valid values are:

STG_DACCESS_READ0x00000001Grant/deny read access.

STG_DACCESS_WRITE0x00000002Grant/deny write access.

STG_DACCESS_READWRITE0x00000003Grant/deny read and write access.

To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the remove_granted_process method.

Note: This method can be called only when active is true, and it cannot be called within events.

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

add_mounting_point Method (CBFS Struct)

Adds a mounting point for the virtual drive.

Syntax

fn add_mounting_point(&self, mounting_point : &String, flags : i32, authentication_id : i64) -> Option<CBFSConnectError>

Remarks

This method adds a new mounting point for the virtual drive (which must have already been created using create_storage). Virtual drives may have as many mounting points as desired.

Typically, mounting points may be added before or after mount_media is called. However, for plug-and-play virtual drives with non-removable media (see storage_type), add_mounting_point must not be called until after the mount_media method has been called successfully, otherwise an error will occur.

MountingPoint should be set to the name/path of the mounting point. The format of this value varies based what type of mounting point the application wishes to create; please refer to the Mounting Points topic for more information.

The Flags parameter is used to specify properties for the mounting point, and should be set by OR'ing together zero or more of the following flags:

STGMP_SIMPLE0x00010000Create a simple mounting point.

Simple mounting points may be local or global; and when local, can be made visible in either the current user session or another one.

This flag cannot be combined with STGMP_MOUNT_MANAGER or STGMP_NETWORK, and is implied if neither of those flags are present.

STGMP_MOUNT_MANAGER0x00020000Create a mounting point that appears to the system as a physical device.

When the storage_type property is set to STGT_DISK_PNP, mounting points created using the system mount manager appear as physical devices in the Disk Management snap-in of the Microsoft Management Console (mmc.exe).

This flag is a necessary prerequisite for creating a folder mounting point, which makes a drive accessible via an otherwise empty directory on another NTFS volume.

This flag cannot be combined with STGMP_SIMPLE, STGMP_NETWORK, or STGMP_LOCAL.

Only one mounting point of this type can be added to a virtual drive.

An application cannot add a STGMP_MOUNT_MANAGER mounting point for a virtual drive created in a Docker container.

STGMP_NETWORK0x00040000Create a network mounting point.

Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows File Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

When a virtual drive is created in a Docker container by an application running on the host, it cannot add a mounting point of STGMP_NETWORK type. If an application is running in the container, STGMP_NETWORK type may be used.

STGMP_LOCAL0x10000000Specifies that a local mounting point should be created.

This flag specifies that a local mounting point should be created rather than a global one. When this flag is set, applications must also pass an appropriate value for the add_mounting_point method's AuthenticationId parameter.

Passing 0 for AuthenticationId will make the mounting point visible in the current user session. To make the mounting point visible in a different user session instead, pass the target session's Authentication ID.

This flag is valid when combined with STGMP_SIMPLE or STGMP_NETWORK; it cannot be combined with STGMP_MOUNT_MANAGER. Please note that a mounting point can be made available to other computers as a network share, and network shares are always globally visible on the local machine, even if this flag is set.

STGMP_NETWORK_ALLOW_MAP_AS_DRIVE0x00000001Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows File Explorer).

STGMP_NETWORK_HIDDEN_SHARE0x00000002Indicates that the share should be skipped during enumeration.

Such shares are only accessible when their name is already known to the accessor.

STGMP_NETWORK_READ_ACCESS0x00000004Makes a read-only share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the struct use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_WRITE_ACCESS0x00000008Makes a read/write share available for the mounting point.

When this flag is specified, the <Server Name> part of the MountingPoint parameter value must be empty. Please refer to the Mounting Points topic for more information. This flag makes the struct use the Windows API's NetShareAdd function. As per MSDN, "Only members of the Administrators, System Operators, or Power Users local group can add file shares with a call to the NetShareAdd function."

STGMP_NETWORK_CLAIM_SERVER_NAME0x00000010Specifies that the server name is unique.

When this flag is specified, the driver handles IOCTL_REDIR_QUERY_PATH[_EX] requests by instructing the OS to direct all requests going to the <Server Name> part of the MountingPoint parameter's value to the driver instead.

This flag should be used when the <Server Name> is unique within the local system (e.g., when the application's name is used). Using this flag allows the system to avoid delays caused by certain network requests made by various processes.

This flag is also required for "net view" command to be able to show the share in the list.
STGMP_DRIVE_LETTER_NOTIFY_ASYNC0x20000000Causes the method to return immediately without waiting for mounting notifications to be sent to the system.

STGMP_AUTOCREATE_DRIVE_LETTER0x40000000Tells the struct that it should assign the drive letter automatically.

When this flag is specified, the struct will automatically assign a drive letter from the list of available letters. The assigned letter is added to the end of the list of mounting points, and can be retrieved from there.

Do not include a drive letter in the MountingPoint parameter's value when specifying this flag.

If no flags are specified, the STGMP_SIMPLE flag is assumed.

If the STGMP_LOCAL flag is set, the AuthenticationId parameter should be set to the Authentication ID of the user session the mounting point should visible in; or to 0 to make the mounting point visible in the current user session. If the aforementioned flag is not set and AuthenticationId is 0, the mounting point will be global (i.e., visible in all user sessions). When AuthenticationId is set to a non-zero value, STGMP_LOCAL is implied. Please refer to the Mounting Points topic for more information.

To create a virtual drive in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling add_mounting_point. Note: not all mounting point types are supported when a mounting point is created in a container. Please refer to the Docker Containers for more information.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

Virtual Drives, Media, and Mounting Points

In the FUSE struct, a mount point is specified as a parameter of the mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS struct.

When applications call the create_storage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call mount_media to "insert" virtual storage media into the virtual drive. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual drive, applications should use the add_mounting_point method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call add_mounting_point before mount_media (except for plug-and-play virtual drives with non-removable media; see storage_type), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

close_opened_files_snapshot Method (CBFS Struct)

Closes the previously-created opened files snapshot.

Syntax

fn close_opened_files_snapshot(&self) -> Option<CBFSConnectError>

Remarks

This method closes the opened files snapshot previously created by create_opened_files_snapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

config Method (CBFS Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &String) ->  Result<String, CBFSConnectError>

Remarks

config is a generic method available in every struct. It is used to set and retrieve configuration settings for the struct.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

create_opened_files_snapshot Method (CBFS Struct)

Creates a snapshot of information about files that are currently open.

Syntax

fn create_opened_files_snapshot(&self) -> Option<CBFSConnectError>

Remarks

This method creates a snapshot of information about all files and directories in the virtual filesystem that are currently open. This information is then used to populate the OpenFile* properties, as well as the open_handles_count and open_objects_count properties.

Note that there will always be at least one item in the OpenFile* properties since the virtual volume itself is always inherently open.

When the application is finished working with the opened files snapshot, it must close it by calling the close_opened_files_snapshot method in order to release the associated memory. If this method is called again before an existing snapshot is closed, the struct will attempt to close it before creating a new one.

Note: This method can be called only when active is true, and it cannot be called within events.

The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.

create_storage Method (CBFS Struct)

This method creates the virtual drive.

Syntax

fn create_storage(&self) -> Option<CBFSConnectError>

Remarks

This method creates the virtual drive (without mounting points) based on the following properties and configuration settings, which cannot be changed once the virtual storage has been created:

Note: Many other properties, although not directly used by this method, nonetheless cannot be changed once a virtual drive is created. Such restrictions are noted where applicable.

After the virtual drive is created, use the mount_media method to "insert storage media" into the virtual drive, and use the add_mounting_point method to create one or more mounting points for it.

The initialize method must have been called by some struct instance in the application before calling this method.

Note: This method cannot be called within events.

Virtual Drives, Media, and Mounting Points

In the FUSE struct, a mount point is specified as a parameter of the mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS struct.

When applications call the create_storage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call mount_media to "insert" virtual storage media into the virtual drive. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual drive, applications should use the add_mounting_point method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call add_mounting_point before mount_media (except for plug-and-play virtual drives with non-removable media; see storage_type), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

delete_storage Method (CBFS Struct)

This method deletes the virtual drive.

Syntax

fn delete_storage(&self, force_unmount : bool) -> Option<CBFSConnectError>

Remarks

This method attempts to delete the virtual drive. The ForceUnmount parameter controls how this method behaves if any mounting points currently exist for the virtual drive.

If ForceUnmount is true, any existing mounting points are forcibly removed (and any open handles are closed along the way). If ForceUnmount is false and any mounting points exist for it, this method .

Note: This method cannot be called within events.

disable_route_cache Method (CBFS Struct)

This method disables the automatic routing of requests to local files.

Syntax

fn disable_route_cache(&self, invalidate_routed_files : bool) -> Option<CBFSConnectError>

Remarks

This method disables the automatic routing of requests to files in the directory specified by a previous call to enable_route_cache. Please refer to that method for more information about said request routing.

The InvalidateRoutedFiles parameter controls what happens to any handles currently open for files in the aforementioned directory: passing true will allow them to continue being used, whereas passing false will invalidate them immediately.

Note: This method cannot be called within events.

dispatch_events Method (CBFS Struct)

Reserved, do not use.

Syntax

fn dispatch_events(&self) -> Option<CBFSConnectError>

Remarks

Reserved, do not use.

enable_route_cache Method (CBFS Struct)

This method enables the automatic routing of requests to local files.

Syntax

fn enable_route_cache(&self, location : &String, flags : i32) -> Option<CBFSConnectError>

Remarks

This method enables the automatic routing of requests to files that exist in the directory specified by Location. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

When automatic request routing is enabled, and a file in the virtual drive is opened, the struct will immediately check the cache directory to see if a file with the same path and name exists. If such a file is found, all operations will be performed on it directly and the corresponding events will not fire (except for the operations excluded from routing by the specified Flags).

When attempting to find a matching file, the struct assumes that the contents of the specified cache directory mirror that of the virtual drive. That is, the cache directory corresponds to the root of the virtual drive, and the files and directory structure are the same in each. If the struct fails to find a matching file (or if the operation in question is excluded from routing), then the applicable events fire as usual.

The Flags value should be created by ORing together zero or more of the following flags:

CBFS_ROUTE_FILE_READ_ONLY0x00000001Causes files to be treated as read-only; all write operations will be automatically denied.

CBFS_ROUTE_OPEN_EVENT0x00000020Prevents 'open' requests from being routed automatically.

If set, the on_open_file event will fire as usual when such requests arrive.

Note: This flag is implied if any of the other CBFS_ROUTE_*_EVENT flags are present.

CBFS_ROUTE_CLEANUP_EVENT0x00000040Prevents 'cleanup' requests from being routed automatically.

If set, the on_cleanup_file event will fire as usual when such requests arrive.

CBFS_ROUTE_CLOSE_EVENT0x00000080Prevents 'close' requests from being routed automatically.

If set, the on_close_file event will fire as usual when such requests arrive.

Note: This flag is implied if any of the other CBFS_ROUTE_*_EVENT flags are present.

CBFS_ROUTE_ENUMERATE_DIRECTORY_EVENT0x00000200Prevents 'enumerate directory' requests from being routed automatically.

If set, the on_enumerate_directory event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_SECURITY_EVENT0x00000400Prevents 'set security' requests from being routed automatically.

If set, the on_set_file_security event will fire as usual when such requests arrive.

CBFS_ROUTE_GET_SECURITY_EVENT0x00000800Prevents 'get security' requests from being routed automatically.

If set, the on_get_file_security event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_FILE_ATTRIBUTES_EVENT0x00002000Prevents 'set file attributes' requests from being routed automatically.

If set, the on_set_file_attributes event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_FILE_SIZES_EVENT0x00004000Prevents 'set file size' requests from being routed automatically.

If set, the on_set_file_size event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_VALID_DATA_LENGTH_EVENT0x00008000Prevents 'set valid data length' requests from being routed automatically.

If set, the on_open_file event will fire as usual when such requests arrive.

CBFS_ROUTE_CREATE_HARD_LINK_EVENT0x00020000Prevents 'create hard link' requests from being routed automatically.

If set, the on_create_hard_link event will fire as usual when such requests arrive.

CBFS_ROUTE_QUERY_QUOTA_EVENT0x00040000Prevents 'query quota' requests from being routed automatically.

If set, the on_query_quotas event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_QUOTA_EVENT0x00080000Prevents 'set quota' requests from being routed automatically.

If set, the on_set_quotas event will fire as usual when such requests arrive.

CBFS_ROUTE_CAN_FILE_BE_DELETED_EVENT0x00200000Prevents 'can file be deleted' requests from being routed automatically.

If set, the on_can_file_be_deleted event will fire as usual when such requests arrive.

CBFS_ROUTE_IS_DIRECTORY_EMPTY_EVENT0x00400000Prevents 'is directory empty' requests from being routed automatically.

If set, the on_is_directory_empty event will fire as usual when such requests arrive.

CBFS_ROUTE_RENAME_EVENT0x00800000Prevents 'rename/move' requests from being routed automatically.

If set, the on_rename_or_move_file event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_EA_EVENT0x01000000Prevents 'set ea' requests from being routed automatically.

If set, the on_set_ea event will fire as usual when such requests arrive.

CBFS_ROUTE_QUERY_EA_EVENT0x02000000Prevents 'query ea' requests from being routed automatically.

If set, the on_query_ea event will fire as usual when such requests arrive.

Note: This method cannot be called within events.

file_matches_mask Method (CBFS Struct)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

fn file_matches_mask(&self, mask : &String, file_name : &String, case_sensitive : bool) ->  Result<bool, CBFSConnectError>

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

flush_file Method (CBFS Struct)

This method flushes cached data of a file or its part.

Syntax

fn flush_file(&self, file_name : &String, offset : i64, length : i64, wait : bool) -> Option<CBFSConnectError>

Remarks

This method flushes cached data of a file denoted by FileName or its part to storage, making it easier for the OS to close the file and ensuring consistency of data on the backend (e.g., during locking of a file range).

To flush all of the data of the file, set both Offset and Length to 0. Set any or both of these parameters to non-zero values to specify the data range within the file that should be flushed.

The Wait parameter specifies if the method must wait for flushing to complete. If flush_file is called from an event handler, Wait must be set to false; otherwise, the method will immediately fail with an error.

get_driver_status Method (CBFS Struct)

Retrieves the status of the system driver.

Syntax

fn get_driver_status(&self, product_guid : &String, module : i32) ->  Result<i32, CBFSConnectError>

Remarks

This method retrieves the status of the system driver module specified by Module. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

MODULE_STATUS_NOT_PRESENT0x00000000The specified module is not present on the system.

Note: This functionality is only available in Windows.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

Note: This functionality is only available in Windows.

MODULE_STATUS_RUNNING0x00000004The specified module is loaded and running.

Note: This functionality is only available in Windows.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

The Module parameter specifies which driver module to query the status of. Possible values are:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBFSShellHelper24.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the get_driver_status method.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

get_event_file_name Method (CBFS Struct)

This method retrieves the name of the file or directory, to which the event applies.

Syntax

fn get_event_file_name(&self) ->  Result<String, CBFSConnectError>

Remarks

This method can be called within event handlers of events, related to the file or directory operations, to retrieve the name of the file or directory, to which the operation applies. If the query fails or an event does not have an associated file name, this method returns an empty string.

get_handle_creator_process_id Method (CBFS Struct)

This method retrieves the Id of the process (PID) that opened the specified file handle.

Syntax

fn get_handle_creator_process_id(&self, handle_info : i64) ->  Result<i32, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

get_handle_creator_process_name Method (CBFS Struct)

This method retrieves the name of the process that opened the specified file handle.

Syntax

fn get_handle_creator_process_name(&self, handle_info : i64) ->  Result<String, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns an empty string.

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

get_handle_creator_thread_id Method (CBFS Struct)

This method retrieves the Id of the thread that opened the specified file handle.

Syntax

fn get_handle_creator_thread_id(&self, handle_info : i64) ->  Result<i32, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

get_handle_creator_token Method (CBFS Struct)

This method retrieves the security token associated with the process that opened the specified file handle.

Syntax

fn get_handle_creator_token(&self, handle_info : i64) ->  Result<i64, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle specified by HandleInfo. The value to pass for HandleInfo should be obtained directly from the event. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

Note: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

  • Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
  • Guest mode, in which case the retrievable information is for the system's GUEST account.
  • Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within events that expose a HandleInfo parameter, and must be called in the same thread that the event was originally fired on.

get_module_version Method (CBFS Struct)

Retrieves the version of a given product module.

Syntax

fn get_module_version(&self, product_guid : &String, module : i32) ->  Result<i64, CBFSConnectError>

Remarks

This method retrieves the version of the product module specified by Module. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the specified module is not installed, this method returns 0.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

The Module parameter specifies which driver module to query the status of. Possible values are:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBFSShellHelper24.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the get_driver_status method.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

get_originator_process_id Method (CBFS Struct)

Retrieves the Id of the process (PID) that initiated the operation (Windows only).

Syntax

fn get_originator_process_id(&self) ->  Result<i32, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time (though in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as on_read_file and on_write_file, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the on_create_file or on_open_file event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

get_originator_process_name Method (CBFS Struct)

Retrieves the name of the process that initiated the operation (Windows only).

Syntax

fn get_originator_process_name(&self) ->  Result<String, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Applications cannot use this method to retrieve information about remote processes accessing virtual drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as on_read_file and on_write_file, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the on_create_file or on_open_file event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

get_originator_thread_id Method (CBFS Struct)

Retrieves the Id of the thread that initiated the operation (Windows only).

Syntax

fn get_originator_thread_id(&self) ->  Result<i32, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.

Please note that thread Ids are not unique, and may be reused by different threads over time.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as on_read_file and on_write_file, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the on_create_file or on_open_file event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

get_originator_token Method (CBFS Struct)

Retrieves the security token associated with the process that initiated the operation (Windows only).

Syntax

fn get_originator_token(&self) ->  Result<i64, CBFSConnectError>

Remarks

This method can be called within certain events to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process. This is particularly useful for implementing custom security checks; please refer to the Security Checks topic for more information.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

For virtual drives shared on the network, applications may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

  • Authenticated mode, in which case the Helper DLL (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
  • Guest mode, in which case the retrievable information is for the system's GUEST account.
  • Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files , such as on_read_file and on_write_file, since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

  1. Call this method within the on_create_file or on_open_file event.
  2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
  3. In a later event, access the information via the reference stored in HandleContext.
Please refer to the Contexts topic for more information on how to use events' context parameters.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

initialize Method (CBFS Struct)

This method initializes the struct.

Syntax

fn initialize(&self, product_guid : &String) -> Option<CBFSConnectError>

Remarks

This method initializes the struct and must be called each time the application starts before attempting to call any of the struct's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

If the required driver was not installed using the install method with the same value of ProductGUID, initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the install method is required before the struct can be used.

install Method (CBFS Struct)

Installs (or upgrades) the product's system drivers and/or the helper DLL (Windows only).

Syntax

fn install(&self, cab_file_name : &String, product_guid : &String, path_to_install : &String, modules_to_install : i32, flags : i32) ->  Result<i32, CBFSConnectError>

Remarks

This method is used to install or upgrade the product's various modules (i.e., the system drivers and the Helper DLL). The ModulesToInstall parameter selects which modules should be installed. If the system must be rebooted to complete the installation process, this method will return a non-zero value indicating which module(s) requested the reboot (out of those initially selected).

Important: To upgrade the product's modules, use only the install method. Previously installed versions of the modules should not be uninstalled first. Calling the install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the .cab file containing the product modules. Important: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required for uninstalling the modules from the system.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

PathToInstall controls where the modules are installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

ModulesToInstall should contain one or more of the following flags, OR'd together:

MODULE_PNP_BUS0x00000001PnP Bus Driver (.sys file).

This module must be installed if the application wishes to make use of Plug-and-Play (PnP) storage features. PnP storage devices are those visible as disks in the Device Manager, and the system treats such storage devices differently from other purely virtual devices.

The filesystem driver must be reinstalled any time this module is added or removed.

MODULE_DRIVER0x00000002Core Product Driver (.sys file).

The product's filesystem driver module provides the core of its functionality; it must be installed for the product to function correctly.

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBFSShellHelper24.dll)

This module provides supplementary functionality; please refer to the Helper DLL topic for more information.

Note: This module is not applicable when calling the get_driver_status method.

Flags specifies various installation options, and should contain zero or more of the following flags, OR'd together:

INSTALL_REMOVE_OLD_VERSIONS0x00000001Uninstall drivers and helper DLLs from previous struct versions (e.g., 2017).

Note: This functionality is only available in Windows. This flag does not remove the old PnP driver (VPnpBus) from the system because that driver is not versioned. Use the installer DLL of the old version and its Uninstall() function if you need to uninstall the PnP driver.

INSTALL_KEEP_START_TYPE0x00000002Keep the driver's current start type setting in the registry.

If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application itself) set it previously.

Note: This functionality is only available in Windows.

INSTALL_OVERWRITE_SAME_VERSION0x00000004Install files when their version is the same as the version of already installed files.

If this flag is not set (default), the installation logic will overwrite the existing file only if the version number of the file being installed is larger than the version of the file being overwritten. Setting this flag causes the installation logic to overwrite the file even when it has the same version.

Note: This functionality is only available in Windows.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD () error.

Note: This method cannot be called within events.

is_cbfs_volume Method (CBFS Struct)

This method checks whether the specified volume is powered by CBFS.

Syntax

fn is_cbfs_volume(&self, volume_path : &String) ->  Result<bool, CBFSConnectError>

Remarks

This method checks to see whether the volume specified by VolumePath is powered by CBFS; if it is, this method returns true.

Valid formats for VolumePath include the following:

  • Drive letters, like X:.
  • Volume GUIDs, like Volume{676D0357-A23A-49C3-B433-65AAD72DD282}.

is_icon_registered Method (CBFS Struct)

Checks whether the specified icon is registered (Windows only).

Syntax

fn is_icon_registered(&self, icon_id : &String) ->  Result<bool, CBFSConnectError>

Remarks

This method checks whether an icon with the specified IconId has been registered. If such an icon has been registered, this method returns true; otherwise it returns false.

Icons can be registered using the register_icon method. Please refer to that method's documentation, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the get_module_version method, and install it using the install method if necessary.

mount_media Method (CBFS Struct)

This method mounts media in the virtual drive, making it accessible for reading and writing.

Syntax

fn mount_media(&self, timeout : i32) -> Option<CBFSConnectError>

Remarks

After using create_storage to create a virtual drive, applications should call this method to "insert storage media" into it. For plug-and-play virtual drives with nonremovable media (see storage_type), this method must be called before add_mounting_point is called. For all other virtual drives, add_mounting_point can be called before or after calling this method.

Timeout specifies how many milliseconds the driver will wait for events to execute before canceling the underlying OS requests ; please refer to the Timeouts topic for more information . Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. (Passing a nonzero value less than 3000 will cause this method to fail with an ERROR_IMPLEMENTATION_LIMIT (1292, 0x50C) error code.)

When event timeouts are in effect, event handlers can call reset_timeout to reset the timer if they require additional time to complete an operation.

Note: A number of properties cannot be changed once media is mounted. Such restrictions are noted in properties' documentation as applicable.

If this method encounters any issues during its execution, it , and additional information is logged to the Windows system log as described in the Error Handling topic.

Note: This method can be called only after creating a virtual drive, and it cannot be called within events.

Virtual Drives, Media, and Mounting Points

In the FUSE struct, a mount point is specified as a parameter of the mount method. Mounting includes both creation of a drive (virtual device) and mounting a media into this device.

The information below applies to the CBFS struct.

When applications call the create_storage method, a virtual drive is created. Virtual drives are created without any "media" in them (like a CD drive without a CD inserted), and without any mounting points (drive letters, UNC paths, etc.).

After creating a virtual drive, applications should call mount_media to "insert" virtual storage media into the virtual drive. This call will cause the struct's events to start firing; applications must handle these events correctly, or the mount_media call will fail.

Once media has been mounted in the virtual drive, applications should use the add_mounting_point method to add one or more mounting points for the virtual drive. These mounting points make the virtual drive, visible to the system and other applications, allowing them to start accessing the contents of the CBFS-based virtual filesystem.

Note that applications can technically call add_mounting_point before mount_media (except for plug-and-play virtual drives with non-removable media; see storage_type), but any attempts to access a virtual drive with no media mounted will result in a "no media" error.

notify_directory_change Method (CBFS Struct)

This method notifies the OS that a file or directory has changed.

Syntax

fn notify_directory_change(&self, file_name : &String, action : i32, new_file_name : &String, wait : bool) ->  Result<bool, CBFSConnectError>

Remarks

If a file or directory is modified by some means external to the virtual filesystem, this method should be called to notify the OS. Doing so prompts the OS to make any requests necessary to obtain the most up-to-date information, which in turn fires the relevant struct events. This method returns either true or false to indicate whether it executed successfully.

Applications must be careful to call this method only when some changes have occurred that the OS has no possibility of detecting on its own. Said another way, applications should not call this method to notify the OS of changes made by invoking filesystem APIs on files or directories in the virtual filesystem; such changes are inherently visible to OS.

For further clarity, the following examples describe scenarios in which notify_directory_change should and should not be called:

  • DO call notify_directory_change if, for example, the application is in charge of mapping the contents of some database to its virtual filesystem, and an external process changes the database's contents directly. The OS only knows about the filesystem, it does not know or care about the database contents; thus, the application must notify it that "something has changed".
  • DO NOT call notify_directory_change if, for example, the application has created a virtual drive Z:, and either it or some other process makes a filesystem call against the virtual drive's contents; for example, DeleteFile("Z:\SomeFile.txt"). The OS detects such a change automatically because it was made through the filesystem APIs.

FileName specifies the path to the file or directory (in the virtual drive) that has changed. This path must not include a mounting point name.

Several files or directories may be referenced in this parameter at once. To specify the exact names, join the paths with CRLF (characters with numeric codes 13 and 10) and pass the final string to FileName. The paths may reference files and directories in different parent directories.

An application also may specify the path with a mask. When passing a mask, only the file name portion of the mask may contain wildcard characters (* and ?). Such mask will denote multiple entries in a single directory. The struct will fire the on_enumerate_directory event with the specified mask to collect the names of files and subdirectories, next they will be reported as changed.

Note: When the on_enumerate_directory event is fired, its HandleInfo, DirectoryContext, and HandleContext parameters will be empty because no system-initiated enumeration takes place and the directory is not opened.

Action specifies the type of change so that the OS knows what kind of information it needs to request. Possible values are as follows:

CBFS_NOTIFY_FLAG_ADDED0x00000001The specified file or directory has been created.

CBFS_NOTIFY_FLAG_REMOVED0x00000002The specified file or directory has been removed.

For directories, all handles to files in the directory are immediately closed.

CBFS_NOTIFY_FLAG_MODIFIED0x00000003The specified file or directory has been modified.

For files, use this option when the file's contents have changed. For directories, use this option when a change is made in alternate data streams that belong to the directory.

If a directory is reported as modified, all handles to files in the directory are immediately invalidated.

CBFS_NOTIFY_FLAG_METADATA_MODIFIED0x00000004The timestamp or other attributes of the specified file or directory have been modified.

CBFS_NOTIFY_FLAG_ALLOCATION_SIZE_MODIFIED0x00000005The allocation size for the specified file or directory has been modified.

This option is applicable only if CorrectAllocationSizes is false.

CBFS_NOTIFY_FLAG_MODIFIED_NOT_INVALIDATE0x00000006The specified file or directory has been modified, but handles should not be invalidated.

Note: Using this option can cause other applications to operate using stale data if they keep the specified file or directory open, because they have no way to know about the external changes.

CBFS_NOTIFY_FLAG_RENAMED0x00000007The specified file or directory has been renamed.

This flag updates the internally stored name and does not invalidate existing handles (if any exist).

CBFS_NOTIFY_FLAG_SKIP_LOCKED_FILE0x00001000Ignore the request if the file has locked ranges.

This supplementary flag may be used together with the CBFS_NOTIFY_FLAG_MODIFIED_NOT_INVALIDATE flag to tell the driver that if the file has locked ranges, the notification should be ignored.

NewFileName specifies the new path/name of the file or directory (in the virtual drive) if the rename operation was performed. In other cases, the value is ignored.

Wait specifies whether this method should wait until the OS has finished making all of the requests necessary to handle the notification sent by this method. Passing true will cause this method to block until all requests are complete. Passing false will cause it to send the notification to the OS and return immediately, letting the OS make the necessary requests in the background. In the latter case, this method returns false.

Note: This method can be called only when active is true. It may be called both within and outside of events; when called within an event, the Wait parameter is ignored and is assumed to be set to false.

If this method encounters any issues during its execution, it .

register_icon Method (CBFS Struct)

Registers an icon that can be displayed as an overlay on the virtual drive in Windows File Explorer (Windows only).

Syntax

fn register_icon(&self, icon_path : &String, product_guid : &String, icon_id : &String) ->  Result<bool, CBFSConnectError>

Remarks

This method registers an icon in the file specified by IconPath so that it can later be used to display an overlay on the virtual drive in Windows File Explorer. If the system must be rebooted before the icon can be used, this method returns true, otherwise it returns false.

Please note that this method only registers overlay icons; Applications should call the set_icon and reset_icon methods to select an icon for display. Please refer to the Custom Drive Icons topic for more information.

IconPath must be the full path and file name of the .ico file whose icon should be registered. The file must exist and remain available in order for the icon to be used until the icon is unregistered using unregister_icon.

ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.

The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.

To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

IconId specifies an identifier that can later be passed to the set_icon and unregister_icon methods. Each registered icon should have a unique IconId value; if a value is passed that is already in use, the existing icon will be removed (by calling unregister_icon internally) before the new one is registered.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter. The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the get_module_version method, and install it using the install method if necessary.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD () error.

Note: This method cannot be called within events.

release_unused_files Method (CBFS Struct)

This method instructs the OS to release any files kept open by the cache manager.

Syntax

fn release_unused_files(&self) ->  Result<bool, CBFSConnectError>

Remarks

This method instructs the OS to release any files that the system cache manager has kept open, and returns either true or false to indicate whether the files were released successfully. Having the OS release open files can be useful in situations in which operations need to be performed while the filesystem is not in use.

Note: The OS may open additional files during the execution of this method. To guard against this, it is recommended that application use a critical section (or other synchronization object) when calling this method, and use the same one in the on_open_file event handler. Such an approach ensures that the cache manager has no files open after calling this method.

Note: This method can be called only when active is true. It may be called both within and outside of events; when called within an event, it is executed asynchronously on another thread (causing the call to return immediately, and an ERROR_IO_PENDING result code to be reported to the OS).

remove_denied_process Method (CBFS Struct)

Removes a rule that prevents a process from accessing the virtual drive (Windows only).

Syntax

fn remove_denied_process(&self, process_file_name : &String, process_id : i32) -> Option<CBFSConnectError>

Remarks

When the process_restrictions_enabled property is enabled, this method can be used to remove an access rule previously added with the add_denied_process method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when add_denied_process was called previously. Please refer to that method's documentation for more information.

Note: This method can be called only when active is true, and it cannot be called within events.

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

remove_granted_process Method (CBFS Struct)

Removes a rule that allows a process to access the virtual drive (Windows only).

Syntax

fn remove_granted_process(&self, process_file_name : &String, process_id : i32) -> Option<CBFSConnectError>

Remarks

When the process_restrictions_enabled property is enabled, this method can be used to remove an access rule previously added with the add_granted_process method.

Pass the same values for ProcessFileName and ProcessId as were used to add the rule when add_granted_process was called previously. Please refer to that method's documentation for more information.

Note: This method can be called only when active is true, and it cannot be called within events.

The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.

remove_mounting_point Method (CBFS Struct)

Removes a mounting point for the virtual drive.

Syntax

fn remove_mounting_point(&self, index : i32, mounting_point : &String, flags : i32, authentication_id : i64) -> Option<CBFSConnectError>

Remarks

This method removes a previously-created mounting point for the virtual drive.

Index must be set to the index of an item in the MountingPoint* properties, or to -1 to remove an item based on the other method parameters.

If Index is -1, then the same values must be passed for MountingPoint, Flags, AuthenticationId as were used to add the mounting point when add_mounting_point was called previously. Please refer to that method's documentation for more information. (If Index is not -1, these parameters are ignored.)

The sgSTGMPDRIVELETTERNOTIFYASYNC; flag may be passed in Flags to send notifications about removal of the mounting point asynchronously. Do not use this flag if the process quits right after a call to this method because asynchronous delivery involves a secondary thread, which will be terminated when the process quits.

To remove a virtual drive, created in a container from the host, set the container's Id via the DockerContainerId configuration setting prior to calling remove_mounting_point.

Note: This method cannot be called within events.

The methods and properties related to mounting points are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of mounting points occurs in a thread-safe manner.

reset_icon Method (CBFS Struct)

Resets the virtual drive's icon back to default by deselecting the active overlay icon (Windows only).

Syntax

fn reset_icon(&self) -> Option<CBFSConnectError>

Remarks

This method deselects the overlay icon currently in use, thus resetting the virtual drive's icon back to its default state (i.e., displayed without any overlay icons).

Please refer to the set_icon method, as well as the Custom Drive Icons topic, for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the get_module_version method, and install it using the install method if necessary.

Note: This method can be called only after creating a virtual drive, and it cannot be called within events.

reset_timeout Method (CBFS Struct)

This method resets the timeout duration for the current event handler.

Syntax

fn reset_timeout(&self, timeout : i32) ->  Result<bool, CBFSConnectError>

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the struct that request processing is taking longer than expected.

If called successfully, this method returns true, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will cancel the underlying OS request. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

Note: When several events are fired for the same file concurrently (if the serialize_access property is set to false), and reset_timeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

Note: This method can be called only within events.

route_to_file Method (CBFS Struct)

This method instructs the struct to route future requests directly to a given file.

Syntax

fn route_to_file(&self, file_info : i64, file_name : &String, flags : i32) ->  Result<bool, CBFSConnectError>

Remarks

This method can be called from within the on_create_file or on_open_file event to instruct the struct to route any future requests against the file specified by FileInfo directly to the file at the path specified by FileName instead of firing the corresponding events. The Flags parameter is used to specify which kinds of requests should not be routed automatically (see below).

Pass the value obtained from the on_create_file or on_open_file event's FileInfo parameter for this method's FileInfo parameter.

This method returns either true or false to indicate whether routing was set up successfully. If, after this method is called successfully, the application later wishes for routing to cease, it may do one of the following:

The Flags value should be created by ORing together zero or more of the following flags:

CBFS_ROUTE_FILE_READ_ONLY0x00000001Causes files to be treated as read-only; all write operations will be automatically denied.

CBFS_ROUTE_OPEN_EVENT0x00000020Prevents 'open' requests from being routed automatically.

If set, the on_open_file event will fire as usual when such requests arrive.

Note: This flag is implied if any of the other CBFS_ROUTE_*_EVENT flags are present.

CBFS_ROUTE_CLEANUP_EVENT0x00000040Prevents 'cleanup' requests from being routed automatically.

If set, the on_cleanup_file event will fire as usual when such requests arrive.

CBFS_ROUTE_CLOSE_EVENT0x00000080Prevents 'close' requests from being routed automatically.

If set, the on_close_file event will fire as usual when such requests arrive.

Note: This flag is implied if any of the other CBFS_ROUTE_*_EVENT flags are present.

CBFS_ROUTE_ENUMERATE_DIRECTORY_EVENT0x00000200Prevents 'enumerate directory' requests from being routed automatically.

If set, the on_enumerate_directory event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_SECURITY_EVENT0x00000400Prevents 'set security' requests from being routed automatically.

If set, the on_set_file_security event will fire as usual when such requests arrive.

CBFS_ROUTE_GET_SECURITY_EVENT0x00000800Prevents 'get security' requests from being routed automatically.

If set, the on_get_file_security event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_FILE_ATTRIBUTES_EVENT0x00002000Prevents 'set file attributes' requests from being routed automatically.

If set, the on_set_file_attributes event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_FILE_SIZES_EVENT0x00004000Prevents 'set file size' requests from being routed automatically.

If set, the on_set_file_size event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_VALID_DATA_LENGTH_EVENT0x00008000Prevents 'set valid data length' requests from being routed automatically.

If set, the on_open_file event will fire as usual when such requests arrive.

CBFS_ROUTE_CREATE_HARD_LINK_EVENT0x00020000Prevents 'create hard link' requests from being routed automatically.

If set, the on_create_hard_link event will fire as usual when such requests arrive.

CBFS_ROUTE_QUERY_QUOTA_EVENT0x00040000Prevents 'query quota' requests from being routed automatically.

If set, the on_query_quotas event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_QUOTA_EVENT0x00080000Prevents 'set quota' requests from being routed automatically.

If set, the on_set_quotas event will fire as usual when such requests arrive.

CBFS_ROUTE_CAN_FILE_BE_DELETED_EVENT0x00200000Prevents 'can file be deleted' requests from being routed automatically.

If set, the on_can_file_be_deleted event will fire as usual when such requests arrive.

CBFS_ROUTE_IS_DIRECTORY_EMPTY_EVENT0x00400000Prevents 'is directory empty' requests from being routed automatically.

If set, the on_is_directory_empty event will fire as usual when such requests arrive.

CBFS_ROUTE_RENAME_EVENT0x00800000Prevents 'rename/move' requests from being routed automatically.

If set, the on_rename_or_move_file event will fire as usual when such requests arrive.

CBFS_ROUTE_SET_EA_EVENT0x01000000Prevents 'set ea' requests from being routed automatically.

If set, the on_set_ea event will fire as usual when such requests arrive.

CBFS_ROUTE_QUERY_EA_EVENT0x02000000Prevents 'query ea' requests from being routed automatically.

If set, the on_query_ea event will fire as usual when such requests arrive.

Note: This method can be called only within the on_create_file and on_open_file event handlers.

set_icon Method (CBFS Struct)

Selects a registered overlay icon for display on the virtual drive in Windows File Explorer (Windows only).

Syntax

fn set_icon(&self, icon_id : &String) -> Option<CBFSConnectError>

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual drive in Windows File Explorer. The desired icon must have already been registered using the register_icon method, and the value passed for IconId must match the one passed register_icon at that time.

To switch to a different overlay icon later, call this method again with a different IconId. To reset the virtual drive's icon back to its default state (i.e., displayed without any overlay icons), call the reset_icon method. Please refer to the Custom Drive Icons topic for more information.

The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the get_module_version method, and install it using the install method if necessary.

Note: This method can be called only after creating a virtual drive, and it cannot be called within events. Also, note that the effects of this method only last until the virtual drive is destroyed; applications that always want to have some overlay icon displayed must call this method each time the virtual drive is created.

shutdown_system Method (CBFS Struct)

Shuts down or reboots the operating system.

Syntax

fn shutdown_system(&self, shutdown_prompt : &String, timeout : i32, force_close_apps : bool, reboot : bool) ->  Result<bool, CBFSConnectError>

Remarks

This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (true) or just shut down (false).

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

uninstall Method (CBFS Struct)

Uninstalls the product's system drivers and/or helper DLL (Windows only).

Syntax

fn uninstall(&self, cab_file_name : &String, product_guid : &String, installed_path : &String, flags : i32) ->  Result<i32, CBFSConnectError>

Remarks

This method is used to uninstall the product's various modules (i.e., the system drivers and Helper DLL). If the system must be rebooted to complete the uninstallation process, this method will return a non-zero value indicating which module(s) requested the reboot (see install for possible values).

Important: To upgrade the product's modules, use only the install method. Previously installed versions of the modules should not be uninstalled first. Calling the install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when install was called; please refer to its documentation for more information.

Flags specifies which versions of the product's modules should be uninstalled, and should be set by OR'ing together one or more of the following values:

UNINSTALL_VERSION_PREVIOUS0x00000001Uninstall modules from previous product versions.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_ALL0x00000003Uninstall modules from all product versions.

Note: This functionality is only available in Windows.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD () error.

Note: This method cannot be called within events.

unmount_media Method (CBFS Struct)

This method unmounts media from the virtual drive.

Syntax

fn unmount_media(&self, force_unmount : bool) -> Option<CBFSConnectError>

Remarks

This method unmounts the virtual storage media from the virtual drive. The virtual drive, as well as any existing mounting points, remain present.

If ForceUnmount is true, all open files are forcefully closed. If ForceUnmount is false and open files or directories are detected, this method .

This method must not be called for plug-and-play virtual drives with nonremovable media (see storage_type); attempting to do so will cause the call will fail with an "access denied" error.

Note: This method can be called only after creating a virtual drive, and it cannot be called within events.

unregister_icon Method (CBFS Struct)

Unregisters an existing overlay icon (Windows only).

Syntax

fn unregister_icon(&self, product_guid : &String, icon_id : &String) ->  Result<bool, CBFSConnectError>

Remarks

This method unregisters the overlay icon identified by IconId. If the system must be rebooted to completely remove the icon, this method returns true, otherwise it returns false.

The same values must be passed for the ProductGUID and IconId parameters as were passed when register_icon was called; please refer to its documentation, as well as the Custom Drive Icons topic, for more information.

This method is available in both the struct API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter. The Helper DLL must be installed in order for this method to function correctly. Applications can check to see whether the Helper DLL is installed using the get_module_version method, and install it using the install method if necessary.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD () error.

Note: This method cannot be called within events.

on_can_file_be_deleted Event (CBFS Struct)

This event fires when the driver needs to know whether a file or directory can be deleted.

Syntax

// CBFSCanFileBeDeletedEventArgs carries the CBFS CanFileBeDeleted event's parameters.
pub struct CBFSCanFileBeDeletedEventArgs {
  fn file_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn can_be_deleted(&self) -> bool
  fn set_can_be_deleted(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCanFileBeDeletedEvent defines the signature of the CBFS CanFileBeDeleted event's handler function.
pub trait CBFSCanFileBeDeletedEvent {
  fn on_can_file_be_deleted(&self, sender : CBFS, e : &mut CBFSCanFileBeDeletedEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_can_file_be_deleted(&self) -> &'a dyn CBFSCanFileBeDeletedEvent;
  pub fn set_on_can_file_be_deleted(&mut self, value : &'a dyn CBFSCanFileBeDeletedEvent);
  ...
}

Remarks

This event fires when the driver needs to know whether the file or directory specified by FileName can be deleted.

To handle this event properly, applications must set the CanBeDeleted parameter appropriately.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Note: The firing of this event does not necessarily mean the specified file or directory will be deleted if CanBeDeleted is set to true. It means only that the OS needs to know whether or not it can be deleted.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_cleanup_file Event (CBFS Struct)

This event fires when the OS needs to clean up a file.

Syntax

// CBFSCleanupFileEventArgs carries the CBFS CleanupFile event's parameters.
pub struct CBFSCleanupFileEventArgs {
  fn file_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCleanupFileEvent defines the signature of the CBFS CleanupFile event's handler function.
pub trait CBFSCleanupFileEvent {
  fn on_cleanup_file(&self, sender : CBFS, e : &mut CBFSCleanupFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_cleanup_file(&self) -> &'a dyn CBFSCleanupFileEvent;
  pub fn set_on_cleanup_file(&mut self, value : &'a dyn CBFSCleanupFileEvent);
  ...
}

Remarks

This event fires when the OS needs to close a handle to the currently open file specified by FileName. This event differs from on_close_file in that on_cleanup_file fires immediately when an open handle to the specified file is closed by a process, whereas on_close_file may be fired much later when the OS itself decides that the file can be formally closed. Similar to on_close_file, however, this event will fire only for the last handle to a file if the fire_all_open_close_events property is disabled.

Other events may fire for the file handle in the time between when this event fires and when the on_close_file event fires. For example, system components such as the memory manager or cache manager may cause the on_read_file and on_write_file events to fire.

This event is optional; it is provided to give applications a chance to, for example, free up resources associated with a file before it's formally closed.

When the fire_all_open_close_events is set to false, this event is fired each time the file is closed by the application. When the file is opened and closed by some process multiple times consequently, the event handler can end up being called multiple times seemingly without a match with the on_open_file and on_close_file . However, such behavior is correct. The exact order of Open/Cleanup/Close events cannot be guaranteed because of the way Windows closes files.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_close_directory_enumeration Event (CBFS Struct)

This event fires when the OS is finished enumerating a directory's contents.

Syntax

// CBFSCloseDirectoryEnumerationEventArgs carries the CBFS CloseDirectoryEnumeration event's parameters.
pub struct CBFSCloseDirectoryEnumerationEventArgs {
  fn directory_name(&self) -> &String
  fn directory_context(&self) -> usize
  fn set_directory_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCloseDirectoryEnumerationEvent defines the signature of the CBFS CloseDirectoryEnumeration event's handler function.
pub trait CBFSCloseDirectoryEnumerationEvent {
  fn on_close_directory_enumeration(&self, sender : CBFS, e : &mut CBFSCloseDirectoryEnumerationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_close_directory_enumeration(&self) -> &'a dyn CBFSCloseDirectoryEnumerationEvent;
  pub fn set_on_close_directory_enumeration(&mut self, value : &'a dyn CBFSCloseDirectoryEnumerationEvent);
  ...
}

Remarks

This event fires when the OS is finished enumerating the contents of the directory specified by DirectoryName.

To handle this event properly, applications must release any resources that were allocated for/by the directory enumeration in earlier on_enumerate_directory events.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The DirectoryContext and EnumerationContext parameters are placeholders for application-defined data associated with the directory and enumeration, respectively. Please refer to the Contexts topic for more information about them.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_close_file Event (CBFS Struct)

This event fires when the OS needs to close a file.

Syntax

// CBFSCloseFileEventArgs carries the CBFS CloseFile event's parameters.
pub struct CBFSCloseFileEventArgs {
  fn file_name(&self) -> &String
  fn pending_deletion(&self) -> bool
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCloseFileEvent defines the signature of the CBFS CloseFile event's handler function.
pub trait CBFSCloseFileEvent {
  fn on_close_file(&self, sender : CBFS, e : &mut CBFSCloseFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_close_file(&self) -> &'a dyn CBFSCloseFileEvent;
  pub fn set_on_close_file(&mut self, value : &'a dyn CBFSCloseFileEvent);
  ...
}

Remarks

This event fires when the OS needs to close the file specified by FileName. If the fire_all_open_close_events property is disabled, this event will fire only after the last handle to the specified file is closed.

To handle this event properly, applications can (if necessary/applicable) check to see if any other handles are open for the file, and if not, close whatever backend resources are currently open for it.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The PendingDeletion parameter indicates whether the file should be deleted; if it's true, the on_delete_file event will fire immediately after this event. The application may delete the file from either event handler.

If an application uses some object to store user context, uses FileContext to store the reference to this object, and deletes an object referenced in FileContext, the pointer stored in FileContext becomes invalid. In this scenario, if the PendingDeletion parameter is true, the on_delete_file event will fire with the invalid value in its FileContext parameter. The solution to this issue is to inspect the value of the DeleteFile parameter and if it is true, postpone deletion of the object referenced in FileContext until the on_delete_file event. Alternatively, an event handler may set FileContext to an empty value, in which case, a on_delete_file event handler will receive that empty value as a file context.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Note: The OS sends a file close request asynchronously, which is later than a process closes its handle(s) to the opened file. Because of this, the result code returned by the event handler does not get back to the process that closed the file handle.

on_close_hard_links_enumeration Event (CBFS Struct)

This event fires when the OS is finished enumerating a file's hard links.

Syntax

// CBFSCloseHardLinksEnumerationEventArgs carries the CBFS CloseHardLinksEnumeration event's parameters.
pub struct CBFSCloseHardLinksEnumerationEventArgs {
  fn file_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCloseHardLinksEnumerationEvent defines the signature of the CBFS CloseHardLinksEnumeration event's handler function.
pub trait CBFSCloseHardLinksEnumerationEvent {
  fn on_close_hard_links_enumeration(&self, sender : CBFS, e : &mut CBFSCloseHardLinksEnumerationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_close_hard_links_enumeration(&self) -> &'a dyn CBFSCloseHardLinksEnumerationEvent;
  pub fn set_on_close_hard_links_enumeration(&mut self, value : &'a dyn CBFSCloseHardLinksEnumerationEvent);
  ...
}

Remarks

This event fires when the OS is finished enumerating the hard links of the file specified by FileName.

This event needs to be handled only if the use_hard_links property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the hard link enumeration in earlier on_enumerate_hard_links events.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_close_named_streams_enumeration Event (CBFS Struct)

This event fires when the OS is finished enumerating a file's named streams.

Syntax

// CBFSCloseNamedStreamsEnumerationEventArgs carries the CBFS CloseNamedStreamsEnumeration event's parameters.
pub struct CBFSCloseNamedStreamsEnumerationEventArgs {
  fn file_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCloseNamedStreamsEnumerationEvent defines the signature of the CBFS CloseNamedStreamsEnumeration event's handler function.
pub trait CBFSCloseNamedStreamsEnumerationEvent {
  fn on_close_named_streams_enumeration(&self, sender : CBFS, e : &mut CBFSCloseNamedStreamsEnumerationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_close_named_streams_enumeration(&self) -> &'a dyn CBFSCloseNamedStreamsEnumerationEvent;
  pub fn set_on_close_named_streams_enumeration(&mut self, value : &'a dyn CBFSCloseNamedStreamsEnumerationEvent);
  ...
}

Remarks

This event fires when the OS is finished enumerating the named streams of the file specified by FileName.

This event needs to be handled only if the use_alternate_data_streams property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the named stream enumeration in earlier on_enumerate_named_streams events.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_close_quotas_enumeration Event (CBFS Struct)

This event fires when the OS is finished reading or updating quota information.

Syntax

// CBFSCloseQuotasEnumerationEventArgs carries the CBFS CloseQuotasEnumeration event's parameters.
pub struct CBFSCloseQuotasEnumerationEventArgs {
  fn enumeration_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCloseQuotasEnumerationEvent defines the signature of the CBFS CloseQuotasEnumeration event's handler function.
pub trait CBFSCloseQuotasEnumerationEvent {
  fn on_close_quotas_enumeration(&self, sender : CBFS, e : &mut CBFSCloseQuotasEnumerationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_close_quotas_enumeration(&self) -> &'a dyn CBFSCloseQuotasEnumerationEvent;
  pub fn set_on_close_quotas_enumeration(&mut self, value : &'a dyn CBFSCloseQuotasEnumerationEvent);
  ...
}

Remarks

This event fires when the OS is finished reading or updating quota information.

This event only needs to be handled if the use_disk_quotas property is enabled. To handle this event properly, applications must release any resources that were allocated for/by the quota enumeration in earlier on_query_quotas or on_set_quotas events.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_create_file Event (CBFS Struct)

This event fires when the OS wants to create a file or directory.

Syntax

// CBFSCreateFileEventArgs carries the CBFS CreateFile event's parameters.
pub struct CBFSCreateFileEventArgs {
  fn file_name(&self) -> &String
  fn desired_access(&self) -> i32
  fn attributes(&self) -> i32
  fn share_mode(&self) -> i32
  fn nt_create_disposition(&self) -> i32
  fn nt_desired_access(&self) -> i32
  fn file_info(&self) -> i64
  fn handle_info(&self) -> i64
  fn reserved(&self) -> bool
  fn set_reserved(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCreateFileEvent defines the signature of the CBFS CreateFile event's handler function.
pub trait CBFSCreateFileEvent {
  fn on_create_file(&self, sender : CBFS, e : &mut CBFSCreateFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_create_file(&self) -> &'a dyn CBFSCreateFileEvent;
  pub fn set_on_create_file(&mut self, value : &'a dyn CBFSCreateFileEvent);
  ...
}

Remarks

This event fires when the OS wants to create a file or directory named FileName using the creation options reflected in Attributes. If the fire_all_open_close_events property is disabled, this event will fire only when the first handle to the specified file or directory is opened. To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY;

If the use_alternate_data_streams property is enabled, this event also fires any time the OS wants to create a named datastream in a file. Such requests are distinguished by the presence of a colon (:) in the FileName value; the text before the colon is the name of the file itself, and the text after the colon is the name of the stream to create.

To handle this event properly, applications should (at least) perform any actions needed to create and/or open the requested file, directory, or named stream in their backend storage. Applications are also responsible for validating the access rights of the process that initiated the request before performing the requested operation; please refer to the Security Checks topic for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

If an existing local file corresponds to the virtual one specified by FileName, the application may call route_to_file to have the struct route future requests directly to that file. This event's FileInfo value must be passed to route_to_file to request routing to be configured successfully.

In certain cases, a request to open an existing file may unexpectedly be surfaced through this event instead of through on_open_file. Normally, this will not happen, as the OS already knows which files exist (based on information obtained via on_get_file_info/on_enumerate_directory) before it sends the create or open request. If, however, a file is created externally, a rare condition may occur in which said file exists but is not known to the OS or the virtual filesystem yet. In such cases, the application must decide how to handle the unexpected on_create_file event; it can either truncate the existing file, or return the ERROR_ALREADY_EXISTS error code via ResultCode.

If an original call to CreateFile() or a similar Windows API function included security attributes, the on_set_file_security event will immediately follow this CreateFile event, and the mentioned security attributes will be passed via on_set_file_security.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request; it may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

This value may differ from the one originally passed to the OS; the struct alters it in the following cases:

  • The DELETE flag is added if the requested CreateDisposition is FILE_SUPERSEDE.
  • The FILE_WRITE_DATA, FILE_WRITE_EA, and FILE_WRITE_ATTRIBUTES flags are added if the requested CreateDisposition is FILE_OVERWRITE or FILE_OVERWRITE_IF.
The original CreateDisposition and DesiredAccess values are exposed through the NTCreateDisposition and NTDesiredAccess parameters.

Note: These values are in NT format; that is, as expected by the Windows API's ZwCreateFile function.

The Attributes parameter contains file attributes; it may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the support_compressed_attribute property to true and then properly handling the on_get_file_info, on_enumerate_directory, and on_set_file_attributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

Attributes specifies both the attributes and create/open options for the new file. Some options, such as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, and FILE_FLAG_RANDOM_ACCESS, may be useful for applications that wish to fine-tune their performance. For example, such information could be used to decide whether it is necessary to locally cache some amount of data that is stored remotely.

The ShareMode parameter specifies the access sharing mode desired by the process that initiated the request; it may contain zero or more of the following share mode flags:

FILE_SYS_SHARE_READ0x00000001Enables subsequent open operations on a file to request read access.

Otherwise, other processes cannot open the file if they request read access. If this flag is not specified, but the file has been opened for read access, file creation or opening fails.

FILE_SYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file to request write access.

Otherwise, other processes cannot open the file if they request write access. If this flag is not specified, but the file has been opened for write access or has a file mapping with write access, file creation or opening fails.

FILE_SYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file to request delete access.

Otherwise, other processes cannot open the file if they request delete access. If this flag is not specified, but the file has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

Please refer to the Windows API's ZwCreateFile function for detailed information about possible values for the DesiredAccess, Attributes, ShareMode, NTCreateDisposition, and NTDesiredAccess parameters.

The FileInfo parameter carries a handle to an object with information about the file. As mentioned earlier, this value should be used if the application chooses to call the route_to_file method.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_create_hard_link Event (CBFS Struct)

This event fires when the OS wants to create a new hard link to an existing file.

Syntax

// CBFSCreateHardLinkEventArgs carries the CBFS CreateHardLink event's parameters.
pub struct CBFSCreateHardLinkEventArgs {
  fn file_name(&self) -> &String
  fn link_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSCreateHardLinkEvent defines the signature of the CBFS CreateHardLink event's handler function.
pub trait CBFSCreateHardLinkEvent {
  fn on_create_hard_link(&self, sender : CBFS, e : &mut CBFSCreateHardLinkEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_create_hard_link(&self) -> &'a dyn CBFSCreateHardLinkEvent;
  pub fn set_on_create_hard_link(&mut self, value : &'a dyn CBFSCreateHardLinkEvent);
  ...
}

Remarks

This event fires when the OS wants to create a new hard link that points to the existing file specified by FileName. The LinkName parameter specifies the absolute path (including the file name) of the link to be created.

This event needs to be handled only if the use_hard_links property is enabled. To handle this event properly, applications should perform any actions needed to create an additional hard link to the specified file in their backend storage.

Please refer to the Hard Links topic for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_delete_file Event (CBFS Struct)

This event fires when the OS needs to delete a file or directory.

Syntax

// CBFSDeleteFileEventArgs carries the CBFS DeleteFile event's parameters.
pub struct CBFSDeleteFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSDeleteFileEvent defines the signature of the CBFS DeleteFile event's handler function.
pub trait CBFSDeleteFileEvent {
  fn on_delete_file(&self, sender : CBFS, e : &mut CBFSDeleteFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_delete_file(&self) -> &'a dyn CBFSDeleteFileEvent;
  pub fn set_on_delete_file(&mut self, value : &'a dyn CBFSDeleteFileEvent);
  ...
}

Remarks

This event fires when the OS has decided to delete the file or directory specified by FileName.

To handle this event properly, applications must perform any actions needed to delete the specified file or directory from their backend storage. If the use_hard_links property is enabled, a file's data should be deleted only when its last hard link has been deleted; please refer to the Hard Links topic for more information.

Note:

  • A deletion cannot be canceled from this event; applications that wish to prevent a deletion must do so via the on_can_file_be_deleted event.
  • This event fires immediately after the last on_close_file event. If the application disposes of the FileContext in the on_close_file event handler, it will be invalid when this event fires. The on_close_file event includes a DeleteFile parameter that helps address this situation.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_delete_object_id Event (CBFS Struct)

This event fires when the OS needs to remove the object Id and extended information from a volume or a filesystem entry.

Syntax

// CBFSDeleteObjectIdEventArgs carries the CBFS DeleteObjectId event's parameters.
pub struct CBFSDeleteObjectIdEventArgs {
  fn file_name(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSDeleteObjectIdEvent defines the signature of the CBFS DeleteObjectId event's handler function.
pub trait CBFSDeleteObjectIdEvent {
  fn on_delete_object_id(&self, sender : CBFS, e : &mut CBFSDeleteObjectIdEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_delete_object_id(&self) -> &'a dyn CBFSDeleteObjectIdEvent;
  pub fn set_on_delete_object_id(&mut self, value : &'a dyn CBFSDeleteObjectIdEvent);
  ...
}

Remarks

This event fires when the OS needs to remove the previously set object Id and extended information from the virtual drive volume or one of its files or directories. If the object ID of a file or directory is deleted, this entry is identified with the FileName parameter. If the request is made for the volume, FileName will be empty.

This event removes only the object Id and is not used to delete the filesystem entry or the volume.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_delete_reparse_point Event (CBFS Struct)

This event fires when the OS wants to delete a reparse point from a file or directory.

Syntax

// CBFSDeleteReparsePointEventArgs carries the CBFS DeleteReparsePoint event's parameters.
pub struct CBFSDeleteReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn reparse_buffer_length(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSDeleteReparsePointEvent defines the signature of the CBFS DeleteReparsePoint event's handler function.
pub trait CBFSDeleteReparsePointEvent {
  fn on_delete_reparse_point(&self, sender : CBFS, e : &mut CBFSDeleteReparsePointEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_delete_reparse_point(&self) -> &'a dyn CBFSDeleteReparsePointEvent;
  pub fn set_on_delete_reparse_point(&mut self, value : &'a dyn CBFSDeleteReparsePointEvent);
  ...
}

Remarks

This event fires when the OS wants to delete a reparse point from the file or directory specified by FileName.

This event needs to be handled only if the use_reparse_points property is enabled.

Note: NFS sharing makes use of reparse points.

To handle this event properly, applications must delete the reparse point data (and tag) stored previously for the specified file or directory. Any other actions taken in an earlier on_set_reparse_point event also should be reversed appropriately.

Note: The file or directory itself should not be deleted.

Please refer to the Reparse Points topic for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The existing reparse point data are provided in this event as a convenience for use-cases that wish to utilize it.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_ejected Event (CBFS Struct)

Fires when the media and virtual drive have been ejected (Windows only).

Syntax

// CBFSEjectedEventArgs carries the CBFS Ejected event's parameters.
pub struct CBFSEjectedEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSEjectedEvent defines the signature of the CBFS Ejected event's handler function.
pub trait CBFSEjectedEvent {
  fn on_ejected(&self, sender : CBFS, e : &mut CBFSEjectedEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_ejected(&self) -> &'a dyn CBFSEjectedEvent;
  pub fn set_on_ejected(&mut self, value : &'a dyn CBFSEjectedEvent);
  ...
}

Remarks

This event fires when a user has ejected the media and virtual drive using the Eject command in Windows File Explorer.

For ejection via the system notification area (tray) to work correctly, the storage_type property must be set to STGT_DISK_PNP, and the storage_characteristics property must include ejection-related flags.

This event is optional; it is provided to give applications a chance to, e.g., free up resources associated with the virtual drive. Since the virtual drive has already been destroyed by the time this event fires, applications must not call unmount_media or delete_storage (the latter is called automatically with its ForceUnmount parameter set to true) .

The ResultCode parameter will always be initially set to the result of a storage deletion operation. The expected value is 0. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Note that as ejection has already occured, this non-zero value will not have effect on the media's state. Please refer to the Error Handling topic for more information.

on_enumerate_directory Event (CBFS Struct)

This event fires when the OS wants to enumerate a directory's contents.

Syntax

// CBFSEnumerateDirectoryEventArgs carries the CBFS EnumerateDirectory event's parameters.
pub struct CBFSEnumerateDirectoryEventArgs {
  fn directory_name(&self) -> &String
  fn mask(&self) -> &String
  fn case_sensitive(&self) -> bool
  fn restart(&self) -> bool
  fn requested_info(&self) -> i32
  fn file_found(&self) -> bool
  fn set_file_found(&self, value : bool)
  fn file_name(&self) -> &String
  fn set_file_name(&self, value : String)
  fn set_file_name_ref(&self, value : &String)
  fn short_file_name(&self) -> &String
  fn set_short_file_name(&self, value : String)
  fn set_short_file_name_ref(&self, value : &String)
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn set_creation_time(&self, value : chrono::DateTime<Utc>)
  fn set_creation_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_access_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_access_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_write_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_write_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn set_change_time(&self, value : chrono::DateTime<Utc>)
  fn set_change_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn allocation_size(&self) -> i64
  fn set_allocation_size(&self, value : i64)
  fn file_id(&self) -> i64
  fn set_file_id(&self, value : i64)
  fn attributes(&self) -> i64
  fn set_attributes(&self, value : i64)
  fn reparse_tag(&self) -> i64
  fn set_reparse_tag(&self, value : i64)
  fn ea_size(&self) -> i32
  fn set_ea_size(&self, value : i32)
  fn handle_info(&self) -> i64
  fn directory_context(&self) -> usize
  fn set_directory_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSEnumerateDirectoryEvent defines the signature of the CBFS EnumerateDirectory event's handler function.
pub trait CBFSEnumerateDirectoryEvent {
  fn on_enumerate_directory(&self, sender : CBFS, e : &mut CBFSEnumerateDirectoryEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_enumerate_directory(&self) -> &'a dyn CBFSEnumerateDirectoryEvent;
  pub fn set_on_enumerate_directory(&mut self, value : &'a dyn CBFSEnumerateDirectoryEvent);
  ...
}

Remarks

This event fires when the OS wants to enumerate the contents of the directory specified by DirectoryName (which will have been opened via on_open_file).

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must return information about each directory entry (e.g., file, subdirectory, link) that matches the specified Mask.

For each matching entry found, set FileFound to true, inspect the RequestedInfo parameter for the types of information required, and supply the entry's information using the following parameters:

  • FileName: Set to the name of the entry (not including its path).
  • ShortFileName: If the use_short_file_names property is enabled, set to the short (8.3) name of the entry.
    • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
  • CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the entry's corresponding time values, specified . Any time values not applicable to the entry can be left unchanged, or set to January 1, 1601 00:00:00 UTC.
  • Size: For file entries, set to the size of the file, in bytes; for other entries, set to 0. If a file is compressed or sparse, set this parameter to the "full" size of the file, i.e. the size which the file would have if it were not compressed or sparse.
  • AllocationSize: For file entries, set to the number of bytes allocated locally for the file; for other entries, set to 0. The allocation size is typically a multiple of the ClusterSize.
  • FileId: Set to the unique Id of the file or directory represented by the entry. Please refer to the File IDs topic for more information.
  • Attributes: Set to the file or directory attributes of the entry. If the support_compressed_attribute property is set to true, an event handler should properly set or clear the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter.
  • ReparseTag: If the use_reparse_points property is enabled, and the entry is a reparse point, set to the reparse point's tag.
    • Ensure that the FILE_ATTRIBUTE_REPARSE_POINT attribute is included in the value supplied for the Attributes parameter.
    • The tag should have been stored when the reparse point was created (i.e., during an earlier on_set_reparse_point event).
    • Please refer to the Reparse Points topic for more information.
  • EaSize: If the support_extended_attributes property is enabled, and the entry has associated extended attributes, set it to the combined length, in bytes, of the extended attributes for the file.

If there are no more matching entries present, set FileFound to false and leave the above parameters unchanged. When the OS is finished with the directory enumeration, the on_close_directory_enumeration event will fire.

RequestedInfo: This value specifies which kinds of information the struct is interested in. Use this information as a hint to save some CPU ticks. Providing unrequested information will not cause a problem, but this information will be ignored, thus wasting the time used to obtain it. The value is a combination of the following flags:

FILEINFO_EA_SIZE0x0400Ea size is requested.

FILEINFO_REAL_NAME0x0040File's actual name is requested.

In an on_enumerate_directory event handler, store the name of the file or directory in the FileName parameter. In a on_get_file_info event handler, store the name of the file or directory in the RealFileName parameter. Refer to the corresponding event's help topic for more details.

FILEINFO_SHORT_NAME0x0200Short name is requested.

FILEINFO_TIME0x0004File times are requested.

FILEINFO_SIZE0x0008File size is requested.

FILEINFO_ATTR0x0010File attributes are requested.

FILEINFO_FILEID0x0020File Id is requested.

This flag is used when use_file_ids is true.

FILEINFO_REPARSE_TAG0x0080File Reparse Tag is requested.

This flag is used when use_reparse_points is true. The reparse tag must be provided if file attributes indicate that the file or directory is a reparse point.

The Mask parameter specifies the file name mask that should be used to filter the results. This value may contain any combination of valid file name characters and wildcards (the * and ? characters). Alternatively, it may be an exact file name (i.e., a value without any wildcards), as some applications query file information by specifying an exact file name in an enumeration. Note: When a request for directory enumeration passes Windows network redirector, it always uses the mask * regardless of what the original mask was.

The CaseSensitive parameter indicates whether entry names should be matched against the specified Mask in a case-sensitive manner. It will always be false if the use_case_sensitive_file_names property is disabled.

Note: This parameter is not currently used; the search is always case-insensitive.

The Restart parameter, if true, indicates that the enumeration should be restarted from the beginning of the directory. Any previously reported entries that still exist should be reported again.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

Note: If an application calls the notify_directory_change method and passes a mask instead of a file name, the struct will fire this EnumerateDirectory event to collect the names of files and subdirectories, and in this case, the HandleInfo, DirectoryContext, and HandleContext parameters will be empty.

Note: To avoid unexpected delays and slowdown, enumeration does not refresh the metadata cache or nonexistent file cache. If your data may be altered on the backend side (i.e., not through the virtual disk), your application needs to track the changes and use notify_directory_change, as needed, which will update the mentioned caches. Alternatively, you may disable either or both of the caches.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

on_enumerate_hard_links Event (CBFS Struct)

This event fires when the OS needs to enumerate a file's hard links.

Syntax

// CBFSEnumerateHardLinksEventArgs carries the CBFS EnumerateHardLinks event's parameters.
pub struct CBFSEnumerateHardLinksEventArgs {
  fn file_name(&self) -> &String
  fn link_found(&self) -> bool
  fn set_link_found(&self, value : bool)
  fn link_name(&self) -> &String
  fn set_link_name(&self, value : String)
  fn set_link_name_ref(&self, value : &String)
  fn parent_id(&self) -> i64
  fn set_parent_id(&self, value : i64)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSEnumerateHardLinksEvent defines the signature of the CBFS EnumerateHardLinks event's handler function.
pub trait CBFSEnumerateHardLinksEvent {
  fn on_enumerate_hard_links(&self, sender : CBFS, e : &mut CBFSEnumerateHardLinksEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_enumerate_hard_links(&self) -> &'a dyn CBFSEnumerateHardLinksEvent;
  pub fn set_on_enumerate_hard_links(&mut self, value : &'a dyn CBFSEnumerateHardLinksEvent);
  ...
}

Remarks

This event fires when the OS needs to enumerate the hard links of the file specified by FileName (which will have been opened via on_open_file).

This event needs to be handled only if the use_hard_links property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must return information about each of the file's hard links.

Note: A file's "primary" name (i.e., the one contained in FileName) is itself one of the hard links that must be reported; please refer to the Hard Links topic for more information.

For each hard link, set LinkFound to true and supply the hard link's information using the following parameters:

  • LinkName: Set to the name of the hard link (not including its path).
  • ParentId: Set to the unique Id of the directory the hard link resides in (this Id should not change over time). Always use 0x7FFFFFFFFFFFFFFF if the hard link resides in the root directory (\).

If there are no more hard links present, set LinkFound to false and leave the above parameters unchanged. When the OS is finished with the hard links enumeration, the on_close_hard_links_enumeration event will fire.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_enumerate_named_streams Event (CBFS Struct)

This event fires when the OS needs to enumerate a file's named streams.

Syntax

// CBFSEnumerateNamedStreamsEventArgs carries the CBFS EnumerateNamedStreams event's parameters.
pub struct CBFSEnumerateNamedStreamsEventArgs {
  fn file_name(&self) -> &String
  fn named_stream_found(&self) -> bool
  fn set_named_stream_found(&self, value : bool)
  fn stream_name(&self) -> &String
  fn set_stream_name(&self, value : String)
  fn set_stream_name_ref(&self, value : &String)
  fn stream_size(&self) -> i64
  fn set_stream_size(&self, value : i64)
  fn stream_allocation_size(&self) -> i64
  fn set_stream_allocation_size(&self, value : i64)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSEnumerateNamedStreamsEvent defines the signature of the CBFS EnumerateNamedStreams event's handler function.
pub trait CBFSEnumerateNamedStreamsEvent {
  fn on_enumerate_named_streams(&self, sender : CBFS, e : &mut CBFSEnumerateNamedStreamsEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_enumerate_named_streams(&self) -> &'a dyn CBFSEnumerateNamedStreamsEvent;
  pub fn set_on_enumerate_named_streams(&mut self, value : &'a dyn CBFSEnumerateNamedStreamsEvent);
  ...
}

Remarks

This event fires when the OS needs to enumerate the named streams of the file specified by FileName (which will have been opened via on_open_file).

This event needs to be handled only if the use_alternate_data_streams property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must return information about each of the file's named streams. For each named stream, set StreamNameFound to true and supply the named stream's information using the following parameters:

  • StreamName: Set to the name of the named stream, prefixed with : (e.g. :MyStreamName). For more information about stream naming conventions, refer to Microsoft's Naming Conventions for Streams information.
  • StreamSize: Set the size, in bytes, of the named stream's data.
  • StreamAllocationSize: Set to the number of bytes allocated locally for the named stream. This is typically a multiple of the ClusterSize.

If there are no more named streams present, set StreamNameFound to false and leave the above parameters unchanged. When the OS is finished with the named streams enumeration, the on_close_named_streams_enumeration event will fire.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the file, specific handle, and enumeration, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_error Event (CBFS Struct)

This event fires if an unhandled error occurs during an event.

Syntax

// CBFSErrorEventArgs carries the CBFS Error event's parameters.
pub struct CBFSErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// CBFSErrorEvent defines the signature of the CBFS Error event's handler function.
pub trait CBFSErrorEvent {
  fn on_error(&self, sender : CBFS, e : &mut CBFSErrorEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_error(&self) -> &'a dyn CBFSErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn CBFSErrorEvent);
  ...
}

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

on_flush_file Event (CBFS Struct)

This event fires when the OS needs to flush an open file's data out to storage.

Syntax

// CBFSFlushFileEventArgs carries the CBFS FlushFile event's parameters.
pub struct CBFSFlushFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSFlushFileEvent defines the signature of the CBFS FlushFile event's handler function.
pub trait CBFSFlushFileEvent {
  fn on_flush_file(&self, sender : CBFS, e : &mut CBFSFlushFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_flush_file(&self) -> &'a dyn CBFSFlushFileEvent;
  pub fn set_on_flush_file(&mut self, value : &'a dyn CBFSFlushFileEvent);
  ...
}

Remarks

This event fires any time the OS needs the virtual filesystem to flush data out to storage. If the FileName parameter is nonempty, then all data related to the specified file (i.e., contents and all metadata) should be flushed. If FileName is empty, everything related to the virtual drive should be flushed.

To handle this event properly, applications must flush the requested data, writing it out to their backend storage.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information. (Not applicable if FileName is empty.)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_fsctl Event (CBFS Struct)

This event fires when the virtual filesystem receives a nonstandard request (filesystem control code).

Syntax

// CBFSFsctlEventArgs carries the CBFS Fsctl event's parameters.
pub struct CBFSFsctlEventArgs {
  fn file_name(&self) -> &String
  fn code(&self) -> i32
  fn input_buffer(&self) -> *mut u8
  fn input_buffer_length(&self) -> i32
  fn output_buffer(&self) -> *mut u8
  fn output_buffer_length(&self) -> i32
  fn bytes_returned(&self) -> i32
  fn set_bytes_returned(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSFsctlEvent defines the signature of the CBFS Fsctl event's handler function.
pub trait CBFSFsctlEvent {
  fn on_fsctl(&self, sender : CBFS, e : &mut CBFSFsctlEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_fsctl(&self) -> &'a dyn CBFSFsctlEvent;
  pub fn set_on_fsctl(&mut self, value : &'a dyn CBFSFsctlEvent);
  ...
}

Remarks

An FSCTL is a system call for filesystem-specific I/O operations as well as for other operations that cannot be expressed through regular filesystem calls. Such calls carry a control code, and the effects of the call depend entirely on how a filesystem handles that control code. A control code is composed of, among other things, a function code and flags that describe how data are passed.

CBFS Connect reserves function codes 2400-4096 for applications' use, and normally fires this event only for control codes containing a function code from that range. If, however, the handle_all_fsctls property is enabled, the struct will fire this event for all FSCTLs other than those processed by CBFS Connect itself.

This event is optional. Applications that choose to implement it are free to do so in any manner they desire based on the control code received.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

An application can send a custom FSCTL by defining a control code with the following macro and then using that control code to call the Windows API's DeviceIoControl function. #define CTL_CODE( DeviceType, Function, Method, Access ) \ ( ((DeviceType) << 16) | ((Access) << 14) | ((Function) << 2) | (Method) )

  • DeviceType: Must always be FILE_DEVICE_FILE_SYSTEM (9).
  • Function: Must be an integer in the range 2400-4096.
  • Method ("TransferType"): Specifies how data are passed between the caller and the driver. Possible values are as follows:
    • METHOD_BUFFERED (0)
    • METHOD_IN_DIRECT (1)
    • METHOD_OUT_DIRECT (2)
    • METHOD_NEITHER (3)
    For small amounts of data (1-4096 bytes), it is best to use METHOD_BUFFERED (0); otherwise, use METHOD_NEITHER (3) or one of the other values.
  • Access ("RequiredAccess"): Indicates the type(s) of access the caller must request when opening a handle to the target filesystem object (i.e., the handle passed for the hDevice parameter of the DeviceIoControl function). The system's I/O manager will block the request if the caller did not open the specified handle with the required access rights. Possible values are as follows:
    • FILE_ANY_ACCESS (0) (i.e., the caller can send the FSCTL regardless of access rights)
    • FILE_READ_ACCESS (1)
    • FILE_WRITE_ACCESS (2)
    The latter two options can be ORed together to require the caller to have both read and write access.

Please refer to Microsoft's Defining I/O Control Codes article for more information.

The FileName parameter identifies the file or directory targeted by the request. It may be empty if the request is targeting the virtual drive.

The Code parameter reflects the control code received. If the specified control code is unrecognized or unsupported (either in general, or for the filesystem object specified by FileName), return the ERROR_INVALID_FUNCTION error code via ResultCode.

The InputBuffer parameter points to the memory buffer containing the data required to perform the operation. The format of this data depends on the specified Code; it may be empty. The InputBufferLength parameter specifies the length, in bytes, of InputBuffer.

The OutputBuffer parameter points to the memory buffer that receives the data returned by the operation. The format of this data depends on the specified Code; it may be empty. The OutputBufferLength parameter specifies the capacity, in bytes, of OutputBuffer; applications should set the BytesReturned parameter to the number of bytes written to OutputBuffer.

If the application needs to return more than OutputBufferLength bytes of data, it should do one of the following:

  1. If OutputBuffer is too small to hold all of the data, but can hold some entries, then the application should write as much data to it as possible, set BytesReturned appropriately, and return the ERROR_MORE_DATA error code via ResultCode.
  2. If OutputBuffer is too small to hold any data, then the application should set BytesReturned to 0, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The FileContext parameter is a placeholder for application-defined data associated with the file. Please refer to the Contexts topic for more information.

Initially, the Result parameter will be set to ERROR_INVALID_FUNCTION. If an event handler processes the request in a meaningful way (i.e., the requestor will receive an expected result), the event handler should set Result to 0 or another error code that should reach the requestor. Please refer to the Error Handling topic for more information.

on_get_default_quota_info Event (CBFS Struct)

This event fires when the OS needs the virtual drive's default quota information.

Syntax

// CBFSGetDefaultQuotaInfoEventArgs carries the CBFS GetDefaultQuotaInfo event's parameters.
pub struct CBFSGetDefaultQuotaInfoEventArgs {
  fn default_quota_threshold(&self) -> i64
  fn set_default_quota_threshold(&self, value : i64)
  fn default_quota_limit(&self) -> i64
  fn set_default_quota_limit(&self, value : i64)
  fn file_system_control_flags(&self) -> i64
  fn set_file_system_control_flags(&self, value : i64)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetDefaultQuotaInfoEvent defines the signature of the CBFS GetDefaultQuotaInfo event's handler function.
pub trait CBFSGetDefaultQuotaInfoEvent {
  fn on_get_default_quota_info(&self, sender : CBFS, e : &mut CBFSGetDefaultQuotaInfoEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_default_quota_info(&self) -> &'a dyn CBFSGetDefaultQuotaInfoEvent;
  pub fn set_on_get_default_quota_info(&mut self, value : &'a dyn CBFSGetDefaultQuotaInfoEvent);
  ...
}

Remarks

This event fires when the OS needs the default quota information, set during an earlier on_set_default_quota_info event, for the virtual drive.

This event needs to be handled only if the use_disk_quotas property is enabled. To handle this event properly, applications must return the virtual drive's default quota information by setting DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Descriptions of the DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags parameters can be found in the Windows API's FILE_FS_CONTROL_INFORMATION structure documentation.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_file_info Event (CBFS Struct)

This event fires when the OS needs information about a file or directory.

Syntax

// CBFSGetFileInfoEventArgs carries the CBFS GetFileInfo event's parameters.
pub struct CBFSGetFileInfoEventArgs {
  fn file_name(&self) -> &String
  fn requested_info(&self) -> i32
  fn file_exists(&self) -> bool
  fn set_file_exists(&self, value : bool)
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn set_creation_time(&self, value : chrono::DateTime<Utc>)
  fn set_creation_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_access_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_access_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_write_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_write_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn set_change_time(&self, value : chrono::DateTime<Utc>)
  fn set_change_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn allocation_size(&self) -> i64
  fn set_allocation_size(&self, value : i64)
  fn file_id(&self) -> i64
  fn set_file_id(&self, value : i64)
  fn attributes(&self) -> i64
  fn set_attributes(&self, value : i64)
  fn reparse_tag(&self) -> i64
  fn set_reparse_tag(&self, value : i64)
  fn hard_link_count(&self) -> i32
  fn set_hard_link_count(&self, value : i32)
  fn short_file_name(&self) -> &String
  fn set_short_file_name(&self, value : String)
  fn set_short_file_name_ref(&self, value : &String)
  fn real_file_name(&self) -> &String
  fn set_real_file_name(&self, value : String)
  fn set_real_file_name_ref(&self, value : &String)
  fn ea_size(&self) -> i32
  fn set_ea_size(&self, value : i32)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetFileInfoEvent defines the signature of the CBFS GetFileInfo event's handler function.
pub trait CBFSGetFileInfoEvent {
  fn on_get_file_info(&self, sender : CBFS, e : &mut CBFSGetFileInfoEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_file_info(&self) -> &'a dyn CBFSGetFileInfoEvent;
  pub fn set_on_get_file_info(&mut self, value : &'a dyn CBFSGetFileInfoEvent);
  ...
}

Remarks

This event fires when the OS needs information about the file or directory specified by FileName and in some other cases (see the following notes for details).

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications should first check whether the specified file or directory exists, and set FileExists accordingly. If no such file or directory exists, set FileExists to false. If the file or directory exists, set FileExists to true, inspect the RequestedInfo parameter for the types of information required, and supply its information using the following parameters:

  • CreationTime, LastAccessTime, LastWriteTime, ChangeTime: Set to the corresponding time values of the file or directory, specified . Any nonapplicable time values can be left unchanged, or set to January 1, 1601 00:00:00 UTC.
  • Size: For file entries, set to the size of the file, in bytes; for other entries, set to 0. If a file is compressed or sparse, set this parameter to the "full" size of the file, i.e. the size which the file would have if it were not compressed or sparse.
  • AllocationSize: For files, set to the number of bytes allocated locally for the file; for directories, set to 0. The allocation size is typically a multiple of the ClusterSize.
  • FileId: Set to the unique Id of the file or directory. Please refer to the File IDs topic for more information.
  • Attributes: Set to the attributes of the file or directory. If the support_compressed_attribute property is set to true, an event handler should properly set or clear the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter.
  • ReparseTag: If the use_reparse_points property is enabled, and the entry is a reparse point, set to the reparse point's tag.
    • Ensure that the FILE_ATTRIBUTE_REPARSE_POINT attribute is included in the value supplied for the Attributes parameter.
    • The tag should have been stored when the reparse point was created (i.e., during an earlier on_set_reparse_point event).
    • Please refer to the Reparse Points topic for more information.
  • EaSize: If the support_extended_attributes property is enabled, and the entry has associated extended attributes, set it to the combined length, in bytes, of the extended attributes for the file.
  • HardLinkCount: If the use_hard_links property is enabled, set to the number of hard links that point to the file. The default value is 1 (which is also the only valid value for directories). Please refer to the Hard Links topic for more information.
  • ShortFileName: If the use_short_file_names property is enabled, set to the short (8.3) name of the file.
    • If use_short_file_names is enabled, it is possible that FileName is already a short name. In such cases, return the same name in ShortFileName.
    • The short name must adhere to the 8.3 name format; please refer to the Short File Names topic for more information.
  • RealFileName: If the use_case_sensitive_file_names property is enabled, and FileName's casing differs from that of the actual file or directory name, set to the real name of said file or directory.
    • For example, if the requested FileName is QWERTY.txt, but the only similarly named file in the virtual filesystem is qwErTy.TxT, then this parameter should be set to the latter.
    • If the specified FileName includes a path, it must be preserved in the value returned via RealFileName; only the casing of the file name and extension may be corrected.
    • The length of the returned name (and path, if applicable) must not exceed the value of the max_file_path_length property.

RequestedInfo: This value specifies which kinds of information the struct is interested in. Use this information as a hint to save some CPU ticks. Providing unrequested information will not cause a problem, but this information will be ignored, thus wasting the time used to obtain it. The value is a combination of the following flags:

FILEINFO_EA_SIZE0x0400Ea size is requested.

FILEINFO_REAL_NAME0x0040File's actual name is requested.

In an on_enumerate_directory event handler, store the name of the file or directory in the FileName parameter. In a on_get_file_info event handler, store the name of the file or directory in the RealFileName parameter. Refer to the corresponding event's help topic for more details.

FILEINFO_SHORT_NAME0x0200Short name is requested.

FILEINFO_TIME0x0004File times are requested.

FILEINFO_SIZE0x0008File size is requested.

FILEINFO_ATTR0x0010File attributes are requested.

FILEINFO_FILEID0x0020File Id is requested.

This flag is used when use_file_ids is true.

FILEINFO_REPARSE_TAG0x0080File Reparse Tag is requested.

This flag is used when use_reparse_points is true. The reparse tag must be provided if file attributes indicate that the file or directory is a reparse point.

Notes:

  1. if the use_case_sensitive_file_names and use_alternate_data_streams properties are both enabled, this event may also be used to obtain the real name of a named stream. When returning the name of a named stream via the RealFileName parameter, prepend a colon (:) to the stream's name so that it looks like this: :Zone.Identifier.
  2. if the UpdateFileMetadataOnOpen config setting is true, this event will fire right after the on_open_file event but only if the file was fully closed before on_open_file.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Note: For this event, returning ERROR_FILE_INVALID has no effect.

on_get_file_name_by_file_id Event (CBFS Struct)

This event fires when the struct needs to translate a file Id to a file or directory path.

Syntax

// CBFSGetFileNameByFileIdEventArgs carries the CBFS GetFileNameByFileId event's parameters.
pub struct CBFSGetFileNameByFileIdEventArgs {
  fn file_id(&self) -> i64
  fn file_path(&self) -> &String
  fn set_file_path(&self, value : String)
  fn set_file_path_ref(&self, value : &String)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetFileNameByFileIdEvent defines the signature of the CBFS GetFileNameByFileId event's handler function.
pub trait CBFSGetFileNameByFileIdEvent {
  fn on_get_file_name_by_file_id(&self, sender : CBFS, e : &mut CBFSGetFileNameByFileIdEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_file_name_by_file_id(&self) -> &'a dyn CBFSGetFileNameByFileIdEvent;
  pub fn set_on_get_file_name_by_file_id(&mut self, value : &'a dyn CBFSGetFileNameByFileIdEvent);
  ...
}

Remarks

This event fires any time the struct needs a specified FileId translated to a file or directory path. This typically occurs when a process tries to open a file or directory by Id rather than by name (e.g., if FILE_OPEN_BY_FILE_ID is used when calling the Windows API's ZwCreateFile function); the on_open_file event fires after the path is obtained from this event.

This event must be handled if one of the use_disk_quotas or use_hard_links properties is enabled; otherwise, it is optional, and applications need not implement it if the virtual filesystem doesn't support file Ids.

Note: NFS sharing makes use of file IDs.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must set FilePath to the absolute path of the file or directory associated with the specified FileId. The length of the path must not exceed the value of the max_file_path_length property.

The root directory (\) always uses the predefined Id 0x7FFFFFFFFFFFFFFF.

Please refer to the File IDs topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_file_security Event (CBFS Struct)

This event fires when the OS needs to read the Windows security attributes of a file or directory.

Syntax

// CBFSGetFileSecurityEventArgs carries the CBFS GetFileSecurity event's parameters.
pub struct CBFSGetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn descriptor_length(&self) -> i32
  fn set_descriptor_length(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetFileSecurityEvent defines the signature of the CBFS GetFileSecurity event's handler function.
pub trait CBFSGetFileSecurityEvent {
  fn on_get_file_security(&self, sender : CBFS, e : &mut CBFSGetFileSecurityEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_file_security(&self) -> &'a dyn CBFSGetFileSecurityEvent;
  pub fn set_on_get_file_security(&mut self, value : &'a dyn CBFSGetFileSecurityEvent);
  ...
}

Remarks

This event fires when the OS needs to read the Windows security attributes of the file or directory specified by FileName.

This event only needs to be handled if the use_windows_security property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must return the requested pieces of security information, specified by SecurityInformation, via the SecurityDescriptor buffer. Please refer to the following parameter descriptions, as well as the Security Checks topic, for more information.

The SecurityInformation parameter indicates which pieces of security information must be provided. This value is a bitfield; possible flags include (but are not limited to) the following:

  • OWNER_SECURITY_INFORMATION
  • GROUP_SECURITY_INFORMATION
  • DACL_SECURITY_INFORMATION
  • SACL_SECURITY_INFORMATION
Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to the memory buffer that receives the requested data. It is available only if BufferLength is greater than 0. The data must be formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to these articles for more information about self-relative security descriptors.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BufferLength parameter specifies the capacity, in bytes, of the SecurityDescriptor buffer; and the DescriptorLength parameter specifies, in bytes, the length of the security descriptor.

If the SecurityDescriptor buffer has enough capacity to accommodate the entire security descriptor, DescriptorLength must be set to the length of the data copied to SecurityDescriptor. If the SecurityDescriptor buffer is too small (or, in cases in which BufferLength is 0, unavailable), do not write any data to it; instead, set DescriptorLength to the number of bytes required to hold the requested data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_object_id Event (CBFS Struct)

This event fires when the OS needs the object Id and extended information of a volume or a filesystem entry.

Syntax

// CBFSGetObjectIdEventArgs carries the CBFS GetObjectId event's parameters.
pub struct CBFSGetObjectIdEventArgs {
  fn file_name(&self) -> &String
  fn should_create(&self) -> bool
  fn object_id(&self) -> *mut u8
  fn object_id_length(&self) -> i32
  fn extended_information(&self) -> *mut u8
  fn extended_information_length(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetObjectIdEvent defines the signature of the CBFS GetObjectId event's handler function.
pub trait CBFSGetObjectIdEvent {
  fn on_get_object_id(&self, sender : CBFS, e : &mut CBFSGetObjectIdEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_object_id(&self) -> &'a dyn CBFSGetObjectIdEvent;
  pub fn set_on_get_object_id(&mut self, value : &'a dyn CBFSGetObjectIdEvent);
  ...
}

Remarks

This event fires any time the OS needs to retrieve the object Id and extended information for the virtual drive volume or one of its files or directories. If the object ID is requested for a file or directory, this entry is identified with the FileName parameter. If the request is made for the volume, FileName will be empty.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must populate the ObjectId and ExtendedInformation buffers with the most recent values obtained via on_set_object_id. The ObjectIdLength and ExtendedInformationLength values are defined by the OS; currently, they are 16 and 48 bytes, respectively. ObjectId and ExtendedInformation are are the two parts of the FILE_OBJECT_BUFFER structure, split for convenience.

ShouldCreate

ShouldCreate specifies whether the handler must create a new Id if there is no Id associated with the volume or the filesystem entry. If the value of this parameter is false and no Id exists, an error should be returned.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_reparse_point Event (CBFS Struct)

This event fires when the OS wants to read a reparse point for a file or directory.

Syntax

// CBFSGetReparsePointEventArgs carries the CBFS GetReparsePoint event's parameters.
pub struct CBFSGetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn reparse_buffer_length(&self) -> i32
  fn set_reparse_buffer_length(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetReparsePointEvent defines the signature of the CBFS GetReparsePoint event's handler function.
pub trait CBFSGetReparsePointEvent {
  fn on_get_reparse_point(&self, sender : CBFS, e : &mut CBFSGetReparsePointEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_reparse_point(&self) -> &'a dyn CBFSGetReparsePointEvent;
  pub fn set_on_get_reparse_point(&mut self, value : &'a dyn CBFSGetReparsePointEvent);
  ...
}

Remarks

This event fires when the OS wants to read a reparse point for the file or directory specified by FileName.

This event only needs to be handled if the use_reparse_points property is enabled.

Note: NFS sharing makes use of reparse points.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must populate ReparseBuffer with the reparse point data associated with the specified file or directory (i.e., the data stored during an earlier on_set_reparse_point event), and set ReparseBufferLength to the number of bytes written.

Please refer to the Reparse Points topic for more information.

The ReparseBufferLength parameter's initial value reflects the capacity of the memory buffer pointed to by ReparseBuffer. If the buffer is too small to hold all of the reparse point data, then the application should write as much data to it as possible, set ReparseBufferLength appropriately, and return the ERROR_MORE_DATA error code via ResultCode.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The HandleInfo, FileContext, and HandleContext parameters will be absent if it is not open, in which case, they will be .

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_volume_id Event (CBFS Struct)

This event fires when the struct needs the volume Id.

Syntax

// CBFSGetVolumeIdEventArgs carries the CBFS GetVolumeId event's parameters.
pub struct CBFSGetVolumeIdEventArgs {
  fn volume_id(&self) -> i32
  fn set_volume_id(&self, value : i32)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetVolumeIdEvent defines the signature of the CBFS GetVolumeId event's handler function.
pub trait CBFSGetVolumeIdEvent {
  fn on_get_volume_id(&self, sender : CBFS, e : &mut CBFSGetVolumeIdEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_volume_id(&self) -> &'a dyn CBFSGetVolumeIdEvent;
  pub fn set_on_get_volume_id(&mut self, value : &'a dyn CBFSGetVolumeIdEvent);
  ...
}

Remarks

This event fires any time the struct needs to retrieve the volume Id of the virtual drive. Ideally, each drive's volume Id should be globally unique.

To handle this event properly, applications must return the virtual drive's volume Id via the VolumeId parameter.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_volume_label Event (CBFS Struct)

This event fires when the OS needs the volume label.

Syntax

// CBFSGetVolumeLabelEventArgs carries the CBFS GetVolumeLabel event's parameters.
pub struct CBFSGetVolumeLabelEventArgs {
  fn buffer(&self) -> &String
  fn set_buffer(&self, value : String)
  fn set_buffer_ref(&self, value : &String)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetVolumeLabelEvent defines the signature of the CBFS GetVolumeLabel event's handler function.
pub trait CBFSGetVolumeLabelEvent {
  fn on_get_volume_label(&self, sender : CBFS, e : &mut CBFSGetVolumeLabelEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_volume_label(&self) -> &'a dyn CBFSGetVolumeLabelEvent;
  pub fn set_on_get_volume_label(&mut self, value : &'a dyn CBFSGetVolumeLabelEvent);
  ...
}

Remarks

This event fires any time the OS needs to retrieve the volume label of the virtual drive.

To handle this event properly, applications must set Buffer to the most recent value obtained via on_set_volume_label.

The length of the returned volume label must not exceed 32 characters, which is the maximum length supported by the OS.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_get_volume_size Event (CBFS Struct)

This event fires when the OS needs information about the virtual drive's capacity and free space.

Syntax

// CBFSGetVolumeSizeEventArgs carries the CBFS GetVolumeSize event's parameters.
pub struct CBFSGetVolumeSizeEventArgs {
  fn total_sectors(&self) -> i64
  fn set_total_sectors(&self, value : i64)
  fn available_sectors(&self) -> i64
  fn set_available_sectors(&self, value : i64)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSGetVolumeSizeEvent defines the signature of the CBFS GetVolumeSize event's handler function.
pub trait CBFSGetVolumeSizeEvent {
  fn on_get_volume_size(&self, sender : CBFS, e : &mut CBFSGetVolumeSizeEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_get_volume_size(&self) -> &'a dyn CBFSGetVolumeSizeEvent;
  pub fn set_on_get_volume_size(&mut self, value : &'a dyn CBFSGetVolumeSizeEvent);
  ...
}

Remarks

This event fires any time the OS needs to retrieve the virtual drive's total storage capacity and free space, measured in sectors. The virtual drive's sector size is defined by the SectorSize configuration setting.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must set TotalSectors to the total number of sectors on the drive, and set AvailableSectors to the number of sectors that are available to the OS for storing filesystem objects.

The minimum drive size accepted by Windows is 6144 bytes (based on a 3072-byte sector, 1 sector per cluster and 2 clusters per drive). The struct adjusts the minimum size to be at least 16 sectors (49152 bytes) to ensure compatibility with possible changes in future Windows updates.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_ioctl Event (CBFS Struct)

This event fires when the disk behind the virtual filesystem receives a nonstandard request (I/O control code).

Syntax

// CBFSIoctlEventArgs carries the CBFS Ioctl event's parameters.
pub struct CBFSIoctlEventArgs {
  fn file_name(&self) -> &String
  fn code(&self) -> i32
  fn input_buffer(&self) -> *mut u8
  fn input_buffer_length(&self) -> i32
  fn output_buffer(&self) -> *mut u8
  fn output_buffer_length(&self) -> i32
  fn bytes_returned(&self) -> i32
  fn set_bytes_returned(&self, value : i32)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSIoctlEvent defines the signature of the CBFS Ioctl event's handler function.
pub trait CBFSIoctlEvent {
  fn on_ioctl(&self, sender : CBFS, e : &mut CBFSIoctlEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_ioctl(&self) -> &'a dyn CBFSIoctlEvent;
  pub fn set_on_ioctl(&mut self, value : &'a dyn CBFSIoctlEvent);
  ...
}

Remarks

An IOCTL is a system call for device-specific I/O operations, as well as other operations that cannot be expressed through regular API calls. Such calls carry a control code, and the effects of the call depend entirely on how a device driver handles that control code. A control code is composed of, among other things, a function code and flags that describe how data are passed.

This event is optional. Applications that choose to implement it are free to do so in any manner they desire based on the control code received.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The FileName parameter identifies the file or directory targeted by the request. It may be empty if the request is targeting the virtual drive.

The Code parameter reflects the control code received. If the specified control code is unrecognized or unsupported, return the ERROR_INVALID_FUNCTION error code via ResultCode.

The InputBuffer parameter points to the memory buffer containing the data required to perform the operation. The format of this data depends on the specified Code; it may be empty. The InputBufferLength parameter specifies the length, in bytes, of InputBuffer.

The OutputBuffer parameter points to the memory buffer that receives the data returned by the operation. The format of this data depends on the specified Code; it may be empty. The OutputBufferLength parameter specifies the capacity, in bytes, of OutputBuffer; applications should set the BytesReturned parameter to the number of bytes written to OutputBuffer.

If the application needs to return more than OutputBufferLength bytes of data, it should do one of the following:

  1. If OutputBuffer is too small to hold all of the data, but can hold some entries, then the application should write as much data to it as possible, set BytesReturned appropriately, and return the ERROR_MORE_DATA error code via ResultCode.
  2. If OutputBuffer is too small to hold any data, then the application should set BytesReturned to 0, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Initially, the Result parameter will be set to ERROR_INVALID_FUNCTION. If an event handler processes the request in a meaningful way (i.e., the requestor will receive an expected result), the event handler should set Result to 0 or another error code that should reach the requestor. Please refer to the Error Handling topic for more information.

on_is_directory_empty Event (CBFS Struct)

This event fires when the OS needs to know whether a directory is empty.

Syntax

// CBFSIsDirectoryEmptyEventArgs carries the CBFS IsDirectoryEmpty event's parameters.
pub struct CBFSIsDirectoryEmptyEventArgs {
  fn directory_name(&self) -> &String
  fn is_empty(&self) -> bool
  fn set_is_empty(&self, value : bool)
  fn directory_context(&self) -> usize
  fn set_directory_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSIsDirectoryEmptyEvent defines the signature of the CBFS IsDirectoryEmpty event's handler function.
pub trait CBFSIsDirectoryEmptyEvent {
  fn on_is_directory_empty(&self, sender : CBFS, e : &mut CBFSIsDirectoryEmptyEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_is_directory_empty(&self) -> &'a dyn CBFSIsDirectoryEmptyEvent;
  pub fn set_on_is_directory_empty(&mut self, value : &'a dyn CBFSIsDirectoryEmptyEvent);
  ...
}

Remarks

This event fires when the OS needs to know whether the directory specified by DirectoryName is empty.

This event needs to be handled only if the use_directory_empty_check property is enabled. To handle this event properly, applications must set the IsEmpty parameter appropriately.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The DirectoryContext parameter is a placeholder for application-defined data associated with the directory (for "general-purpose" events, it is called FileContext instead). Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_lock_file Event (CBFS Struct)

This event fires when the OS needs to lock a range of bytes in a file.

Syntax

// CBFSLockFileEventArgs carries the CBFS LockFile event's parameters.
pub struct CBFSLockFileEventArgs {
  fn file_name(&self) -> &String
  fn byte_offset(&self) -> i64
  fn length(&self) -> i64
  fn key(&self) -> i32
  fn exclusive_lock(&self) -> bool
  fn fail_immediately(&self) -> bool
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSLockFileEvent defines the signature of the CBFS LockFile event's handler function.
pub trait CBFSLockFileEvent {
  fn on_lock_file(&self, sender : CBFS, e : &mut CBFSLockFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_lock_file(&self) -> &'a dyn CBFSLockFileEvent;
  pub fn set_on_lock_file(&mut self, value : &'a dyn CBFSLockFileEvent);
  ...
}

Remarks

This event fires when the OS needs to lock a range of bytes in the file specified by FileName. Typically, such requests originate from the Windows API's LockFile and LockFileEx functions.

This event is optional. The CBFS struct automatically manages file locks in the virtual filesystem. If the resources an application uses for backend storage (e.g., files, memory, a database) are never directly accessed by anything other than the application itself, then there is no reason to implement this event.

If, however, an application's backend storage involves shared resources (i.e., those that could be accessed by something other than the application at any time), this event should be used to perform any actions needed to propagate the requested lock onto those resources.

For example, if an application's backend storage implementation involves files stored on a network server, then the locking request should be communicated to that server so that it can prevent other accessors from using the locked data.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Applications that implement this event must also implement the on_unlock_file event.

The ByteOffset and Length parameters specify the starting position of the range being locked, and the length of that range, respectively.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The ExclusiveLock and FailImmediately parameters are described in-depth in the LockFileEx function's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

An event handler may return ERROR_RETRY to signal that locking cannot be done immediately but a retry is required a bit later. The time until the next attempt is set via the LockRetryInterval setting. This behavior requires that the UserModeLockFirst setting is enabled.

on_mount Event (CBFS Struct)

This event fires after the struct mounts media into the virtual drive, making it available.

Syntax

// CBFSMountEventArgs carries the CBFS Mount event's parameters.
pub struct CBFSMountEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSMountEvent defines the signature of the CBFS Mount event's handler function.
pub trait CBFSMountEvent {
  fn on_mount(&self, sender : CBFS, e : &mut CBFSMountEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_mount(&self) -> &'a dyn CBFSMountEvent;
  pub fn set_on_mount(&mut self, value : &'a dyn CBFSMountEvent);
  ...
}

Remarks

This event fires once the struct has mounted media into the virtual drive, making it available. Please refer to mount_media for more information.

This event is optional; it is provided to give applications a chance to perform additional processing when the virtual filesystem is made available.

Do not call any GetOriginator* methods from the event handler - doing this will cause a deadlock.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_offload_read_file Event (CBFS Struct)

This event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) read operation.

Syntax

// CBFSOffloadReadFileEventArgs carries the CBFS OffloadReadFile event's parameters.
pub struct CBFSOffloadReadFileEventArgs {
  fn file_name(&self) -> &String
  fn token_time_to_live(&self) -> i32
  fn position(&self) -> i64
  fn copy_length(&self) -> i64
  fn transfer_length(&self) -> i64
  fn set_transfer_length(&self, value : i64)
  fn token_type(&self) -> i32
  fn set_token_type(&self, value : i32)
  fn token_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i64
  fn token_length(&self) -> i32
  fn set_token_length(&self, value : i32)
  fn result_flags(&self) -> i32
  fn set_result_flags(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSOffloadReadFileEvent defines the signature of the CBFS OffloadReadFile event's handler function.
pub trait CBFSOffloadReadFileEvent {
  fn on_offload_read_file(&self, sender : CBFS, e : &mut CBFSOffloadReadFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_offload_read_file(&self) -> &'a dyn CBFSOffloadReadFileEvent;
  pub fn set_on_offload_read_file(&mut self, value : &'a dyn CBFSOffloadReadFileEvent);
  ...
}

Remarks

This events fires when the OS wants the virtual filesystem to perform an offloaded read for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should first verify whether the specified file supports offload operations, returning the ERROR_OFFLOAD_READ_FILE_NOT_SUPPORTED error code via ResultCode if not. Assuming the file does support offload operations, the application should perform any actions needed to prepare for the offloaded read based on the specified parameters, and then return the requested information. Please refer to the following parameter descriptions for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The TokenTimeToLive parameter indicates the duration, in milliseconds, that the offloaded read operation remains valid. Multiple writes can be performed with the token returned in TokenBuffer until this time expires.

The Position and CopyLength parameters specify the byte offset and length (respectively) of a data chunk in the specified file that should be read, or in some other way prepared, for transferring.

The TransferLength parameter must be set to the number of bytes actually read/prepared as a result of this request. It may be less than CopyLength.

The TokenType parameter must be set to either (1) the Microsoft-defined value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) if the token represents data that are all zeros, or (2) an application-defined value outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF to denote an application-defined token format.

Note: Use of the STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA token type is not required.

The TokenBuffer parameter points to a memory buffer that receives some application-defined token that identifies the data that have been read or prepared for transfer. The returned token will be passed to an offloaded write operation to actually transfer the data it represents. The BufferLength parameter specifies the capacity, in bytes, of TokenBuffer; applications must set the TokenLength parameter to the number of bytes written to TokenBuffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_READ_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_offload_write_file Event (CBFS Struct)

This event fires when the OS wants the virtual filesystem to perform an offloaded data transfer (ODX) write operation.

Syntax

// CBFSOffloadWriteFileEventArgs carries the CBFS OffloadWriteFile event's parameters.
pub struct CBFSOffloadWriteFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn copy_length(&self) -> i64
  fn transfer_offset(&self) -> i64
  fn transfer_length(&self) -> i64
  fn set_transfer_length(&self, value : i64)
  fn token_type(&self) -> i32
  fn token(&self) -> *mut u8
  fn token_length(&self) -> i64
  fn result_flags(&self) -> i32
  fn set_result_flags(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSOffloadWriteFileEvent defines the signature of the CBFS OffloadWriteFile event's handler function.
pub trait CBFSOffloadWriteFileEvent {
  fn on_offload_write_file(&self, sender : CBFS, e : &mut CBFSOffloadWriteFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_offload_write_file(&self) -> &'a dyn CBFSOffloadWriteFileEvent;
  pub fn set_on_offload_write_file(&mut self, value : &'a dyn CBFSOffloadWriteFileEvent);
  ...
}

Remarks

This event fires when the OS wants the virtual filesystem to perform an offloaded write for the file specified by FileName as part of an offloaded data transfer.

To handle this event properly, applications should perform any actions needed to handle the offloaded write based on the specified parameters, and then return the result information. Please refer to the following parameter descriptions for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The Position and CopyLength parameters specify the byte offset and length, respectively, of the data chunk that should be written in the specified file. The CopyLength parameter's value may be smaller than the total amount of data represented by the token (in which case TransferOffset may be greater than 0).

The TransferOffset parameters specifies the byte offset, in the chunk of data represented by the token, from which to begin writing.

The TransferLength parameter must be set to the number of bytes actually written as a result of this request. It may be less than CopyLength.

The TokenType parameter indicates the type of token stored in the Token buffer. A value of STORAGE_OFFLOAD_TOKEN_TYPE_ZERO_DATA (0xFFFF0001) indicates that the token represents data that are all zeros. Any other value (outside of the reserved range 0xFFFF0002 to 0xFFFFFFFF) indicates an application-defined token format.

The Token parameter points to a memory buffer that contains the token returned in response to an earlier offloaded read request. The token identifies the chunk of data that has been read or prepared for transfer; refer to the on_offload_read_file event for more information. The TokenLength parameter specifies the length, in bytes, of the data in Token.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultFlags parameter must be set to a combination of zero or more of the flags described in the FSCTL_OFFLOAD_WRITE_OUTPUT structure's documentation.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_open_file Event (CBFS Struct)

This event fires when the OS wants to open a file or directory.

Syntax

// CBFSOpenFileEventArgs carries the CBFS OpenFile event's parameters.
pub struct CBFSOpenFileEventArgs {
  fn file_name(&self) -> &String
  fn desired_access(&self) -> i32
  fn attributes(&self) -> i32
  fn share_mode(&self) -> i32
  fn nt_create_disposition(&self) -> i32
  fn nt_desired_access(&self) -> i32
  fn file_info(&self) -> i64
  fn handle_info(&self) -> i64
  fn reserved(&self) -> bool
  fn set_reserved(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSOpenFileEvent defines the signature of the CBFS OpenFile event's handler function.
pub trait CBFSOpenFileEvent {
  fn on_open_file(&self, sender : CBFS, e : &mut CBFSOpenFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_open_file(&self) -> &'a dyn CBFSOpenFileEvent;
  pub fn set_on_open_file(&mut self, value : &'a dyn CBFSOpenFileEvent);
  ...
}

Remarks

This event fires when the OS wants to open the existing file or directory specified by FileName using the open options reflected in Attributes. If the fire_all_open_close_events property is disabled, this event will fire only when the first handle to the specified file or directory is opened. To determine whether the request is for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY;

If the use_alternate_data_streams property is enabled, this event also fires anytime the OS wants to open a named data stream in a file. Such requests are distinguished by the presence of a colon (:) in the FileName value; the text before the colon is the name of the file itself, and the text after the colon is the name of the stream to open.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications should perform any actions needed to open the requested file, directory, or named stream in their backend storage. Applications are also responsible for validating the access rights of the process that initiated the request before performing the requested operation; please refer to the Security Checks topic for more information.

If there is an existing local file that corresponds to the virtual one specified by FileName, the application may call route_to_file to have the struct route future requests directly to that file. This event's FileInfo value must be passed to route_to_file for request routing to be configured successfully.

In certain cases, this event may fire for a file or directory that no longer exists. Normally this will not happen, as the OS already knows which files exist (based on information obtained via on_get_file_info/on_enumerate_directory) before it sends the open request. If, however, a file or directory is deleted externally, a race condition may occur where said deletion is not detected by the OS or virtual filesystem before the open request arrives. In such cases, applications must return the ERROR_FILE_NOT_FOUND error code via ResultCode.

The DesiredAccess parameter specifies the access mode desired by the process that initiated the request; it may contain one or more of the following access flags:

DESIRED_ACCESS_FILE_LIST_DIRECTORY0x00000001For a directory, the right to list the contents of the directory.

DESIRED_ACCESS_FILE_READ_DATA0x00000001For a file object, the right to read the corresponding file data.

For a directory object, the right to read the corresponding directory data.

DESIRED_ACCESS_FILE_ADD_FILE0x00000002For a directory, the right to create a file in the directory.

DESIRED_ACCESS_FILE_WRITE_DATA0x00000002For a file object, the right to write data to the file.

For a directory object, the right to create a file in the directory

DESIRED_ACCESS_FILE_ADD_SUBDIRECTORY0x00000004For a directory, the right to create a subdirectory.

DESIRED_ACCESS_FILE_APPEND_DATA0x00000004For a file object, the right to append data to the file.

(For local files, write operations will not overwrite existing data if this flag is specified without FILE_WRITE_DATA.) For a directory object, the right to create a subdirectory (FILE_ADD_SUBDIRECTORY).

DESIRED_ACCESS_FILE_READ_EA0x00000008The right to read extended file attributes.

DESIRED_ACCESS_FILE_WRITE_EA0x00000010The right to write extended file attributes.

DESIRED_ACCESS_FILE_EXECUTE0x00000020For a native code file, the right to execute the file.

This access right given to scripts may cause the script to be executable, depending on the script interpreter.

DESIRED_ACCESS_FILE_DELETE_CHILD0x00000040For a directory, the right to delete a directory and all the files it contains, including read-only files.

DESIRED_ACCESS_FILE_READ_ATTRIBUTES0x00000080The right to read file attributes.

DESIRED_ACCESS_FILE_WRITE_ATTRIBUTES0x00000100The right to write file attributes.

DESIRED_ACCESS_READ_CONTROL0x00020000The right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_READ0x00020000Includes READ_CONTROL, which is the right to read the information in the file or directory object's security descriptor.

This does not include the information in the SACL.

DESIRED_ACCESS_STANDARD_RIGHTS_WRITE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_STANDARD_RIGHTS_EXECUTE0x00020000Same as STANDARD_RIGHTS_READ

DESIRED_ACCESS_SYNCHRONIZE0x00100000The right to use the object for synchronization.

This enables a thread to wait until the object is in the signaled state. Some object types do not support this access right.

DESIRED_ACCESS_FILE_ALL_ACCESS0x001F01FFAll possible access rights for a file.

DESIRED_ACCESS_FILE_GENERIC_READ0x00120089A combinarion of flags that allow reading of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_WRITE0x00120116A combinarion of flags that allow modifications to the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

DESIRED_ACCESS_FILE_GENERIC_EXECUTE0x001200A0A combinarion of flags that allow execution of the file.

Note: Don't match received values against this flag. Instead, use flags that specify the rights that you want to verify or add/remove.

This value may differ from the one originally passed to the OS; the struct alters it in the following cases:

  • The DELETE flag is added if the requested CreateDisposition is FILE_SUPERSEDE.
  • The FILE_WRITE_DATA, FILE_WRITE_EA, and FILE_WRITE_ATTRIBUTES flags are added if the requested CreateDisposition is FILE_OVERWRITE or FILE_OVERWRITE_IF.
The original CreateDisposition and DesiredAccess values are exposed through the NTCreateDisposition and NTDesiredAccess parameters.

Note: These values are in NT format; that is, as expected by the Windows API's ZwCreateFile function.

The Attributes parameter contains file attributes; it may contain one or more of the following attributes:

FILE_SYS_ATTR_READ_ONLY0x00000001The file is read-only.

Applications can read the file, but cannot write to it or delete it. This attribute is not honored on directories.

FILE_SYS_ATTR_HIDDEN0x00000002The file or directory is hidden.

The file is not included in an ordinary directory listing.

FILE_SYS_ATTR_SYSTEM0x00000004A file or directory that the operating system uses a part of, or uses exclusively.

FILE_SYS_ATTR_DIRECTORY0x00000010The entry is a directory.

FILE_SYS_ATTR_ARCHIVE0x00000020The entry is an archive file or directory.

Applications typically use this attribute to mark files for backup or removal.

FILE_SYS_ATTR_NORMAL0x00000080A file doesn't have other attributes set.

This attribute is valid only when used alone.

FILE_SYS_ATTR_TEMPORARY0x00000100A file that is being used for temporary storage.

File systems avoid writing data back to mass storage if sufficient cache memory is available, because typically, an application deletes a temporary file after the handle is closed. In that scenario, the system can entirely avoid writing the data. Otherwise, the data are written after the handle is closed.

FILE_SYS_ATTR_SPARSE_FILE0x00000200A file that is a sparse file.

FILE_SYS_ATTR_REPARSE_POINT0x00000400A file that is a reparse point or a symbolic link.

FILE_SYS_ATTR_COMPRESSED0x00000800A file or directory that is compressed.

For a file, all of the data in the file are compressed. For a directory, compression is the default for newly created files and subdirectories. A filesystem implementation can make use of this attribute by setting the support_compressed_attribute property to true and then properly handling the on_get_file_info, on_enumerate_directory, and on_set_file_attributes events.

FILE_SYS_ATTR_OFFLINE0x00001000The data of a file are not available immediately.

This attribute indicates that the file data are physically moved to offline storage.

FILE_SYS_ATTR_NOT_CONTENT_INDEXED0x00002000The file or directory is not to be indexed by the content indexing service.

FILE_SYS_ATTR_ENCRYPTED0x00004000A file or directory that is encrypted.

For a file, all data streams in the file are encrypted. For a directory, encryption is the default for newly created files and subdirectories.

Note: This flag is used by NTFS and the OS sends undocumented requests to the filesystem based on this flag. The flag should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_VIRTUAL0x00010000Reserved.

Note: This flag is reserved by the OS and should not be used for files in custom filesystem implementations.

FILE_SYS_ATTR_RECALL_ON_OPEN0x00040000The file or directory has no physical representation on the local system; the item is virtual.

Opening the item will be more expensive than normal (e.g., it will cause at least some of it to be fetched from a remote store). This flag is reported by filesystems during directory enumerations.

Attributes specifies both the attributes and create/open options for the new file. Some options, such as FILE_FLAG_SEQUENTIAL_SCAN, FILE_FLAG_WRITE_THROUGH, and FILE_FLAG_RANDOM_ACCESS, may be useful for applications that wish to fine-tune their performance. For example, such information could be used to decide whether it is necessary to locally cache some amount of data that is stored remotely.

The ShareMode parameter specifies the access sharing mode desired by the process that initiated the request; it may contain zero or more of the following share mode flags:

FILE_SYS_SHARE_READ0x00000001Enables subsequent open operations on a file to request read access.

Otherwise, other processes cannot open the file if they request read access. If this flag is not specified, but the file has been opened for read access, file creation or opening fails.

FILE_SYS_SHARE_WRITE0x00000002Enables subsequent open operations on a file to request write access.

Otherwise, other processes cannot open the file if they request write access. If this flag is not specified, but the file has been opened for write access or has a file mapping with write access, file creation or opening fails.

FILE_SYS_SHARE_DELETE0x00000004Enables subsequent open operations on a file to request delete access.

Otherwise, other processes cannot open the file if they request delete access. If this flag is not specified, but the file has been opened for delete access, the function fails.

Note: Delete access allows both delete and rename operations.

Please refer to the Windows API's ZwCreateFile function for detailed information about possible values for the DesiredAccess, Attributes, ShareMode, NTCreateDisposition, and NTDesiredAccess parameters.

The FileInfo parameter carries a handle to an object with information about the file. As mentioned earlier, this value should be used if the application chooses to call the route_to_file method.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_query_allocated_ranges Event (CBFS Struct)

This event fires when the OS needs to query valid ranges within a file.

Syntax

// CBFSQueryAllocatedRangesEventArgs carries the CBFS QueryAllocatedRanges event's parameters.
pub struct CBFSQueryAllocatedRangesEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn length(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn length_returned(&self) -> i32
  fn set_length_returned(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSQueryAllocatedRangesEvent defines the signature of the CBFS QueryAllocatedRanges event's handler function.
pub trait CBFSQueryAllocatedRangesEvent {
  fn on_query_allocated_ranges(&self, sender : CBFS, e : &mut CBFSQueryAllocatedRangesEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_query_allocated_ranges(&self) -> &'a dyn CBFSQueryAllocatedRangesEvent;
  pub fn set_on_query_allocated_ranges(&mut self, value : &'a dyn CBFSQueryAllocatedRangesEvent);
  ...
}

Remarks

This event fires when the OS needs to query valid data ranges of a sparse file specified by FileName. Only those ranges must be reported that are located within the overall range [Position-Position + Length].

To handle the event, an application must put the list of range information into a buffer specified by Buffer, then set LengthReturned to the size of the actually written data, in bytes. The size of the information placed into Buffer may not exceed BufferLength bytes and must be a multiple of 16 bytes (each record in the list is 16 bytes as described below).

The list to be stored in Buffer is a sequence of elements, each being a pair of unsigned 64-bit values that contain the starting position and the length of each reported range: {Range1Position}{Range1Length}{Range2Position}{Range2Length}...{RangeNPosition}{RangeNLength}. The number of entries is determined by a caller from the value of LengthReturned that the application must set as described above.

For compressed files that are not sparse, the application must return one range with its position set to 0 and length set to the length of original (uncompressed) data.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_query_compression_info Event (CBFS Struct)

This event fires when the OS needs to query the information about a compressed file.

Syntax

// CBFSQueryCompressionInfoEventArgs carries the CBFS QueryCompressionInfo event's parameters.
pub struct CBFSQueryCompressionInfoEventArgs {
  fn file_name(&self) -> &String
  fn compressed_file_size(&self) -> i64
  fn set_compressed_file_size(&self, value : i64)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSQueryCompressionInfoEvent defines the signature of the CBFS QueryCompressionInfo event's handler function.
pub trait CBFSQueryCompressionInfoEvent {
  fn on_query_compression_info(&self, sender : CBFS, e : &mut CBFSQueryCompressionInfoEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_query_compression_info(&self) -> &'a dyn CBFSQueryCompressionInfoEvent;
  pub fn set_on_query_compression_info(&mut self, value : &'a dyn CBFSQueryCompressionInfoEvent);
  ...
}

Remarks

This event fires when the OS needs to query the information about a compressed file specified by FileName. To handle this event, an application must set CompressedFileSize to the size of file data in the compressed form (usually, it is the smaller size of the original and compressed sizes). The struct reports the compression format to be COMPRESSION_FORMAT_DEFAULT.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_query_ea Event (CBFS Struct)

This event fires when the OS needs to query extended attributes of a file.

Syntax

// CBFSQueryEaEventArgs carries the CBFS QueryEa event's parameters.
pub struct CBFSQueryEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn return_single_entry(&self) -> bool
  fn ea_list(&self) -> *mut u8
  fn ea_list_length(&self) -> i32
  fn ea_index(&self) -> i32
  fn restart_scan(&self) -> bool
  fn length_returned(&self) -> i32
  fn set_length_returned(&self, value : i32)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSQueryEaEvent defines the signature of the CBFS QueryEa event's handler function.
pub trait CBFSQueryEaEvent {
  fn on_query_ea(&self, sender : CBFS, e : &mut CBFSQueryEaEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_query_ea(&self) -> &'a dyn CBFSQueryEaEvent;
  pub fn set_on_query_ea(&mut self, value : &'a dyn CBFSQueryEaEvent);
  ...
}

Remarks

This event fires when the OS needs to query extended attributes of the file specified by FileName using the ZwQueryEaFile or FltQueryEaFile function of the system API.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The Buffer parameter points to a memory buffer, into which, if the request is successful, an event handler should place the requested information. The data in the buffer must be formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The BufferLength parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

ReturnSingleEntry specifies that the event handler has to return only the first entry it has found.

EaList is an optional parameter that points to a caller-supplied memory buffer specifying the extended attributes to be queried. The data in the buffer are formatted as a FILE_GET_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The EaListLength parameter reflects the length of this data, in bytes. If the caller of the ZwQueryEaFile or FltQueryEaFile function did not specify any value, it will contain 0. The list may be modified by an event handler, if needed, provided that the size of the new or modified data does not exceed the value of the EaListLength parameter.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which is requested. This parameter should ignored by the event handler if EaList points to a nonempty list. If the caller of the ZwQueryEaFile or FltQueryEaFile function did not specify any value, the parameter will contain -1.

The RestartScan parameter instructs the event handler to restart enumeration of extended attributes from the first entry. If the parameter is false, retrieval of the extended attributes should be resumed by the event handler after a previous request.

LengthReturned is must be set to the size, in bytes, of the information, returned in the Buffer.

To handle the request, the event handler must copy no more than BufferLength bytes into Buffer and set the LengthReturned parameter's value afterward so that it correctly reflects the amount of data in Buffer.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_query_quotas Event (CBFS Struct)

This event fires when the OS needs to read quota information.

Syntax

// CBFSQueryQuotasEventArgs carries the CBFS QueryQuotas event's parameters.
pub struct CBFSQueryQuotasEventArgs {
  fn sid(&self) -> *mut u8
  fn sid_length(&self) -> i32
  fn index(&self) -> i32
  fn quota_found(&self) -> bool
  fn set_quota_found(&self, value : bool)
  fn quota_used(&self) -> i64
  fn set_quota_used(&self, value : i64)
  fn quota_threshold(&self) -> i64
  fn set_quota_threshold(&self, value : i64)
  fn quota_limit(&self) -> i64
  fn set_quota_limit(&self, value : i64)
  fn sid_out(&self) -> *mut u8
  fn sid_out_length(&self) -> i32
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSQueryQuotasEvent defines the signature of the CBFS QueryQuotas event's handler function.
pub trait CBFSQueryQuotasEvent {
  fn on_query_quotas(&self, sender : CBFS, e : &mut CBFSQueryQuotasEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_query_quotas(&self) -> &'a dyn CBFSQueryQuotasEvent;
  pub fn set_on_query_quotas(&mut self, value : &'a dyn CBFSQueryQuotasEvent);
  ...
}

Remarks

This event fires when the OS needs to read quota information, set during earlier on_set_quotas events, for one or more security identifiers (SIDs).

This event needs to be handled only if the use_disk_quotas property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Quota information is read by the OS in one of two ways. To handle this event properly, applications must be able to handle both kinds of requests by doing the following:

  1. When the OS needs a specific SID's quota information, SID will point to a memory buffer that contains that SID (in binary form, with length SIDLength).
    • If the application has a quota stored for the specified SID, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit.
    • If the application does not have quota information stored for the SID, set QuotaFound to false and leave the other parameters unchanged.
    • For such requests, Index is always -1, no SIDOut buffer is available, and SIDOutLength is 0.
  2. When the OS needs all of the quota information the application has stored, this event fires with Index set to 0 first, then continues to fire with increasing indices until all quotas have been returned.
    • For each quota the application has stored, set QuotaFound to true, and return its information by setting QuotaUsed, QuotaThreshold, and QuotaLimit. Return the SID associated with the quota by copying it, in binary form, to the memory buffer pointed to by SIDOut. The capacity of the SIDOut buffer is specified by SIDOutLength.
    • If there are more quotas to return, set QuotaFound to false and leave the other parameters unchanged.
    • For such requests, no SID buffer is available, and SIDLength is 0.

Both this event and on_set_quotas cause a quota enumeration to be started; the on_close_quotas_enumeration event will fire when the OS has finished reading quota information (this applies for both of the cases described above).

Descriptions of the QuotaUsed, QuotaThreshold, and QuotaLimit parameters can be found in the Windows API's DISKQUOTA_USER_INFORMATION structure documentation.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_read_file Event (CBFS Struct)

This event fires when the OS needs to read data from an open file.

Syntax

// CBFSReadFileEventArgs carries the CBFS ReadFile event's parameters.
pub struct CBFSReadFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn bytes_to_read(&self) -> i64
  fn bytes_read(&self) -> i64
  fn set_bytes_read(&self, value : i64)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSReadFileEvent defines the signature of the CBFS ReadFile event's handler function.
pub trait CBFSReadFileEvent {
  fn on_read_file(&self, sender : CBFS, e : &mut CBFSReadFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_read_file(&self) -> &'a dyn CBFSReadFileEvent;
  pub fn set_on_read_file(&mut self, value : &'a dyn CBFSReadFileEvent);
  ...
}

Remarks

This event fires when the OS needs to read data from the already open file specified by FileName.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications should read BytesToRead bytes of data from the specified file into the memory region pointed to by Buffer. Reading must begin at the specified Position in the file, and when reading is complete, applications must set BytesRead to reflect the actual number of bytes copied into Buffer. Applications must not attempt to copy more than BytesToRead bytes of data into Buffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Note: Although it is technically possible for an application to return fewer than BytesToRead bytes of data, doing so is abnormal, and should be avoided. Most processes treat read requests as "all or nothing", so returning less data than requested is likely to cause an ungraceful failure.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_rename_or_move_file Event (CBFS Struct)

This event fires when the OS wants to rename or move a file or directory within the virtual filesystem.

Syntax

// CBFSRenameOrMoveFileEventArgs carries the CBFS RenameOrMoveFile event's parameters.
pub struct CBFSRenameOrMoveFileEventArgs {
  fn file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSRenameOrMoveFileEvent defines the signature of the CBFS RenameOrMoveFile event's handler function.
pub trait CBFSRenameOrMoveFileEvent {
  fn on_rename_or_move_file(&self, sender : CBFS, e : &mut CBFSRenameOrMoveFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_rename_or_move_file(&self) -> &'a dyn CBFSRenameOrMoveFileEvent;
  pub fn set_on_rename_or_move_file(&mut self, value : &'a dyn CBFSRenameOrMoveFileEvent);
  ...
}

Remarks

This event fires when the OS wants to rename or move the specified file or directory from FileName to NewFileName, both of which are fully qualified and located in the virtual filesystem.

This event fires only if a file or directory with the specified NewFileName does not exist; or if such a file does exist, and an overwrite was requested. Cases in which a file with the specified NewFileName exists, and an overwrite was not requested, are handled by the struct internally.

Note: Windows only allows files to be overwritten and denies a rename or move request automatically if the destination is an existing directory.

To handle this event properly, applications must perform any actions needed to rename or move the specified file or directory in their backend storage, overwriting the destination file if necessary. An application may also, for its own reasons, decide not to overwrite a destination file, in which case it must deny the operation by returning an appropriate error code via ResultCode.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

When the FastRenameMove configuration setting is disabled, any handles to the file being renamed are closed before the rename operation and re-opened after the operation. If the rename operation fails, then the file handles are re-opened using the old name. If any of re-open operations fail, the re-opening process is stopped, and any handles that have been re-opened already are closed again.

In any case, the value specified by the ResultCode parameter is passed back to the system.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Note: If the FastRenameMove config setting is disabled, all handles would be closed before the event fires; so, both HandleInfo, FileContext, and HandleContext will be empty. To receive the correct values in these parameters, you need to enable the FastRenameMove config setting.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_allocation_size Event (CBFS Struct)

This event fires when the OS needs to set a file's allocation size.

Syntax

// CBFSSetAllocationSizeEventArgs carries the CBFS SetAllocationSize event's parameters.
pub struct CBFSSetAllocationSizeEventArgs {
  fn file_name(&self) -> &String
  fn allocation_size(&self) -> i64
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetAllocationSizeEvent defines the signature of the CBFS SetAllocationSize event's handler function.
pub trait CBFSSetAllocationSizeEvent {
  fn on_set_allocation_size(&self, sender : CBFS, e : &mut CBFSSetAllocationSizeEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_allocation_size(&self) -> &'a dyn CBFSSetAllocationSizeEvent;
  pub fn set_on_set_allocation_size(&mut self, value : &'a dyn CBFSSetAllocationSizeEvent);
  ...
}

Remarks

This event fires when the OS (or the struct, if the CorrectAllocationSizes configuration setting is enabled) needs to set the allocation size of the file specified by FileName. All files have the following three sizes associated with them:

Description Associated Event
File size The length, in bytes, of the file's contents. on_set_file_size
Allocation size The number of bytes allocated locally for the file. on_set_allocation_size
Valid data length The number of bytes that have been written to the file. on_set_valid_data_length

To handle this event properly, applications must perform any actions needed to allocate the specified amount of space for the file in their backend storage.

Note: The file's actual size should not be changed; applications that do not track allocation size separately from file size should do nothing.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The AllocationSize parameter specifies the new allocation size of the file, in bytes. This value is typically larger than the file's actual size, as some file operations reserve space for the file before any data are actually written. Applications should track such situations and avoid reallocating file space when possible to improve performance.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_default_quota_info Event (CBFS Struct)

This event fires when the OS needs to set the virtual drive's default quota information.

Syntax

// CBFSSetDefaultQuotaInfoEventArgs carries the CBFS SetDefaultQuotaInfo event's parameters.
pub struct CBFSSetDefaultQuotaInfoEventArgs {
  fn default_quota_threshold(&self) -> i64
  fn default_quota_limit(&self) -> i64
  fn file_system_control_flags(&self) -> i64
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetDefaultQuotaInfoEvent defines the signature of the CBFS SetDefaultQuotaInfo event's handler function.
pub trait CBFSSetDefaultQuotaInfoEvent {
  fn on_set_default_quota_info(&self, sender : CBFS, e : &mut CBFSSetDefaultQuotaInfoEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_default_quota_info(&self) -> &'a dyn CBFSSetDefaultQuotaInfoEvent;
  pub fn set_on_set_default_quota_info(&mut self, value : &'a dyn CBFSSetDefaultQuotaInfoEvent);
  ...
}

Remarks

This event fires when the OS needs to set the virtual drive's default quota information.

This event needs to be handled only if the use_disk_quotas property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must store the virtual drive's default quota information using the value specified by DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags.

Descriptions of the DefaultQuotaThreshold, DefaultQuotaLimit, and FileSystemControlFlags parameters can be found in the Windows API's FILE_FS_CONTROL_INFORMATION structure documentation.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_ea Event (CBFS Struct)

This event fires when the OS needs to set extended attributes of a file.

Syntax

// CBFSSetEaEventArgs carries the CBFS SetEa event's parameters.
pub struct CBFSSetEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetEaEvent defines the signature of the CBFS SetEa event's handler function.
pub trait CBFSSetEaEvent {
  fn on_set_ea(&self, sender : CBFS, e : &mut CBFSSetEaEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_ea(&self) -> &'a dyn CBFSSetEaEvent;
  pub fn set_on_set_ea(&mut self, value : &'a dyn CBFSSetEaEvent);
  ...
}

Remarks

This event fires when the OS needs to set extended attributes of the file specified by FileName using the ZwSetEaFile or FltSetEaFile function of the system API.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The BufferLength parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to Microsoft's documentation for more information.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_file_attributes Event (CBFS Struct)

This event fires when the OS needs to change the attributes of an open file or directory.

Syntax

// CBFSSetFileAttributesEventArgs carries the CBFS SetFileAttributes event's parameters.
pub struct CBFSSetFileAttributesEventArgs {
  fn file_name(&self) -> &String
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn attributes(&self) -> i32
  fn event_origin(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetFileAttributesEvent defines the signature of the CBFS SetFileAttributes event's handler function.
pub trait CBFSSetFileAttributesEvent {
  fn on_set_file_attributes(&self, sender : CBFS, e : &mut CBFSSetFileAttributesEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_file_attributes(&self) -> &'a dyn CBFSSetFileAttributesEvent;
  pub fn set_on_set_file_attributes(&mut self, value : &'a dyn CBFSSetFileAttributesEvent);
  ...
}

Remarks

This event fires when the OS needs to change the attributes of the already-open file or directory specified by FileName.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must update the attributes of the specified file or directory in their backend storage using the following parameters:

  • Attributes: The new attributes of the file or directory, or 0 to indicate that the existing attributes must remain unchanged.
    • FILE_ATTRIBUTE_NORMAL: This attribute is valid only when used alone; it "resets" a file's attributes.
    • Please refer to Microsoft's File Attribute Constants article for attribute descriptions.
    If the support_compressed_attribute property is set to true, an event handler should properly handle the presence or absence of the FILE_ATTRIBUTE_COMPRESSED in the Attributes parameter, possibly compressing or decompressing the file.
  • CreationTime, LastAccessTime, LastWriteTime, ChangeTime: The new time values for the file or directory, any of which may be January 1, 1601 00:00:00 UTC to indicate that the existing value of the corresponding time must remain unchanged.

The EventOrigin parameter indicates, which filesystem operation led to the change of attributes. It can contain one of the following values:

SETFA_ORIGIN_CREATE_FILE0x0000The attributes are set as a part of a file create/open operation.

SETFA_ORIGIN_SET_INFORMATION0x0006The attributes are set via the SetFileAttributes or NtSetInformationFile function.

SETFA_ORIGIN_FSCTL0x000dA file's Compressed state is changed using one of the *DeviceIOControl functions.

SETFA_ORIGIN_CLEANUP0x0012A handle to the file is being closed and its attributes are updated .

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_file_security Event (CBFS Struct)

This event fires when the OS wants to change the Windows security attributes of a file or directory.

Syntax

// CBFSSetFileSecurityEventArgs carries the CBFS SetFileSecurity event's parameters.
pub struct CBFSSetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetFileSecurityEvent defines the signature of the CBFS SetFileSecurity event's handler function.
pub trait CBFSSetFileSecurityEvent {
  fn on_set_file_security(&self, sender : CBFS, e : &mut CBFSSetFileSecurityEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_file_security(&self) -> &'a dyn CBFSSetFileSecurityEvent;
  pub fn set_on_set_file_security(&mut self, value : &'a dyn CBFSSetFileSecurityEvent);
  ...
}

Remarks

This event fires when the OS wants to change the Windows security attributes of the file or directory specified by FileName.

This event needs to be handled only if the use_windows_security property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must update the pieces of security information, specified by SecurityInformation, on the specified file or directory in their backend storage. Please refer to the following parameter descriptions, as well as the Security Checks topic, for more information.

The SecurityInformation parameter indicates which pieces of security information must be set. This value is a bitfield; possible flags include (but are not limited to):

  • OWNER_SECURITY_INFORMATION
  • GROUP_SECURITY_INFORMATION
  • DACL_SECURITY_INFORMATION
  • SACL_SECURITY_INFORMATION
Please refer to Microsoft's SECURITY_INFORMATION data-type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains data indicated by SecurityInformation. The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to those articles for more information about self-relative security descriptors.

The Length parameter specifies the length, in bytes, of SecurityDescriptor.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_file_size Event (CBFS Struct)

This event fires when the OS needs to change the size of an open file.

Syntax

// CBFSSetFileSizeEventArgs carries the CBFS SetFileSize event's parameters.
pub struct CBFSSetFileSizeEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetFileSizeEvent defines the signature of the CBFS SetFileSize event's handler function.
pub trait CBFSSetFileSizeEvent {
  fn on_set_file_size(&self, sender : CBFS, e : &mut CBFSSetFileSizeEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_file_size(&self) -> &'a dyn CBFSSetFileSizeEvent;
  pub fn set_on_set_file_size(&mut self, value : &'a dyn CBFSSetFileSizeEvent);
  ...
}

Remarks

This event fires when the OS needs to change the size of the already-open file specified by FileName. All files have the following three sizes associated with them:

Description Associated Event
File size The length, in bytes, of the file's contents. on_set_file_size
Allocation size The number of bytes allocated locally for the file. on_set_allocation_size
Valid data length The number of bytes that have been written to the file. on_set_valid_data_length

To handle this event properly, applications must perform any actions needed to resize the specified file in their backend storage.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The Size parameter specifies the new size of the file, in bytes. Extending a file does not require actual space to be allocated; however, NTFS allocates and zeroes the newly added space, and some third-party applications might expect such behavior if the virtual filesystem is identified (via file_system_name) as NTFS.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_object_id Event (CBFS Struct)

This event fires when the OS needs to set the object Id and extended information of a volume or of a filesystem entry.

Syntax

// CBFSSetObjectIdEventArgs carries the CBFS SetObjectId event's parameters.
pub struct CBFSSetObjectIdEventArgs {
  fn file_name(&self) -> &String
  fn only_extended_info(&self) -> bool
  fn object_id(&self) -> *mut u8
  fn object_id_length(&self) -> i32
  fn extended_information(&self) -> *mut u8
  fn extended_information_length(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetObjectIdEvent defines the signature of the CBFS SetObjectId event's handler function.
pub trait CBFSSetObjectIdEvent {
  fn on_set_object_id(&self, sender : CBFS, e : &mut CBFSSetObjectIdEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_object_id(&self) -> &'a dyn CBFSSetObjectIdEvent;
  pub fn set_on_set_object_id(&mut self, value : &'a dyn CBFSSetObjectIdEvent);
  ...
}

Remarks

This event fires when the OS needs to set the object Id and extended information for the virtual drive volume or one of its files or directories. If the object ID is set for a file or directory, this entry is identified with the FileName parameter. If the request is made for the volume, FileName will be empty.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must store the values specified by ObjectId and ExtendedInformation, which are are the two parts of the FILE_OBJECT_BUFFER structure, split for convenience. The values in these parameters are specified by the OS or the caller process; they will always has a size of 16 and 48 bytes, respectively.

When an application sets the extended information, it may set the data in the ExtendedInformation block to some arbitrary data that doesn't follow the DUMMYSTRUCTURE part of the FILE_OBJECT_BUFFER format.

OnlyExtendedInfo

If OnlyExtendedInfo is true, the application must ignore ObjectId and update only the extended information, taking it from ExtendedInformation. If OnlyExtendedInfo is false, both the Object Id and the Extended Information must be set.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_quotas Event (CBFS Struct)

This event fires when the OS needs to update quota information.

Syntax

// CBFSSetQuotasEventArgs carries the CBFS SetQuotas event's parameters.
pub struct CBFSSetQuotasEventArgs {
  fn sid(&self) -> *mut u8
  fn sid_length(&self) -> i32
  fn remove_quota(&self) -> bool
  fn quota_found(&self) -> bool
  fn set_quota_found(&self, value : bool)
  fn quota_used(&self) -> i64
  fn quota_threshold(&self) -> i64
  fn quota_limit(&self) -> i64
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetQuotasEvent defines the signature of the CBFS SetQuotas event's handler function.
pub trait CBFSSetQuotasEvent {
  fn on_set_quotas(&self, sender : CBFS, e : &mut CBFSSetQuotasEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_quotas(&self) -> &'a dyn CBFSSetQuotasEvent;
  pub fn set_on_set_quotas(&mut self, value : &'a dyn CBFSSetQuotasEvent);
  ...
}

Remarks

This event fires when the OS needs to set, update, or remove quota information for the security identifier specified by SID. If quota information needs to be set/updated/removed for multiple security identifiers (SIDs), this event will fire multiple times in succession.

This event needs to be handled only if the use_disk_quotas property is enabled.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications must either store or remove the quota information for the security identifier specified by SID:

  • If RemoveQuota is false, set or update the SID's quota information using the values specified by QuotaUsed, QuotaFound, and QuotaLimit.
  • If RemoveQuota is true, and the application has quota information stored for the SID, remove that information and set QuotaFound to true. If the application does not have quota information stored for the SID, set QuotaFound to false.
Both this event and on_query_quotas cause a quota enumeration to be started; the on_close_quotas_enumeration event will fire when the OS has finished setting/updating/removing quota information.

Descriptions of the QuotaUsed, QuotaThreshold, and QuotaLimit parameters can be found in the Windows API's DISKQUOTA_USER_INFORMATION structure documentation.

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts topic for more information.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_reparse_point Event (CBFS Struct)

This event fires when the OS wants to create or update a reparse point on a file or directory.

Syntax

// CBFSSetReparsePointEventArgs carries the CBFS SetReparsePoint event's parameters.
pub struct CBFSSetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_tag(&self) -> i64
  fn reparse_buffer(&self) -> *mut u8
  fn reparse_buffer_length(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetReparsePointEvent defines the signature of the CBFS SetReparsePoint event's handler function.
pub trait CBFSSetReparsePointEvent {
  fn on_set_reparse_point(&self, sender : CBFS, e : &mut CBFSSetReparsePointEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_reparse_point(&self) -> &'a dyn CBFSSetReparsePointEvent;
  pub fn set_on_set_reparse_point(&mut self, value : &'a dyn CBFSSetReparsePointEvent);
  ...
}

Remarks

This event fires when the OS wants to create or update a reparse point on the file or directory specified by FileName.

This event needs to be handled only if the use_reparse_points property is enabled.

Note: Network file sharing (NFS) makes use of reparse points.

To handle this event properly, applications must store the given reparse point data and tag, and associate them with the specified file or directory, in their backend storage. Both pieces of information are needed for the application to correctly handle any future on_get_file_info and on_enumerate_directory events concerning the specified file or directory.

Please refer to the Reparse Points topic for more information.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ReparseTag parameter specifies the reparse point's tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the struct extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that contains the full reparse point data. The ReparseBufferLength parameter specifies the length, in bytes, of ReparseBuffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_valid_data_length Event (CBFS Struct)

This event fires when the OS needs to set a file's valid data length.

Syntax

// CBFSSetValidDataLengthEventArgs carries the CBFS SetValidDataLength event's parameters.
pub struct CBFSSetValidDataLengthEventArgs {
  fn file_name(&self) -> &String
  fn valid_data_length(&self) -> i64
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetValidDataLengthEvent defines the signature of the CBFS SetValidDataLength event's handler function.
pub trait CBFSSetValidDataLengthEvent {
  fn on_set_valid_data_length(&self, sender : CBFS, e : &mut CBFSSetValidDataLengthEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_valid_data_length(&self) -> &'a dyn CBFSSetValidDataLengthEvent;
  pub fn set_on_set_valid_data_length(&mut self, value : &'a dyn CBFSSetValidDataLengthEvent);
  ...
}

Remarks

This event fires when the OS needs to set the valid data length of the file specified by FileName. All files have the following three sizes associated with them:

Description Associated Event
File size The length, in bytes, of the file's contents. on_set_file_size
Allocation size The number of bytes allocated locally for the file. on_set_allocation_size
Valid data length The number of bytes that have been written to the file. on_set_valid_data_length

Typically, a file's valid data length is explicitly changed only when a process wishes to quickly allocate large amounts of storage space. In such cases, the on_set_file_size event will fire first to set the desired file size, and then this event will fire to inform the virtual filesystem that it does not need to fill that space with zeros. Please refer to the Windows API's SetFileValidData function documentation for more information.

To handle this event properly, applications must perform any actions needed to update the specified file's valid data length.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ValidDataLength parameter specifies the new valid data length, in bytes, for the file. This is the same value as passed to the Windows API's SetFileValidData function.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_set_volume_label Event (CBFS Struct)

This event fires when the OS wants to change the volume label.

Syntax

// CBFSSetVolumeLabelEventArgs carries the CBFS SetVolumeLabel event's parameters.
pub struct CBFSSetVolumeLabelEventArgs {
  fn volume_label(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSSetVolumeLabelEvent defines the signature of the CBFS SetVolumeLabel event's handler function.
pub trait CBFSSetVolumeLabelEvent {
  fn on_set_volume_label(&self, sender : CBFS, e : &mut CBFSSetVolumeLabelEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_set_volume_label(&self) -> &'a dyn CBFSSetVolumeLabelEvent;
  pub fn set_on_set_volume_label(&mut self, value : &'a dyn CBFSSetVolumeLabelEvent);
  ...
}

Remarks

This event fires when the OS wants to change the volume label of the virtual drive.

To handle this event properly, applications must store the new volume label specified by VolumeLabel.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_unlock_file Event (CBFS Struct)

This event fires when the OS needs to unlock a range of bytes in a file.

Syntax

// CBFSUnlockFileEventArgs carries the CBFS UnlockFile event's parameters.
pub struct CBFSUnlockFileEventArgs {
  fn file_name(&self) -> &String
  fn byte_offset(&self) -> i64
  fn length(&self) -> i64
  fn key(&self) -> i32
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSUnlockFileEvent defines the signature of the CBFS UnlockFile event's handler function.
pub trait CBFSUnlockFileEvent {
  fn on_unlock_file(&self, sender : CBFS, e : &mut CBFSUnlockFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_unlock_file(&self) -> &'a dyn CBFSUnlockFileEvent;
  pub fn set_on_unlock_file(&mut self, value : &'a dyn CBFSUnlockFileEvent);
  ...
}

Remarks

This event fires when the OS needs to unlock a range of bytes in the file specified by FileName. Typically, such requests originate from the Windows API's UnlockFile and UnlockFileEx functions.

This event is optional. The CBFS struct automatically manages file locks in the virtual filesystem. So, if the resources an application uses for backend storage (e.g., files, memory, a database) are never directly accessed by anything other than the application itself, then there is no reason to implement this event.

If, however, an application's backend storage involves shared resources (i.e., those that could be accessed by something other than the application at any time), then this event should be used to perform any actions needed to propagate the unlock request.

For example, if an application's backend storage implementation involves files stored on a network server, then the unlock request should be communicated to that server.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

Applications that implement this event must also implement the on_lock_file event.

The ByteOffset and Length parameters specify the starting position of the range being unlocked, and the length of that range, respectively. If both values are set to -1, the system has sent IRP_MN_UNLOCK_ALL request and all regions must be unlocked. The latter behavior is used only when the SupportUnlockAllRequests configuration setting is explicitly enabled by the application.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock. The value is the same that was passed in the Lock request that locked the region, which currently is unlocked using this request.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Note: The OS does not expect the file unlock request to fail and ignores the error code that is returned by the struct.

on_unmount Event (CBFS Struct)

This event fires after the struct unmounts media from the virtual drive, making it unavailable.

Syntax

// CBFSUnmountEventArgs carries the CBFS Unmount event's parameters.
pub struct CBFSUnmountEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSUnmountEvent defines the signature of the CBFS Unmount event's handler function.
pub trait CBFSUnmountEvent {
  fn on_unmount(&self, sender : CBFS, e : &mut CBFSUnmountEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_unmount(&self) -> &'a dyn CBFSUnmountEvent;
  pub fn set_on_unmount(&mut self, value : &'a dyn CBFSUnmountEvent);
  ...
}

Remarks

This event fires once the struct has unmounted media from the virtual drive, making it unavailable. Please refer to unmount_media and delete_storage for more information.

This event is optional; it is provided to give applications a chance to perform additional processing when the virtual filesystem becomes unavailable.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_worker_thread_creation Event (CBFS Struct)

Fires just after a new worker thread is created.

Syntax

// CBFSWorkerThreadCreationEventArgs carries the CBFS WorkerThreadCreation event's parameters.
pub struct CBFSWorkerThreadCreationEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSWorkerThreadCreationEvent defines the signature of the CBFS WorkerThreadCreation event's handler function.
pub trait CBFSWorkerThreadCreationEvent {
  fn on_worker_thread_creation(&self, sender : CBFS, e : &mut CBFSWorkerThreadCreationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_worker_thread_creation(&self) -> &'a dyn CBFSWorkerThreadCreationEvent;
  pub fn set_on_worker_thread_creation(&mut self, value : &'a dyn CBFSWorkerThreadCreationEvent);
  ...
}

Remarks

This event fires just after a worker thread is created, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing when a new worker thread is created, such as allocating per-thread objects.

The struct maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

on_worker_thread_termination Event (CBFS Struct)

Fires just before a worker thread is terminated.

Syntax

// CBFSWorkerThreadTerminationEventArgs carries the CBFS WorkerThreadTermination event's parameters.
pub struct CBFSWorkerThreadTerminationEventArgs {
}

// CBFSWorkerThreadTerminationEvent defines the signature of the CBFS WorkerThreadTermination event's handler function.
pub trait CBFSWorkerThreadTerminationEvent {
  fn on_worker_thread_termination(&self, sender : CBFS, e : &mut CBFSWorkerThreadTerminationEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_worker_thread_termination(&self) -> &'a dyn CBFSWorkerThreadTerminationEvent;
  pub fn set_on_worker_thread_termination(&mut self, value : &'a dyn CBFSWorkerThreadTerminationEvent);
  ...
}

Remarks

This event fires just before a worker thread is terminated, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing before a worker thread is terminated, such as deallocating per-thread objects.

The struct maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

Any errors that occur during this event are ignored.

on_write_file Event (CBFS Struct)

This event fires when the OS needs to write data to an open file.

Syntax

// CBFSWriteFileEventArgs carries the CBFS WriteFile event's parameters.
pub struct CBFSWriteFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn bytes_to_write(&self) -> i64
  fn bytes_written(&self) -> i64
  fn set_bytes_written(&self, value : i64)
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSWriteFileEvent defines the signature of the CBFS WriteFile event's handler function.
pub trait CBFSWriteFileEvent {
  fn on_write_file(&self, sender : CBFS, e : &mut CBFSWriteFileEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_write_file(&self) -> &'a dyn CBFSWriteFileEvent;
  pub fn set_on_write_file(&mut self, value : &'a dyn CBFSWriteFileEvent);
  ...
}

Remarks

This event fires when the OS needs to write data to the already-open file specified by FileName.

IMPORTANT: Not everything is possible or allowed in the event handlers. Please see the Event Handling topic for details.

To handle this event properly, applications should write BytesToWrite bytes of data to the specified file, copying it from the memory region pointed to by Buffer. Writing must begin at the specified Position in the file, and when writing is complete, applications must set BytesWritten to reflect the actual number of bytes written to the file. Applications must not attempt to copy more than BytesToWrite bytes of data from Buffer.

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Note: Although it is technically possible for an application to write fewer than BytesToWrite bytes of data, doing so is abnormal, and should be avoided. Most processes treat write requests as "all or nothing", so writing less data than requested is likely to cause an ungraceful failure.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token. (This parameter may be absent, in which case it will be 0.)

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (HandleContext may be absent, in which case it will be .)

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Note: In most cases, the event is fired when the cache needs to write the data to the filesystem. This happens asynchronously, later than process(es) called the WriteFile() function or alternatives. For such asynchronous write events, the result code returned by the event handler does not get back to the process or processes that wrote the data.

on_zeroize_file_range Event (CBFS Struct)

This event fires when the OS needs to write a block of zeros to a file.

Syntax

// CBFSZeroizeFileRangeEventArgs carries the CBFS ZeroizeFileRange event's parameters.
pub struct CBFSZeroizeFileRangeEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn length(&self) -> i64
  fn handle_info(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFSZeroizeFileRangeEvent defines the signature of the CBFS ZeroizeFileRange event's handler function.
pub trait CBFSZeroizeFileRangeEvent {
  fn on_zeroize_file_range(&self, sender : CBFS, e : &mut CBFSZeroizeFileRangeEventArgs);
}

impl <'a> CBFS<'a> {
  pub fn on_zeroize_file_range(&self) -> &'a dyn CBFSZeroizeFileRangeEvent;
  pub fn set_on_zeroize_file_range(&mut self, value : &'a dyn CBFSZeroizeFileRangeEvent);
  ...
}

Remarks

This event fires when the OS needs to write a block of zeros to the file specified by FileName. The block must be stored starting at Position, and the size of the block is Length bytes. The size of the file is not extended by this operation.

If the file is not sparse and not compressed, the operation is analogous to the on_write_file event, and an application must handle it in the same way.

If the file is sparse or compressed, the application may optimize storage operations by not writing actual zeros to the file but keeping a record of their presense. For a sparse or compressed file, this operation creates a valid range. The starting point and size of the range don't have to exactly match the range which has been zeroized. For example, if a caller zeroizes one byte at position 1126, the filesystem may create a range with a starting point at 1024 bytes and the length of 2048 bytes.

The HandleInfo parameter carries a handle to an object with information about the file handle. While within the event handler, it can be used to call any of the following methods: get_handle_creator_process_id, get_handle_creator_process_name, get_handle_creator_thread_id, or get_handle_creator_token.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

Config Settings (CBFS Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

CBFS Config Settings

AllowOriginatorBufferMapping:   Whether read file, write file, and enumerate directory requests may pass original buffers to event handlers.

When firing the on_read_file, on_write_file, and on_enumerate_directory events, the driver can do one of two things:

  1. Map the original buffer from the underlying request into the application's address space, and pass it to the event handler directly.
  2. Allocate an intermediary buffer to pass to the event handler, and copy the data between it and the original buffer as needed.

The first option is faster because no data copying occurs. However, it also causes the event timeout mechanism to be disabled for a particular event fired for the request. The lack of event timeout means that the driver cannot complete the underlying request until the event handler returns, which can lead to situations in which the filesystem (or the operating system itself) becomes "stuck" because it is blocked by the event handler.

By default, this configuration setting is enabled, and the driver will map the original buffer into the application's address space and pass it to the event handler directly, if possible. (An intermediary buffer is always used if the original buffer's data length is not a multiple of the memory page size, or if the offset of the buffer is not aligned to the page boundary.)

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

AllowReadOutsideEof:   Whether read requests beyond the end of a file are surfaced, or automatically denied.

This configuration setting specifies whether read requests beyond the end of a file are surfaced through the on_read_file event, or automatically denied by the driver.

By default, this configuration setting is disabled, and the driver will automatically deny read requests beyond the end of a file by returning the appropriate error.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

AlwaysFireIsDirectoryEmpty:   Specifies whether the IsDirectoryEmpty event should fire even when the driver has the needed information.

This configuration setting specifies how the driver should act in regard to a deletion when it needs to check if the directory is empty. When the setting is disabled (default), the driver checks the metadata cache to figure out if a directory contains files, which increases performance. Enable this configuration setting to make IsDirectoryEmpty fire unconditionally.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

AsyncDeleteStorageNotifications:   Whether system broadcasts for virtual drive deletion are sent asynchronously.

This setting specifies whether the WM_DEVICECHANGE broadcast is sent asynchronously (true) or synchronously (false) when the virtual drive is deleted using delete_storage.

By default, this setting is enabled, and the broadcast is sent asynchronously. This is typically sufficient, but applications may disable this setting if they find that Windows File Explorer is still presenting virtual drives as available after they've been deleted (which may occur if the application exits immediately after deleting a virtual drive).

CacheDuringLockGetSize:   Specifies whether the file size should be requested via the GetFileInfo event when a file is locked.

This configuration setting enables the supplementary driver behavior when the range of file data is locked by an application. By default, the setting is disabled. When the setting is enabled, the driver fires the on_get_file_info event and updates the size information stored in the system shortly after locking is completed.

This setting is effective when any type of file data cache is used.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

CacheDuringLockPurge:   Specifies the strategy of handling the cached data when a file is locked.

When a file is locked, some scenarios may require the cache to flush and/or purge the data of the locked region or of the file in whole. The possible values are

  • 0 - None: Do nothing in regard to the cached data. Note: - if the CacheDuringLockGetSize setting is enabled and the change of file size is detected, the cache manager may decide to flush or purge the data.
  • 1 - Flush and Purge Range: Causes the driver to flush the range being locked, then remove this data from the cache.
  • 2 - Flush and Purge All: Causes the driver to flush all file data that are kept in the cache, then remove them from the cache.
  • 3 - Purge Range: Causes the driver to discard the range of data being locked and remove it from the cache.

This setting is effective when any type of file data cache is used.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

ClusterSize:   The cluster size to create the virtual drive with.

This configuration setting specifies the number of bytes each cluster on the virtual drive contains; it must either be set to a multiple of SectorSize, or 0 to use the same value as SectorSize.

All filesystems in Windows organize hard drive storage space based on cluster size (also known as "allocation unit size"). Cluster size represents the smallest amount of storage space that can be used to hold a file. Common cluster sizes for FAT and NTFS filesystems are 4096, 8192, and 16384 bytes.

The struct does not use this value for any purpose besides passing it to the OS. Some applications use a drive's cluster size to calculate the size of the buffer used to transfer data in read/write operations. Increasing the cluster size may reduce the number of times the on_read_file and on_write_file events fire for such applications.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

CorrectAllocationSizes:   Whether to perform automatic allocation size correction.

This configuration setting specifies whether the struct should perform automatic allocation size correction. Allocation size measures how many bytes of storage are actually used to hold a file, and typically a file's allocation size is greater than or equal to its actual size.

However, thanks to the flexibility of CBFS-based virtual filesystems, it is possible for a file's data to be stored remotely, with only a portion of it available locally. In such cases, a file's allocation size may indeed be less than its actual size, because the allocation size tracks the amount of local storage that has been allocated for a file.

The struct internally caches the allocation size of each file that is currently open. If this configuration setting is enabled (default) and the file is not compressed or sparse, the struct automatically corrects the known allocation size to be greater than the file's actual size when necessary. The on_set_allocation_size event is fired any time this occurs.

Applications can disable this configuration setting to prevent the struct from automatically adjusting the allocation sizes they report. When this configuration setting is disabled, and an application changes a file's allocation size, it must call the notify_directory_change method using the CBFS_NOTIFY_FLAG_ALLOCATION_SIZE_MODIFIED flag to inform the struct and the OS of the change.

Files which are Compressed or Sparse are always treated as if this setting is disabled.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

DockerContainerId:   Id of the running Docker container, in which the virtual drive should be created.

This configuration setting is optional and is used when an application running on the host needs to create a drive in a container. This configuration setting is applicable only when calling add_mounting_point and remove_mounting_point.

The value should be either the 12-character short Id, for example 4c01db0b339c, the full 64-character Id of the container, or the GUID of the Windows container in registry format.

This setting is not needed when the application is running within a container. Set this value only when the application is running on the host machine.

Querying this setting when a value has not yet been specified will return an empty string if the process is running on the host, or the GUID of the container if the process is running within a container. This may be used as a mechanism to determine whether the application is running on the host, or within a container. If a value has previously been set, querying this setting will return the value that was originally specified.

FastRenameMove:   Whether open files are closed and re-opened during a rename or move operation.

This configuration setting specifies whether, for open files, the struct should close and reopen them as part of the overall rename or move operation. (This configuration setting does not affect the process of renaming or moving closed files.)

When this configuration setting is enabled, the struct performs rename and move operations on open files the same way the system does: the file is opened, renamed or moved, and then closed. The sequence of events is as follows:

  1. The file is opened one or more times by the OS, causing the on_create_file and/or on_open_file events to fire.
  2. <...Other events may fire...>
  3. The file is renamed, causing the on_rename_or_move_file event to fire. If the operation succeeds, the file gets a new name.
  4. <...Other events may fire...>
  5. The file is closed, causing the on_cleanup_file and on_close_file events to fire.

When this configuration setting is disabled, the struct performs rename and move operations on open files by closing all open handles to the file, executing the rename/move operation, and then reopening the file using its new name. The file is reopened once for each handle that was closed before the rename/move operation. The sequence of events is as follows:

  1. The file is opened one or more times by the OS, causing the on_create_file and/or on_open_file events to fire.
  2. <...Other events may fire...>
  3. A request to rename or move the file arrives. The struct performs (emulates) closing all of the currently open file handles, causing the on_cleanup_file and on_close_file events to fire (once each for each open handle). All handle closing occurs within a single worker thread without context switches (so the overall operation is fairly fast, but not multithreaded).
  4. The on_rename_or_move_file event fires for the "completely closed" file.
  5. Finally, the file is reopened by the struct using its new name, causing the on_open_file event to fire once for each of the handles that was closed previously. Again, all opens are performed sequentially on a single worker thread, without context switches.
  6. <...Other events may fire...>
  7. The file is closed, causing the on_cleanup_file and on_close_file events to fire.

By default, this configuration setting is disabled, which is the slower but more conservative option; an application whose backend storage supports renames/moves for open resources can try to enable this configuration setting to improve performance.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

FileCachePolicyPurgeOnClose:   Whether file data should be purged from the cache when the file is closed.

This configuration setting specifies whether the struct should purge a file's data from the file data cache as soon as the file is closed. By default, this configuration setting is disabled, and the struct keeps the data from closed files cached for future use.

Please refer to the Caching topic for more information.

Note: This setting cannot be changed within events.

FileCachePolicyWriteThrough:   Whether file data should be written to storage as it is written to the cache.

This configuration setting specifies whether the struct should write file data out to storage (via on_write_file) as it is written to the cache. By default, this configuration setting is disabled, and data are written to the cache first and flushed out to storage later (assuming file caching is enabled).

Please refer to the Caching topic for more information.

Note: This setting cannot be changed within events.

FireSetFileSizeOnWrite:   Whether to fire SetFileSize before WriteFile if writing would expand the file.

This configuration setting specifies whether the on_set_file_size event should be fired before firing the on_write_file event if the write operation in question would cause the file's size to increase.

When this configuration setting is enabled (default), and the on_set_file_size operation is successful, then either the data are written to the file data cache or the on_write_file event is subsequently fired. It is also possible for the application to deny the request to expand the file (e.g., because of insufficient storage space).

When this configuration setting is disabled, on_set_file_size will not be fired when a write request would require the file to expand, which results in fewer events being fired and thus increased performance. In this case, if the data are written to the file data cache first and on_write_file is fired later (when the cache gets flushed), then any file expansion errors that occur at that time will not be reported to the originator of the write request. Instead, the OS will report them via a notification on the active desktop.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

FlushFileBeforeUnlock:   Whether file buffers are flushed before completion of UnlockFile operation.

Normally, the cached data of the file are managed by the cache manager automatically. If the application implements a network filesystem and handles file lock operations by locking the file beyond the local enironment, it is desired that the data written under the lock are flushed during unlock to let the application send them to remote locations. Enable this configuration setting for such flushing to occur automatically.

By default, this configuration setting is disabled.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

ForceFileClose:   Whether the driver should force files to close after the last handle to them is closed.

This configuration setting specifies the desired behavior in handling of files when they are closed.

A file is not closed after the last handle to it is closed (i.e., after the last on_cleanup_file event fires); it is closed only after the last on_close_file event fires. If a file is cached or memory-mapped, the system may hold it open for quite a while (minutes, or even hours) after the last handle to it is closed.

When this configuration setting is enabled (default), then after the last handle to a file is closed, the driver will wait some time (as defined by the ForceFileCloseDelay setting), and then it will attempt to flush and purge any in-memory file data, allowing it to be formally closed.

Disabling this configuration setting slightly improves performance in the case of repeated access to files on the virtual drive; however, on_close_file events can be significantly delayed.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

ForceFileCloseDelay:   Specifies the timeout between the closing of a last handle of a file and the moment the driver tries to close the file.

This configuration setting is a companion to the ForceFileClose setting. The timeout is set in milliseconds: the default value is 3,000 ms, and the minimal allowed value is 500 ms.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

ImplicitAttributeUpdates:   Whether SetFileAttributes fires when a file is modified.

By default, this setting is enabled, and the on_set_file_attributes event fires when file modification occurs (usually, when a file handle is closed) to update modification time and attributes. If the setting is disabled, on_set_file_attributes will fire only when times or attributes are changed by some process explicitly (using the IRP_MJ_SET_INFORMATION system call).

LockRetryInterval:   Time between repeated lock attempts.

When LockFile event handler returns ERROR_RETRY, the request will be repeated after the time specified in this setting. The vlaue is in milliseconds, minimum is 100 and the default is 500.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

LoggingEnabled:   Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this struct; it is disabled by default. Please refer to the Error Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxReadBlockSize:   The maximum buffer size allowed for the ReadFile event.

This configuration setting specifies the maximum size, in bytes, of the buffer passed to the on_read_file event. The default value of 0 means "no limit", in which case the struct will always pass a buffer large enough to hold all of the requested data in a single on_write_file event.

Note: Unlimited buffer sizes may not be suitable for use-cases in which the virtual filesystem is backed by network operations or other "slow" storage, because attempting to handle large (more than 100 MB) blocks may take longer than the configured event timeout duration.

Applications with constraints such as those described earlier can use this configuration setting to limit how much data they have to process in a single on_read_file event. If a read request arrives requesting more data than the limit allows, the struct will "split up" the overall buffer into smaller chunks and fire the on_read_file event individually for each one (and reset the timeout timer between each event).

Note: This setting cannot be changed within events.

MaxWorkerThreadCount:   The maximum number of worker threads to use to fire events.

(CBFS and FUSE structs on Windows only) This setting specifies the maximum number of worker threads the struct may create to fire events on when the serialize_events property is set to seOnMultipleThreads. (If other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors.

MaxWriteBlockSize:   The maximum buffer size allowed for the WriteFile event.

This configuration setting specifies the maximum size, in bytes, of the buffer passed to the on_write_file event. The default value of 0 means "no limit", in which case the struct will always pass a buffer containing all of the data to write in a single on_write_file event.

Note: Unlimited buffer sizes may not be suitable for use-cases in which the virtual filesystem is backed by network operations or other "slow" storage, because attempting to handle large (more than 100 MB) blocks may take longer than the configured event timeout duration.

Applications with constraints such as those described earlier can use this configuration setting to limit how much data they have to process in a single on_write_file event. If a write request arrives carrying more data than the limit allows, the struct will "split up" the overall buffer into smaller chunks and fire the on_write_file event individually for each one (and reset the timeout timer between each event).

Note: This setting cannot be changed within events.

MinWorkerThreadCount:   The minimum number of worker threads to use to fire events.

(CBFS and FUSE structs on Windows only) This setting specifies the minimum number of worker threads the struct should create to fire events on when the serialize_events property is set to seOnMultipleThreads. (In other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

NrDeviceQueryInfoHandling:   Whether the network redirector module should respond to file-specific requests sent to non-file entries.

Some filter drivers send file-specific requests to our network device object. This behavior can lead to a "Device does not recognize the command" error when attempting to create or mount a filesystem. By default, this configuration setting is disabled to prevent unexpected conflicts with other software.

This configuration setting changes the default behavior of our network redirector module to handle such requests.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

OmitEventFilenames:   Whether the file name parameter should be empty in events.

In some editions of CBFS Connect, passing an extra string parameter to events involves extra allocation of memory and is the unnecessary expenditure of computer resources. Enabling this configuration setting makes the component skip passing the file name to all events except on_create_file, on_open_file, and on_get_file_info . Event handlers can obtain the file or directory name by calling the get_event_file_name method.

By default, this configuration setting is disabled.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

SectorSize:   The sector size to create the virtual drive with.

This setting specifies the number of bytes each "sector" on the virtual drive contains. This setting must be set to a value that is a multiple of 512, a power of 2, and not larger than 4096 (e.g., 512, 1024, 2048, 4096).

By default, this setting is set to 512; using a different value is not recommended.

StorageNamePrefix:   The fixed prefix to use in device object names.

An application may add this prefix to device object names created by the driver so that it is used as a fixed storage identifier in other applications (antivirus, data protection tools etc.).

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

SupportPosixStyleDeletion:   Whether the driver should close all open handles to a file being deleted.

This configuration setting specifies that the driver should handle the FILE_DISPOSITION_POSIX_SEMANTICS flag, when it is set on a file object.

When this configuration setting is enabled, the driver forcefully closes all open handles to a file that is being deleted, if these handles include SHARE_DELETE flag. By default, this configuration setting is disabled to prevent unexpected behavior in applications that own handles.

Note: This setting cannot be changed within events.

SupportSearchIndexer:   Specifies whether the driver must take additional measures to support indexing by Windows Search.

The Search Indexer of Windows 10 has been recently modified in the way that Search Indexer stopped indexing virtual disks. This happens because of the missing mounting point when the disk is created.

This setting, when enabled, tells the driver to create a fake mounting point and use it to work around the Search Indexer bug. By default, this setting is disabled.

Note: This property cannot be changed within events.

SupportUnlockAllRequests:   Whether the driver should fire the UnlockFile event for IRP_MN_UNLOCK_ALL requests or process them internally.

When this configuration setting is disabled, the driver handles an IRP_MN_UNLOCK_ALL request internally and fires the on_unlock_file event for each locked range, passing its offset and length to the event handler.

When this configuration setting is enabled (default), the driver fires on_unlock_file once with the offset and length of the locked region being set to -1.

Note: This setting cannot be changed within events.

SynchronousCleanupFile:   Whether the driver should perform cleanup operations synchronously.

This configuration setting specifies that the driver should wait until on_cleanup_file event returns before completing the IRP_MJ_CLEANUP request.

When this configuration setting is enabled, the driver does not complete the IRP_MJ_CLEANUP request until the user-mode processing of the on_cleanup_file event returns or a timeout occurs. By default, this configuration setting is disabled to prevent deadlocks because of some error in the user-mode processing.

Note: This setting cannot be changed within events.

TranslateDOSCharsInEnumMasks:   Whether the DOS wildcard characters should be translated during search.

In addition to * and ?, Windows uses special wildcard characters for compatibility with DOS applications and short (8.3) names. These characters are <, >, and " . Their meanings are described in MSDN and .NET reference source code as follows:

  • DOS_STAR (<) - Matches zero or more characters until encountering and matching the final dot (.) in the name. (Source code comment: "DOS_STAR matches any character except . zero or more times.")
  • DOS_QM (>) - Matches any single character or, upon encountering a period or end of name string, advances the expression to the end of the set of contiguous DOS_QMs. (Source code comment: "A DOS_DOT can match either a period, or zero characters beyond the end of name.")
  • DOS_DOT (") - Matches either a period or zero characters beyond the name string. (Source code comment: "DOS_QM is the most complicated. If the name is finished, we can match zero characters. If this name is a '.', we don't match, but look at the next expression. Otherwise, we match a single character.")

When this setting is enabled (default), the struct translates them to * and ?, but such a translation is not able to fully represent all the logic behind DOS_* wildcard characters; however, this translation is usually sufficient for end-user needs.

If your application needs to perform exact matching, disable this setting and implement handling of DOS_* wildcard characters in your application. Further explanation about the characters can be found in the MSDN article. The RtlIsNameInExpression function of Windows API may be used to perform such a matching. Note: as the explanation states, "When you do a case-insensitive search and don't provide a translation table, the name is converted to uppercase."

In FUSE on Linux, this setting is not used.

UnusedMetadataLifetime:   The time after which unused metadata cache entries are removed from the metadata cache.

This configuration setting specifies the maximum time, in milliseconds, during which items are kept in the metadata cache before they are removed. The value should be a positive number. The default value is set to 10 minutes.

Note: This setting cannot be changed within events.

UpdateFileMetadataOnOpen:   Whether the struct should request file info and update internal records during file open.

When enabled, this configuration setting tells the struct to fire the on_get_file_info event right after on_open_file and pass the obtained information to the driver, which will use the updated information for the newly opened file. The driver in turn will pass this information to the OS. By default, this configuration setting is disabled to speed up file opening.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

UpdateLastWriteTimeOnContentsChange:   Whether to fire SetFileAttributes when changes in file contents are made.

This configuration setting specifies whether the on_set_file_attributes event should be fired upon handle close when there was a change in file contents or size.

This configuration setting is enabled by default. Disable it if the application has its own logic of managing the last write time attribute (e.g., based on the completion of a backend operation).

Note: This configuration setting has no effect on LastWriteTime change operations, initiated by the OS or other processes. The setting controls only the internal logic of adjusting the last write time.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

UpdateMetadataOfOpenFiles:   Whether times and attributes returned by GetFileInfo replace existing information if a file is opened.

This configuration setting specifies what the driver should do with file times and attributes when the on_get_file_info event is fired for a file while the file is opened. When the setting is disabled (default), these values are ignored unless the driver has a specific need for them. When the setting is enabled, an event handler may update the metadata, and even if the file is open, the information in the metadata cache will be refreshed.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

UseProtectiveFSFilter:   Whether the driver should use a filesystem filter to try and prevent deadlocks.

This configuration setting specifies whether the driver should try to prevent certain kinds of deadlocks by using a filesystem filter that tracks circular access to the virtual filesystem. This may be necessary for some third-party applications and drivers to function correctly.

If this configuration setting is enabled, the driver will attempt to activate the filesystem filter and use it to prevent deadlocks caused by cyclical access (if the activation fails, the driver will simply write an entry to the system log). If this configuration setting is disabled, the filter is not used at all.

By default, this configuration setting is disabled; enable it if system deadlocks are encountered.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

UserModeFileCacheSize:   The size of the user mode file data cache.

When the file_cache property is set to fcInternalUserMode (3), this configuration setting specifies the size of the file data cache. This configuration setting cannot be used to change the size of the other file data cache implementations.

Because this configuration setting's value is specified in bytes and has a granularity of 64 KB, it must be a multiple of 65536. By default, this configuration setting is set to 0, and the driver uses a default size (currently, 300 MB; i.e., 314572800).

The user-mode file data cache's memory region is allocated on a per-process basis. Consequently, this configuration setting's value is synced between all CBFS struct instances in the current process, and all associated virtual drives (that are configured to use the user-mode file data cache) share that memory region allocated for the current process.

Please refer to the Caching topic for more information.

Note: This setting cannot be changed within events. Additionally, this configuration setting can be changed only if, for all virtual drives in the current process, at least one of the following is True:

  • The drive is not currently mounted.
  • The file_cache property is not set to fcInternalUserMode (3).

UserModeLockFirst:   Defines the order of file range locking, whether a kernel-mode lock goes before or after the LockFile event is fired.

When this setting is disabled (default), when hanlding a Lock File request, the driver locks the requested range prior to firing an event. If the user-mode locking operation is likely to fail, an application may enable this setting to change the default order and have the event fired prior to locking the range in the kernel. When user-mode locking goes first, the range remains not locked by the driver until the user-mode event handler reports success.

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

USNJournalPolicy:   How USN Journal requests should be handled.

For virtual filesystems that identify as NTFS (via file_system_name), this configuration setting specifies how USN Journal (Update Sequence Number Journal) requests should be handled. Possible values are as follows:

  • 0 - Emulate (default): Causes the driver to automatically handle USN Journal requests by emulating them internally to satisfy the OS.
  • 1 - Bypass: Causes USN Journal requests to be passed to the application via the on_fsctl event for it to handle.
  • 2 - NotSupported: The driver does not announce USN Journal support to the system.

Note: The driver does not truly emulate all journaling functionality, it simply tells the OS that the journal is empty. Applications that want more robust functionality should set this configuration setting to 1 - Bypass and implement the desired logic themselves.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

VolumeGuidName:   The GUID of the mounted volume.

Use this setting to obtain the guild of the created disk device. The value is returned as a string in the "Volume{GUID}" format, where GUID is the actual GUID.

WorkerInitialStackSize:   The initial stack size to create worker threads with.

(CBFS and FUSE structs on Windows only) This setting specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

Note: This setting cannot be changed when active is true, and it cannot be changed within events.

ZeroOriginatorBufferBeforeMapping:   Whether the allocated buffer should be zeroed before it's passed to the event handler.

When an intermediary buffer is allocated for use with the on_read_file and on_enumerate_directory events, it will contain whatever data was previously stored in that memory region, including old data leftover from other processes. This potentially can lead to sensitive information being leaked to the process that initiated the filesystem request (e.g., if the event handler does not completely fill the buffer during its execution).

To guard against the possibility of data leakage, this configuration setting can be enabled to instruct the driver to zero intermediary buffers before they are passed to event handlers. Because the zeroing of such buffers takes requires additional processing time, this configuration setting is disabled by default.

Note: This setting cannot be changed after a virtual drive is created, and it cannot be changed within events.

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a struct is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (CBFS Struct)

The struct uses Windows error codes during operation as necessary. Please refer to the Error Handling topic for more information.

Special Use Errors

21   ERROR_NOT_READY: Reported by the methods of the struct if initialize has not been called or did not succeed.
191   ERROR_INVALID_EXE_SIGNATURE: Reported by the install method when the CAB file signature cannot be validated.
400   ERROR_THREAD_MODE_ALREADY_BACKGROUND: Reported by dispatch_events when the struct is not in a single-threaded mode.
575   ERROR_APP_INIT_FAILURE: Reported by the methods of the struct if initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code.
588   ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given ProductGUID.
614   ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler.
1006   ERROR_FILE_INVALID: Event handlers may return this error code to tell the driver that the file or directory, to which the operation is related, has been changed externally. Doing this will fail the operation with the corresponding error code and tell the driver to update the information it has about the file or directory. This special handling is not available for GetFileInformation and EnumerateDirectory events.
1292   ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds.
1314   ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions.