CBFS Storage 2020 Python Edition

Questions / Feedback?

CBDrive Class

Properties   Methods   Events   Configuration Settings   Errors  

The CBDrive class lets applications create a vault, manipulate its contents, and mount it as a virtual drive.

Syntax

class cbfsstorage.CBDrive

Remarks

The CBDrive class provides a superset of the functionality offered by the CBVault class. In addition to allowing applications to create and interact with a vault directly, the CBDrive class can mount a vault as a virtual drive, allowing its contents to be accessed by the system and third-party applications.

Unlike the CBVault class, which can be used as-is, the CBDrive class requires additional deployment steps; please refer to the Driver-specific deployment topics deployment topics for more information. For more information about using CBFS Storage's many features, please refer to the extensive General Information topics.

The CBDrive class is available on Windows, Linux, and macOS platforms.

Getting Started

Each CBDrive class instance controls a single vault-based virtual drive. Applications can use multiple instances of the CBDrive class if their use-case requires that multiple vaults be mounted simultaneously.

Here's how to get up and running:

  1. Ensure that the required Prerequisites have been satisfied. On Windows, for example, this involves installing the system driver, which can be done using the install method.
  2. Call the initialize method to initialize the CBDrive class. This must be done each time the application starts (if the application is using multiple CBDrive class instances, only the first instance created should be used to call initialize).
  3. If the application is using custom compression, custom encryption, or callback mode, ensure that the appropriate event handlers have been implemented. Please refer to the linked topics for more information.
  4. Call the open_vault method to create/open a vault and mount it as a virtual drive.
  5. Create one or more Mounting Points for the virtual drive using the add_mounting_point method.
  6. At this point, the system and other processes will be able to access the vault's contents via the virtual drive.
  7. Later, the application can close the vault and unmount the associated virtual drive by calling the close_vault method.

Property List


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

access_denied_process_countThe number of records in the AccessDeniedProcess arrays.
access_denied_process_desired_accessThe kind of access granted or denied.
access_denied_process_include_childrenWhether child processes are affected.
access_denied_process_idThe Id of the target process.
access_denied_process_nameThe filename of the target process's executable.
access_granted_process_countThe number of records in the AccessGrantedProcess arrays.
access_granted_process_desired_accessThe kind of access granted or denied.
access_granted_process_include_childrenWhether child processes are affected.
access_granted_process_idThe Id of the target process.
access_granted_process_nameThe filename of the target process's executable.
activeWhether a vault has been opened and mounted as a virtual drive.
auto_compact_atThe free space percentage threshold a vault must reach to be eligible for automatic compaction.
callback_modeWhether the class should operate in callback mode.
case_sensitiveWhether the class should open a vault in case-sensitive mode.
default_file_compressionThe default compression mode to use when creating files and alternate streams.
default_file_encryptionThe default encryption mode to use when creating files and alternate streams.
default_file_passwordThe default encryption password to use when creating or opening files and alternate streams.
file_system_nameThe name of the virtual filesystem.
is_corruptedWhether the vault is corrupted.
last_write_timeThe last modification time of the vault.
logoAn application-defined text-based logo stored in the second page of a vault.
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.
page_sizeThe vault's page size.
path_separatorThe path separator character to use when returning vault paths.
possible_free_spaceThe maximum amount of free space the vault could possibly have available.
possible_sizeThe maximum size the vault could possibly be.
process_restrictions_enabledWhether process access restrictions are enabled.
read_onlyWhether the class should open a vault in read-only mode.
report_possible_sizeHow the class should report the virtual drive's size and free space to the OS.
storage_characteristicsThe characteristic flags to create the virtual drive with. (Windows only).
storage_typeThe type of virtual drive to create. (Windows only).
tagStores application-defined data specific to this instance of the class.
timeoutHow long vault events may execute before timing out. (Windows only).
unmount_on_terminationWhether the virtual drive should be unmounted if the application terminates. (Windows only).
use_access_timeWhether the class should keep track of last access times for vault items.
use_journalingWhether the class should open a vault in journaling mode.
use_system_cacheWhether the operating system's cache is used.
vault_encryptionThe whole-vault encryption mode.
vault_fileThe vault to create and/or open.
vault_free_spaceThe actual amount of free space the vault has available.
vault_passwordThe whole-vault encryption password.
vault_sizeThe actual size of the vault.
vault_size_maxThe maximum size a vault can be.
vault_size_minThe minimum size a vault can be.
vault_stateInformation about the state of the vault.

Method List


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

add_denied_processAdds a rule that prevents a process from accessing the virtual drive.
add_granted_processAdds a rule that allows a process to access the virtual drive.
add_mounting_pointAdds a mounting point for the virtual drive.
cache_file_passwordCaches an encryption password to use the next time a file or alternate stream is accessed.
check_and_repairChecks a vault's consistency and repairs it as necessary.
check_file_passwordVerifies whether a particular file password is correct.
check_vault_passwordVerifies whether a particular vault password is correct.
close_vaultCloses the vault.
compact_vaultCompacts the vault.
configSets or retrieves a configuration setting.
convert_to_drive_pathConverts a vault-local vault item path to a virtual drive file path.
convert_to_vault_pathConverts a virtual drive file path to a vault-local vault item path.
create_directoryCreates a new directory in the vault.
create_linkCreates a symbolic link to another file in the vault.
delete_fileDeletes a vault item.
delete_file_tagDeletes a file tag.
eject_volumeEjects a removable storage volume formatted with the CBFS Storage filesystem. (Windows only).
file_existsChecks whether a vault item exists.
file_matches_maskChecks whether a particular file or directory name matches the specified mask.
file_tag_existsChecks whether a file tag exists.
find_closeCloses a search operation and releases any associated resources.
find_firstSearches for the first vault item that matches the specified name and attributes.
find_first_by_querySearches for the first file or directory whose file tags match the specified query.
find_nextSearches for the next vault item that matches an ongoing search operation.
force_unmountForcefully unmounts the virtual drive associated with the specified vault. (Windows only).
format_volumeFormats a storage volume or partition with the CBFS Storage filesystem. (Windows only).
get_driver_statusRetrieves the status of the system driver.
get_file_attributesRetrieves the attributes of a vault item.
get_file_compressionRetrieves the compression mode of a file or alternate stream.
get_file_creation_timeRetrieves the creation time of a vault item.
get_file_encryptionRetrieves the encryption mode of a file or alternate stream.
get_file_last_access_timeRetrieves the last access time of a vault item.
get_file_modification_timeRetrieves the modification time of a vault item.
get_file_sizeRetrieves the size of a file or alternate stream.
get_file_tagRetrieves the binary data held by a raw file tag attached to the specified vault item.
get_file_tag_as_ansi_stringRetrieves the value of an AnsiString-typed file tag attached to the specified vault item.
get_file_tag_as_booleanRetrieves the value of a Boolean-typed file tag attached to the specified vault item.
get_file_tag_as_date_timeRetrieves the value of a DateTime-typed file tag attached to the specified vault item.
get_file_tag_as_numberRetrieves the value of a Number-typed file tag attached to the specified vault item.
get_file_tag_as_stringRetrieves the value of a String-typed file tag attached to the specified vault item.
get_file_tag_data_typeRetrieves the data type of a typed file tag attached to a specific vault item.
get_file_tag_sizeRetrieves the size of a raw file tag attached to the specified vault item.
get_module_versionRetrieves the version of a given product module.
get_originator_process_idRetrieves the Id of the process (PID) that initiated the operation.
get_originator_process_nameRetrieves the name of the process that initiated the operation.
get_originator_thread_idRetrieves the Id of the thread that initiated the operation. (Windows only).
get_originator_tokenRetrieves the security token associated with the process that initiated the operation. (Windows only).
get_search_result_attributesRetrieves the attributes of a vault item found during a search operation.
get_search_result_creation_timeRetrieves the creation time of a vault item found during a search operation.
get_search_result_full_nameRetrieves the fully-qualified name of a vault item found during a search operation.
get_search_result_last_access_timeRetrieves the last access time of a vault item found during a search operation.
get_search_result_link_destinationRetrieves the destination of a symbolic link found during a search operation.
get_search_result_metadata_sizeRetrieves the size of the metadata associated with a vault item found during a search operation.
get_search_result_modification_timeRetrieves the modification time of a vault item found during a search operation.
get_search_result_nameRetrieves the name of a vault item found during a search operation.
get_search_result_sizeRetrieves the size of a vault item found during a search operation.
initializeInitializes the class.
installInstalls (or upgrades) the product's system drivers and/or helper DLL. (Windows only).
is_cbfs_storage_vaultChecks whether a local file is a CBFS Storage vault.
is_cbfs_storage_volumeChecks whether a storage partition or volume is formatted with the CBFS Storage filesystem.
is_directory_emptyChecks whether a directory is empty.
is_icon_registeredChecks whether the specified icon is registered.
move_fileRenames or moves a vault item.
open_fileOpens a new or existing file or alternate stream in the vault.
open_file_exOpens a new or existing file or alternate stream in the vault.
open_root_dataOpens the vault's root data stream.
open_vaultOpens a new or existing vault.
open_volumeOpens a storage volume or partition formatted with the CBFS Storage filesystem as a vault. (Windows only).
register_iconRegisters an icon that can be displayed as an overlay on the virtual drive in Windows Explorer.
remove_denied_processRemoves a rule that prevents a process from accessing the virtual drive.
remove_granted_processRemoves a rule that allows a process to access the virtual drive.
remove_mounting_pointRemoves a mounting point for the virtual drive.
reset_iconResets the virtual drive's icon back to default by deselecting the active overlay icon.
resolve_linkRetrieves the destination of a symbolic link.
set_file_attributesSets the attributes of a vault item.
set_file_compressionCompresses or decompresses a file or alternate stream.
set_file_creation_timeSets the creation time of a vault item.
set_file_encryptionEncrypts, decrypts, or changes the encryption password of a file or alternate stream.
set_file_last_access_timeSets the last access time of a vault item.
set_file_modification_timeSets the modification time of a vault item.
set_file_sizeSets the size of a file or alternate stream.
set_file_tagAttaches a raw file tag with binary data to the specified vault item.
set_file_tag_as_ansi_stringAttaches an AnsiString-typed file tag to the specified vault item.
set_file_tag_as_booleanAttaches a Boolean-typed file tag to the specified vault item.
set_file_tag_as_date_timeAttaches a DateTime-typed file tag to the specified vault item.
set_file_tag_as_numberAttaches a Number-typed file tag to the specified vault item.
set_file_tag_as_stringAttaches a String-typed file tag to the specified vault item.
set_iconSelects a registered overlay icon for display on the virtual drive in Windows Explorer.
shutdown_systemShuts down or reboots the operating system.
uninstallUninstalls the product's system drivers and/or helper DLL. (Windows only).
unregister_iconUnregisters an existing overlay icon.
update_vault_encryptionEncrypts, decrypts, or changes the encryption password of the vault.

Event List


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

on_data_compressFires to compress a block of data using a custom compression algorithm.
on_data_decompressFires to decompress a block of data using a custom compression algorithm.
on_data_decryptFires to decrypt a block of data using a custom encryption implementation.
on_data_encryptFires to encrypt a block of data using a custom encryption implementation.
on_ejectedFires when the media and virtual drive have been ejected.
on_errorFires if an unhandled error occurs during an event.
on_file_password_neededFires if a password is needed to open an encrypted file.
on_hash_calculateFires to calculate a password hash using a custom hashing implementation.
on_key_deriveFires to derive an encryption key using a custom key derivation implementation.
on_progressFires to indicate the progress of long-running vault operations.
on_vault_closeFires to close a callback mode vault.
on_vault_deleteFires to delete a callback mode vault.
on_vault_flushFires to flush a callback mode vault's data out to storage.
on_vault_get_parent_sizeFires to determine how much free space is available for growing a callback mode vault.
on_vault_get_sizeFires to determine the size of a callback mode vault.
on_vault_openFires to open a new or existing callback mode vault.
on_vault_readFires to read data from a callback mode vault.
on_vault_set_sizeFires to resize a callback mode vault.
on_vault_writeFires to write data to a callback mode vault.

Configuration Settings


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

AllowMoveStreamsBetweenFilesWhether alternate streams may be moved from one file to another.
AlwaysJournalMetadataWhether filesystem structure is always saved during modification, like in Journaling mode.
AsyncDeleteStorageNotificationsWhether system broadcasts for virtual drive deletion are sent asynchronously.
AutoCompactDelayHow long a vault must remain idle before starting automatic compaction.
DefaultFileCompressionLevelThe default compression level to use when creating files and alternate streams.
LoggingEnabledWhether extended logging is enabled.
MaxNonPagedNameLengthThe maximum number of name characters to store directly within a vault item.
PageCacheSizeThe size of the in-memory vault page cache.
PartSizeThe part size used by a multipart vault.
SupportSearchIndexerSpecifies whether the driver must take additional measures to support indexing by Windows Search.
VolumeGuidNameThe GUID of the mounted volume.

Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 Python Edition - Version 20.0 [Build 8031]