CBFS Storage 2022 Python Edition
Version 22.0 [Build 8517]

CBVaultDrive Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

class cbfsstorage.CBVaultDrive

Remarks

The CBVaultDrive 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 CBVaultDrive 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 CBVaultDrive class requires additional deployment steps; please refer to the Windows-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.

Getting Started

Each CBVaultDrive class instance controls a single vault-based virtual drive. Applications can use multiple instances of the CBVaultDrive 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 CBVaultDrive class. This must be done each time the application starts (if the application is using multiple CBVaultDrive 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_access_passwordThe default encryption password to use when opening files and alternate streams.
default_file_compressionThe default compression mode to use when creating files and alternate streams.
default_file_create_passwordThe default encryption password to use when creating new files and alternate streams.
default_file_encryptionThe default encryption mode to use when creating 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.
open_files_countThe number of records in the OpenFile arrays.
open_file_nameThe name of the open file.
open_file_process_idThe Id of the process that opened the file.
open_file_process_nameThe name of the process that opened the file.
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.
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_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_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 or removes the cached password.
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_opened_files_snapshotCloses the previously-created opened files snapshot.
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 (Windows only).
convert_to_vault_pathConverts a virtual drive file path to a vault-local vault item path (Windows only).
create_directoryCreates a new directory in the vault.
create_linkCreates a symbolic link to another file in the vault.
create_opened_files_snapshotCreates a snapshot of information about files that are currently open.
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.
file_time_to_nanosecondsReturns the subsecond part of the time expressed in nanoseconds.
file_time_to_unix_timeConverts FileTime to unix time format.
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 the helper DLL (Windows only).
is_directory_emptyChecks whether a directory is empty.
is_icon_registeredChecks whether the specified icon is registered (Windows only).
is_valid_vaultChecks whether a local file is a CBFS Storage vault.
is_valid_vault_volumeChecks whether a storage partition or volume is formatted with the CBFS Storage filesystem (Windows only).
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 (Windows only).
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 (Windows only).
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 (Windows only).
shutdown_systemShuts down or reboots the operating system.
uninstallUninstalls the product's system drivers and/or helper DLL (Windows only).
unix_time_to_file_timeConverts the date/time in Unix format to Windows FileTime format.
unregister_iconUnregisters an existing overlay icon (Windows only).
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 (Windows only).
on_errorFires if an unhandled error occurs during an event.
on_file_accessFires when the OS wants to create or open a file or directory.
on_file_after_copyFires after the file has been copied during file export/import operations.
on_file_before_copyFires before the file is copied during file export/import operations.
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.
on_worker_thread_creationFires just after a new worker thread is created.
on_worker_thread_terminationFires just before a worker thread is terminated.

Config Settings


The following is a list of config 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.
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.
FireFileAccessEventWhether FileAccess event is fired.
LoggingEnabledWhether extended logging is enabled.
MaxNonPagedNameLengthThe maximum number of name characters to store directly within a vault item.
MaxWorkerThreadCountThe maximum number of worker threads to use to fire events.
MinWorkerThreadCountThe minimum number of worker threads to use to fire events.
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.
WorkerInitialStackSizeThe initial stack size to create worker threads with.

access_denied_process_count Property

The number of records in the AccessDeniedProcess arrays.

Syntax

def get_access_denied_process_count() -> int: ...

access_denied_process_count = property(get_access_denied_process_count, None)

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.

access_denied_process_desired_access Property

The kind of access granted or denied.

Syntax

def get_access_denied_process_desired_access(access_denied_process_index: int) -> int: ...

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 access_denied_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_denied_process_count property.

This property is read-only.

access_denied_process_include_children Property

Whether child processes are affected.

Syntax

def get_access_denied_process_include_children(access_denied_process_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether child processes are affected.

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

The access_denied_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_denied_process_count property.

This property is read-only.

access_denied_process_id Property

The Id of the target process.

Syntax

def get_access_denied_process_id(access_denied_process_index: int) -> int: ...

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 access_denied_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_denied_process_count property.

This property is read-only.

access_denied_process_name Property

The filename of the target process's executable.

Syntax

def get_access_denied_process_name(access_denied_process_index: int) -> str: ...

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename 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 access_denied_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_denied_process_count property.

This property is read-only.

access_granted_process_count Property

The number of records in the AccessGrantedProcess arrays.

Syntax

def get_access_granted_process_count() -> int: ...

access_granted_process_count = property(get_access_granted_process_count, None)

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.

access_granted_process_desired_access Property

The kind of access granted or denied.

Syntax

def get_access_granted_process_desired_access(access_granted_process_index: int) -> int: ...

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 access_granted_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_granted_process_count property.

This property is read-only.

access_granted_process_include_children Property

Whether child processes are affected.

Syntax

def get_access_granted_process_include_children(access_granted_process_index: int) -> bool: ...

Default Value

FALSE

Remarks

Whether child processes are affected.

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

The access_granted_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_granted_process_count property.

This property is read-only.

access_granted_process_id Property

The Id of the target process.

Syntax

def get_access_granted_process_id(access_granted_process_index: int) -> int: ...

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 access_granted_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_granted_process_count property.

This property is read-only.

access_granted_process_name Property

The filename of the target process's executable.

Syntax

def get_access_granted_process_name(access_granted_process_index: int) -> str: ...

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename 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 access_granted_process_index parameter specifies the index of the item in the array. The size of the array is controlled by the access_granted_process_count property.

This property is read-only.

active Property

Whether a vault has been opened and mounted as a virtual drive.

Syntax

def get_active() -> bool: ...

active = property(get_active, None)

Default Value

FALSE

Remarks

This property reflects whether the class has opened a vault and mounted a virtual drive for it; it will be True once the open_vault or open_volume method has been called successfully.

This property is read-only.

auto_compact_at Property

The free space percentage threshold a vault must reach to be eligible for automatic compaction.

Syntax

def get_auto_compact_at() -> int: ...
def set_auto_compact_at(value: int) -> None: ...

auto_compact_at = property(get_auto_compact_at, set_auto_compact_at)

Default Value

25

Remarks

This property specifies the percentage of free space a vault must have, at minimum, in order for it to be eligible for automatic vault compaction. An eligible vault may be compacted automatically in the background at any time. Please refer to the compact_vault method for more information about the compacting process itself.

To help guard against excessive automatic compaction operations, applications can set the AutoCompactDelay configuration setting to a non-zero value. Alternatively, this property can be set to 0 to disable automatic compaction completely.

A vault opened in read_only mode will never be compacted, regardless of this property's value.

Note: This property cannot be changed within events.

callback_mode Property

Whether the class should operate in callback mode.

Syntax

def get_callback_mode() -> bool: ...
def set_callback_mode(value: bool) -> None: ...

callback_mode = property(get_callback_mode, set_callback_mode)

Default Value

FALSE

Remarks

This property specifies whether the class should operate in callback mode, causing all vault access to be performed via the events listed below. Please refer to the Callback Mode topic for more information.

When this property is enabled, the following events must all be implemented in order for the class to function correctly:

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

case_sensitive Property

Whether the class should open a vault in case-sensitive mode.

Syntax

def get_case_sensitive() -> bool: ...
def set_case_sensitive(value: bool) -> None: ...

case_sensitive = property(get_case_sensitive, set_case_sensitive)

Default Value

FALSE

Remarks

This property specifies whether the class should open a vault in case-sensitive mode. Enabling this property causes all file, directory, symbolic link, alternate stream, and file tag names to be treated as case-sensitive.

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

default_file_access_password Property

The default encryption password to use when opening files and alternate streams.

Syntax

def get_default_file_access_password() -> str: ...
def set_default_file_access_password(value: str) -> None: ...

default_file_access_password = property(get_default_file_access_password, set_default_file_access_password)

Default Value

""

Remarks

This property specifies the default encryption password that the class should use when opening files and alternate streams.

Please refer to the Encryption topic for more information.

As an alternative to using this property, applications may call the cache_file_password method (before a file is opened) to specify a one-time-use password, or specify file encryption passwords dynamically using the on_file_password_needed event.

default_file_compression Property

The default compression mode to use when creating files and alternate streams.

Syntax

def get_default_file_compression() -> int: ...
def set_default_file_compression(value: int) -> None: ...

default_file_compression = property(get_default_file_compression, set_default_file_compression)

Default Value

0

Remarks

This property specifies the default compression mode that the class should use when creating files and alternate streams. Valid values are:

VAULT_CM_NONE0Don't use compression.

VAULT_CM_DEFAULT1Use default compression (zlib).

VAULT_CM_CUSTOM2Use event-based custom compression.

Compression level is not used.

VAULT_CM_ZLIB3Use zlib compression.

Valid compression levels are 1-9.

VAULT_CM_RLE4Use RLE compression.

Compression level is not used.

Applications that use custom compression must the on_data_compress and on_data_decompress events. Please refer to the Compression topic for more information.

Applications can also specify a default compression level using the DefaultFileCompressionLevel configuration setting, if desired.

default_file_create_password Property

The default encryption password to use when creating new files and alternate streams.

Syntax

def get_default_file_create_password() -> str: ...
def set_default_file_create_password(value: str) -> None: ...

default_file_create_password = property(get_default_file_create_password, set_default_file_create_password)

Default Value

""

Remarks

This property specifies the default encryption password that the class should use when creating new files and alternate streams.

Please refer to the Encryption topic for more information.

default_file_encryption Property

The default encryption mode to use when creating files and alternate streams.

Syntax

def get_default_file_encryption() -> int: ...
def set_default_file_encryption(value: int) -> None: ...

default_file_encryption = property(get_default_file_encryption, set_default_file_encryption)

Default Value

0

Remarks

This property specifies the default encryption mode that the class should use when creating files and alternate streams. Valid values are:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

Applications that set this property to a value other than VAULT_EM_NONE (the default) should also specify a default encryption password using the default_file_create_password property.

file_system_name Property

The name of the virtual filesystem.

Syntax

def get_file_system_name() -> str: ...
def set_file_system_name(value: str) -> None: ...

file_system_name = property(get_file_system_name, set_file_system_name)

Default Value

"FAT32"

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 cannot be changed within events.

is_corrupted Property

Whether the vault is corrupted.

Syntax

def get_is_corrupted() -> bool: ...

is_corrupted = property(get_is_corrupted, None)

Default Value

FALSE

Remarks

This property reflects whether the currently-open vault is corrupted, as indicated by the presence of the VAULT_ST_CORRUPTED flag in the vault_state property.

The VAULT_ST_CORRUPTED flag is set automatically anytime the class detects that a vault's integrity has been compromised. Calling the check_and_repair method for a corrupted vault will clear the flag.

This property is read-only.

last_write_time Property

The last modification time of the vault.

Syntax

def get_last_write_time() -> datetime.datetime: ...

last_write_time = property(get_last_write_time, None)

Default Value

0

Remarks

This property reflects the vault's last modification time, specified in UTC.

This property is read-only.

logo Property

An application-defined text-based logo stored in the second page of a vault.

Syntax

def get_logo() -> str: ...
def set_logo(value: str) -> None: ...

logo = property(get_logo, set_logo)

Default Value

"CBFS Vault"

Remarks

This property is used to control a vault's logo, which is a UTF-16LE string stored in the second page of a vault. A vault's logo is visible to anyone who inspects its raw data, and can thus be used to provide information about the vault itself.

Vault logos can be up to 127 characters long (not including the null terminator).

Note: This property cannot be changed within events.

mounting_point_count Property

The number of records in the MountingPoint arrays.

Syntax

def get_mounting_point_count() -> int: ...

mounting_point_count = property(get_mounting_point_count, None)

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.

mounting_point_authentication_id Property

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

Syntax

def get_mounting_point_authentication_id(mounting_point_index: int) -> int: ...

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 mounting_point_index parameter specifies the index of the item in the array. The size of the array is controlled by the mounting_point_count property.

This property is read-only.

mounting_point_flags Property

The flags used to create the mounting point.

Syntax

def get_mounting_point_flags(mounting_point_index: int) -> int: ...

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.

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 Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

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 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 class 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 class 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 class that it should assign the drive letter automatically.

When this flag is specified, the class 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 mounting_point_index parameter specifies the index of the item in the array. The size of the array is controlled by the mounting_point_count property.

This property is read-only.

mounting_point_name Property

The mounting point name.

Syntax

def get_mounting_point_name(mounting_point_index: int) -> str: ...

Default Value

""

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 mounting_point_index parameter specifies the index of the item in the array. The size of the array is controlled by the mounting_point_count property.

This property is read-only.

open_files_count Property

The number of records in the OpenFile arrays.

Syntax

def get_open_files_count() -> int: ...

open_files_count = property(get_open_files_count, None)

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.

open_file_name Property

The name of the open file.

Syntax

def get_open_file_name(open_file_index: int) -> str: ...

Default Value

""

Remarks

The name of the open file.

This property reflects the name of the open file.

The open_file_index parameter specifies the index of the item in the array. The size of the array is controlled by the open_files_count property.

This property is read-only.

open_file_process_id Property

The Id of the process that opened the file.

Syntax

def get_open_file_process_id(open_file_index: int) -> int: ...

Default Value

0

Remarks

The Id of the process that opened the file.

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

The open_file_index parameter specifies the index of the item in the array. The size of the array is controlled by the open_files_count property.

This property is read-only.

open_file_process_name Property

The name of the process that opened the file.

Syntax

def get_open_file_process_name(open_file_index: int) -> str: ...

Default Value

""

Remarks

The name of the process that opened the file.

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

The open_file_index parameter specifies the index of the item in the array. The size of the array is controlled by the open_files_count property.

This property is read-only.

page_size Property

The vault's page size.

Syntax

def get_page_size() -> int: ...
def set_page_size(value: int) -> None: ...

page_size = property(get_page_size, set_page_size)

Default Value

4096

Remarks

This property controls the page size used when creating new vaults, and reflects the page size of the currently-open vault. Valid values are 256 through 65536 bytes (inclusive).

A vault's page size is permanent, it cannot be changed after the vault is created. Please refer to the Vaults topic for more information.

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

path_separator Property

The path separator character to use when returning vault paths.

Syntax

def get_path_separator() -> int: ...
def set_path_separator(value: int) -> None: ...

path_separator = property(get_path_separator, set_path_separator)

Default Value

92

Remarks

This property specifies the path separator character that the class APIs should use when returning a vault path. Valid values are:

VAULT_PSC_BACKSLASH92Backslash ('\').

Windows path separator.

VAULT_PSC_SLASH47Forward slash ('/').

Unix-style path separator.

Note that this property is just a convenience; applications are free to use either of the above characters as path separators when passing path strings to the class's APIs.

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

possible_free_space Property

The maximum amount of free space the vault could possibly have available.

Syntax

def get_possible_free_space() -> int: ...

possible_free_space = property(get_possible_free_space, None)

Default Value

0

Remarks

This property reflects the maximum amount of free space, in bytes, that the vault could possibly have available. That is, the amount of free space that would be available if the vault automatically grew to its maximum possible_size right now, without any additional data being written to it. Therefore:

In both cases, parent_free_space is the amount of free space available for the vault to use for automatic growth. For a file-based vault, this is the total amount of free space on the disk where the vault's storage file (i.e., vault_file) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides via the on_vault_get_parent_size event.

Please refer to the Vault Size topic for more information.

This property is read-only.

possible_size Property

The maximum size the vault could possibly be.

Syntax

def get_possible_size() -> int: ...

possible_size = property(get_possible_size, None)

Default Value

0

Remarks

This property reflects the maximum size, in bytes, that the vault could possibly be. That is, the size that the vault would be if it automatically grew as much as possible right now, without any additional data being written to it. Therefore:

In the former case, parent_free_space is the amount of free space available for the vault to use for automatic growth. For a file-based vault, this is the total amount of free space on the disk where the vault's storage file (i.e., vault_file) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides via the on_vault_get_parent_size event.

Please refer to the vault_size topic for more information.

This property is read-only.

process_restrictions_enabled Property

Whether process access restrictions are enabled.

Syntax

def get_process_restrictions_enabled() -> bool: ...
def set_process_restrictions_enabled(value: bool) -> None: ...

process_restrictions_enabled = property(get_process_restrictions_enabled, set_process_restrictions_enabled)

Default Value

FALSE

Remarks

This property controls whether the class 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 class to enforce across the entire virtual drive.

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.

read_only Property

Whether the class should open a vault in read-only mode.

Syntax

def get_read_only() -> bool: ...
def set_read_only(value: bool) -> None: ...

read_only = property(get_read_only, set_read_only)

Default Value

FALSE

Remarks

This property specifies whether the class should open a vault in read-only mode. When a vault is open in read-only mode, the following restrictions apply:

  • No new vault items (files, directories, symbolic links, and alternate streams) may be created.
  • No existing vault items may be modified, renamed, moved, or deleted. (This includes updating access times.)
  • The vault cannot be resized or compacted (automatically or explicitly).
  • Vault corruption cannot be repaired using check_and_repair.
(Note that this list may not necessarily be exhaustive.)

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

report_possible_size Property

How the class should report the virtual drive's size and free space to the OS.

Syntax

def get_report_possible_size() -> bool: ...
def set_report_possible_size(value: bool) -> None: ...

report_possible_size = property(get_report_possible_size, set_report_possible_size)

Default Value

TRUE

Remarks

This property controls which pair of values the class should use when reporting the virtual drive's size and free space to the OS.

When this property is enabled (default), the class will use the values of the possible_size and possible_free_space properties. When this property is disabled, the class will use the values of the vault_size and possible_size properties.

To ensure correct operation, it is recommended that applications keep this property enabled, unless a vault's size has been fixed by setting the vault_size_min and vault_size_max properties equal to each other.

Please refer to the documentation of the properties mentioned above, as well as the Vault Size topic, for more information.

Note: This property cannot be changed within events.

serialize_events Property

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

Syntax

def get_serialize_events() -> int: ...
def set_serialize_events(value: int) -> None: ...

serialize_events = property(get_serialize_events, set_serialize_events)

Default Value

0

Remarks

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

0 (seOnMultipleThreads) The class 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 class fires events in the context of one background worker thread.

Please refer to the Threading and Concurrency topic for more information.

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

storage_characteristics Property

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

Syntax

def get_storage_characteristics() -> int: ...
def set_storage_characteristics(value: int) -> None: ...

storage_characteristics = property(get_storage_characteristics, set_storage_characteristics)

Default Value

16

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 cannot be changed within events.

storage_guid Property

The GUID to create the virtual drive with.

Syntax

def get_storage_guid() -> str: ...
def set_storage_guid(value: str) -> None: ...

storage_guid = property(get_storage_guid, set_storage_guid)

Default Value

""

Remarks

When the storage_type property is set to STGT_DISK_PNP, 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 can be left empty.

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.

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

storage_type Property

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

Syntax

def get_storage_type() -> int: ...
def set_storage_type(value: int) -> None: ...

storage_type = property(get_storage_type, set_storage_type)

Default Value

0

Remarks

This property specifies what type of virtual drive should be created. Windows 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 Storage 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 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.

tag Property

Stores application-defined data specific to this instance of the class.

Syntax

def get_tag() -> int: ...
def set_tag(value: int) -> None: ...

tag = property(get_tag, set_tag)

Default Value

0

Remarks

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

timeout Property

How long vault events may execute before timing out (Windows only).

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

0

Remarks

When an application is operating in Callback Mode, this property specifies how long the Vault* events may execute before timing out.

When this property is set to a non-zero value, and a Vault* event executes long enough for its timeout to expire, the driver cancels the underlying request by reporting an error to the OS. The tardy event still runs to completion, but any results it returns once finished are ignored since the underlying request has already been handled.

Setting this property to 0 disables event timeouts, which allows Vault* events to take as long as necessary to execute.

Note: This property cannot be changed within events.

unmount_on_termination Property

Whether the virtual drive should be unmounted if the application terminates (Windows only).

Syntax

def get_unmount_on_termination() -> bool: ...
def set_unmount_on_termination(value: bool) -> None: ...

unmount_on_termination = property(get_unmount_on_termination, set_unmount_on_termination)

Default Value

TRUE

Remarks

This property specifies whether the CBFS Storage driver should automatically unmount the virtual drive (closing all handles and other resources associated with it) if the application terminates.

If this property is disabled, applications may need to call the force_unmount method after a crash (if there was a file-based vault open and mounted as a virtual drive when the crash occurred).

Note: This property cannot be disabled on non-Windows platforms.

use_access_time Property

Whether the class should keep track of last access times for vault items.

Syntax

def get_use_access_time() -> bool: ...
def set_use_access_time(value: bool) -> None: ...

use_access_time = property(get_use_access_time, set_use_access_time)

Default Value

FALSE

Remarks

This property specifies whether the class should update the last access time for vault items (files, directories, symbolic links, and alternate streams) every time they're accessed.

Note that keeping track of access times will slow down operations.

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

use_system_cache Property

Whether the operating system's cache is used.

Syntax

def get_use_system_cache() -> bool: ...
def set_use_system_cache(value: bool) -> None: ...

use_system_cache = property(get_use_system_cache, set_use_system_cache)

Default Value

TRUE

Remarks

This property specifies whether the operating system's cache should be used. Use of the OS cache affects the speed of various vault operations; however, note that the exact effects depend on the type of operation as well as the data sizes involved.

For the CBVAULT class, disabling this property will cause a vault's storage file (specified by the vault_file property) to be opened with FILE_FLAG_NO_BUFFERING (on Windows) or F_NOCACHE (on Linux/macOS). This also applies for the CBVaultDrive class on Linux and macOS.

For the CBVaultDrive class on Windows, a vault's storage file is always opened with FILE_FLAG_NO_BUFFERING regardless of how this property is set; disabling this property prevents the system cache from being used to cache files on the virtual drive. This may be necessary in certain situations in order to prevent BSODs. Please refer to Microsoft's File Caching article for more information about the system file cache.

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

vault_encryption Property

The whole-vault encryption mode.

Syntax

def get_vault_encryption() -> int: ...
def set_vault_encryption(value: int) -> None: ...

vault_encryption = property(get_vault_encryption, set_vault_encryption)

Default Value

0

Remarks

This property controls the whole-vault encryption mode used when creating new vaults, and reflects the whole-vault encryption mode of the currently-open vault. Valid values are:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

To create a new vault with whole-vault encryption enabled, the vault_password property must be set as well.

When an existing vault is opened, the class updates vault_encryption automatically based on the detected whole-vault encryption mode. If the vault is encrypted, the class will attempt to access it using the password specified by vault_password. If vault_password is incorrect, the attempt will fail and the vault will not be opened.

The vault_encryption and vault_password properties cannot be used to change an open vault's whole-vault encryption mode or password; use the update_vault_encryption method.

Please refer to the Encryption topic for more information.

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

vault_file Property

The vault to create and/or open.

Syntax

def get_vault_file() -> str: ...
def set_vault_file(value: str) -> None: ...

vault_file = property(get_vault_file, set_vault_file)

Default Value

""

Remarks

This property specifies the vault to create and/or open when the open_vault method is called.

When the callback_mode property is disabled (default), this property specifies the vault storage file to create/open, and must be set to a fully-qualified file path formatted according to OS conventions.

When the callback_mode property is enabled, this property is only used to populate the Vault parameter of the on_vault_open, on_vault_get_parent_size, and on_vault_delete events; and can be set to any application-defined value. Please refer to the Callback Mode topic for more information.

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

vault_free_space Property

The actual amount of free space the vault has available.

Syntax

def get_vault_free_space() -> int: ...

vault_free_space = property(get_vault_free_space, None)

Default Value

0

Remarks

This property reflects the actual amount of free space, in bytes, that the vault has available currently. A vault's actual free space is based on its actual size, which is reflected by the vault_size property.

Applications can also determine the maximum amount of free space the vault could possibly have by querying the possible_free_space property; please refer to its documentation, as well as the Vault Size topic, for more information.

This property is read-only.

vault_password Property

The whole-vault encryption password.

Syntax

def get_vault_password() -> str: ...
def set_vault_password(value: str) -> None: ...

vault_password = property(get_vault_password, set_vault_password)

Default Value

""

Remarks

This property specifies the whole-vault encryption password to use when creating new vaults and opening existing vaults.

To create a new vault with whole-vault encryption enabled, the vault_encryption property must be set as well.

When an existing vault is opened, the class updates vault_encryption automatically based on the detected whole-vault encryption mode. If the vault is encrypted, the class will attempt to access it using the password specified by vault_password. If vault_password is incorrect, the attempt will fail and the vault will not be opened.

The vault_encryption and vault_password properties cannot be used to change an open vault's whole-vault encryption mode or password; use the update_vault_encryption method.

Please refer to the Encryption topic for more information.

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

vault_size Property

The actual size of the vault.

Syntax

def get_vault_size() -> int: ...
def set_vault_size(value: int) -> None: ...

vault_size = property(get_vault_size, set_vault_size)

Default Value

0

Remarks

This property specifies the actual size of the vault, in bytes.

Applications may use this property to explicitly resize a vault, keeping in mind the following:

  • A vault cannot shrink more than its available free space allows (i.e., not by more than vault_free_space bytes).
  • A vault cannot shrink beyond vault_size_min bytes.
  • If vault_size_max is not 0 (unlimited), a vault cannot grow beyond vault_size_max bytes.
  • If a vault grows enough to reach/exceed its auto_compact_at threshold, it will automatically shrink again when the next automatic compaction occurs.

Applications can also determine the maximum size a vault could possibly be by querying the possible_size property. Please refer to the Vault Size topic for more information.

Note: This property can only be changed when active is True, and cannot be changed within events.

vault_size_max Property

The maximum size a vault can be.

Syntax

def get_vault_size_max() -> int: ...
def set_vault_size_max(value: int) -> None: ...

vault_size_max = property(get_vault_size_max, set_vault_size_max)

Default Value

0

Remarks

This property specifies the maximum size, in bytes, that a vault can be. This property must be set to 0 (unlimited), or a number greater than or equal to 8 * page_size or vault_size_min (whichever is greater).

The limit imposed by this property, if any, applies to both explicit growth of a vault via the vault_size property, and implicit growth of a vault due to storage load. Please refer to the Vault Size topic for more information.

Note: This property cannot be changed within events.

vault_size_min Property

The minimum size a vault can be.

Syntax

def get_vault_size_min() -> int: ...
def set_vault_size_min(value: int) -> None: ...

vault_size_min = property(get_vault_size_min, set_vault_size_min)

Default Value

0

Remarks

This property specifies the minimum size, in bytes, that a vault can be. This property's value must be less than or equal to vault_size_max, unless vault_size_max is set to 0 (unlimited).

The limit imposed by this property applies to both explicit shrinking of a vault via the vault_size property or the compact_vault method, and implicit shrinking of a vault via automatic compaction. Please refer to the Vault Size topic for more information.

Note: This property cannot be changed within events.

vault_state Property

Information about the state of the vault.

Syntax

def get_vault_state() -> int: ...

vault_state = property(get_vault_state, None)

Default Value

0

Remarks

This property reflects the current state of the vault; its value consists of one or more of the following flags, OR'd together:

VAULT_ST_FIXED_SIZE0x00000001The vault is fixed-size.

VAULT_ST_READ_ONLY0x00000002The vault was opened in read-only mode.

Please refer to the read_only property for more information.

VAULT_ST_CORRUPTED0x00000004The vault is corrupted.

Applications can use the check_and_repair method to try to repair vault corruption. Please refer to the Vault Corruption topic for more information.

VAULT_ST_TRANSACTIONS_USED0x00000008The vault was opened in journaling mode.

Please refer to the use_journaling property for more information.

VAULT_ST_ACCESS_TIME_USED0x00000010Last access times are being tracked.

Please refer to the use_access_time property for more information.

VAULT_ST_ENCRYPTED0x00000020The vault is encrypted with whole-vault encryption.

Please refer to the Encryption topic for more information.

VAULT_ST_VALID_PASSWORD_SET0x00000040The correct whole-vault encryption password has been provided.

Please refer to the Encryption topic for more information.

VAULT_ST_PHYSICAL_VOLUME0x00000080The vault is backed by a storage volume or partition formatted with the CBFS Storage filesystem.

This flag only applies when using the CBVaultDrive class.

VAULT_ST_PARTED0x00000100The vault's contents are split across multiple files on disk.

Please refer to the Multipart Vaults topic for more information.

This property is read-only.

add_denied_process Method

Adds a rule that prevents a process from accessing the virtual drive.

Syntax

def add_denied_process(process_file_name: str, process_id: int, child_processes: bool, desired_access: int) -> None: ...

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 filename 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 only be called when active is True, and 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

Adds a rule that allows a process to access the virtual drive.

Syntax

def add_granted_process(process_file_name: str, process_id: int, child_processes: bool, desired_access: int) -> None: ...

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 filename 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 only be called when active is True, and 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

Adds a mounting point for the virtual drive.

Syntax

def add_mounting_point(mounting_point: str, flags: int, authentication_id: int) -> None: ...

Remarks

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

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:

Windows:

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.

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 Explorer will not correctly recognize the "network" drive.

This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER.

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 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 class 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 class 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 class that it should assign the drive letter automatically.

When this flag is specified, the class 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.

Linux and macOS:

STGMP_LOCAL_FUSE0x10000000Creates a mounting point, accessible only for current user.

If this flag is not passed, the "-oallow_other" option of FUSE is used.

STGMP_SYMLINK_DEBUG0x40000000Prints debug messages to stderr

The messages generated by the class are printed.

STGMP_SYMLINK_SYSTEM_DEBUG0x20000000Prints debug messages generated by the FUSE library to stderr

STGMP_NETWORK_MACOS0x00040000Create a network mounting point (macOS only).

If this flag is not passed, the "-olocal" option of macFUSE is used.

For more information about the "-olocal" option of macFUSE, please refer to the macFUSE FAQ.

Windows:

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.

Linux, macOS: The AuthenticationId parameter is ignored.

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 and Mounting Points

When applications call the open_vault (CBVaultDrive) or create_vault method, the specified vault is opened and used to create and mount a virtual drive. This virtual drive is created without a drive letter.

To add a drive letter for the virtual drive, applications have to call the add_mounting_point method. Once a drive letter is assigned, the virtual drive will be visible to the system and other applications, allowing them to start accessing its files and directories.

cache_file_password Method

Caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password.

Syntax

def cache_file_password(file_name: str, password: str, ttl_in_cache: int, remove_from_cache: bool) -> None: ...

Remarks

This method temporarily caches an encryption password so that it can be used the next time the file or alternate stream specified by FileName is accessed.

The value passed for FileName must be a vault-local absolute path.

The Password parameter specifies the password to cache. It must match the one last used to encrypt the specified file or the alternate stream, otherwise this method raises an exception.

The specified password is automatically removed from the cache as soon as one of the following things occur:

  • The password is used to access the file or alternate stream and the value of the TTLInCache parameter is 0.
  • The password for the file or alternate stream is changed.
  • The vault is closed.
  • The timeout expires.

To remove the previously cached password from the cache, set the RemoveFromCache parameter to True. When it is set so, the value of the Password parameter is ignored.

The TTLInCache parameter specifies time to seconds that the class keeps the password in the internal cache to reduce the number of requests for a password. The value of 0 tells the class to discard the password after the first use.

As an alternative to using this method, applications can provide a default file encryption password using the default_file_access_password property, and/or provide such passwords dynamically using the on_file_password_needed event.

Note: This method can only be called when active is True.

check_and_repair Method

Checks a vault's consistency and repairs it as necessary.

Syntax

def check_and_repair(flags: int) -> None: ...

Remarks

This method checks the consistency of a vault and attempts to repair it as necessary.

Applications should call this method if a vault has become corrupted (i.e., if the is_corrupted property is True, or if a vault operation fails with a "Vault Corrupted" error). Be sure to make a vault backup before calling this method, as its repair efforts may cause data loss in cases of severe corruption. Please refer to the Vault Corruption topic for more information.

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

VAULT_CR_CHECK_ONLY0x00000001Check only, don't attempt any repairs.

VAULT_CR_CHECK_ALL_PAGES0x00000002Check all vault pages, including empty ones.

(When this flag is not present, only the vault pages which are marked as occupied are checked.)

Note: This method cannot be called when active is True, and cannot be called within events.

check_file_password Method

Verifies whether a particular file password is correct.

Syntax

def check_file_password(file_name: str, password: str) -> bool: ...

Remarks

This method verifies whether the specified Password matches the one used to encrypt the file or alternate stream specified by FileName. If the password is correct, this method returns True; otherwise it returns False.

The value passed for FileName must be a vault-local absolute path.

Please refer to the Encryption topic for more information.

Note: This method can only be called when active is True.

check_vault_password Method

Verifies whether a particular vault password is correct.

Syntax

def check_vault_password(password: str) -> bool: ...

Remarks

This method verifies whether the specified Password matches the one used to encrypt the vault. If the password is correct, this method returns True; otherwise it returns False.

Please refer to the Encryption topic for more information.

Note: This method can only be called when active is True.

close_opened_files_snapshot Method

Closes the previously-created opened files snapshot.

Syntax

def close_opened_files_snapshot() -> None: ...

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.

close_vault Method

Closes the vault.

Syntax

def close_vault(force: bool) -> None: ...

Remarks

This method closes the currently-open vault.

For CBVaultDrive, the Force parameter specifies whether to forcefully close any file or directory handles open currently. If Force is False, this method will fail if any handles are currently open.

Note: This method can only be called when active is True.

compact_vault Method

Compacts the vault.

Syntax

def compact_vault() -> bool: ...

Remarks

This method triggers vault compaction, a process that shrinks a vault's overall size by truncating its free space. If the compacting operation completes successfully, this method returns True; otherwise it returns False.

Compaction involves physically moving a vault's occupied pages to the beginning of the vault, and then truncating the unoccupied pages from the end of the vault. The runtime of a compacting operation depends on a number of factors, and it's possible for it to be interrupted by other vault operations.

Compaction occurs automatically when the vault's free space percentage exceeds the threshold specified by the auto_compact_at property. Applications can also use the AutoCompactDelay configuration setting to add a delay to the automatic compaction trigger.

Note that a vault opened in read_only mode cannot be compacted, automatically or explicitly.

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

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, 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.

convert_to_drive_path Method

Converts a vault-local vault item path to a virtual drive file path (Windows only).

Syntax

def convert_to_drive_path(vault_file_path: str) -> str: ...

Remarks

This method returns a virtual drive file path that corresponds to the vault item (file, directory, or symbolic link) specified by VaultFilePath.

The value passed for VaultFilePath must be a vault-local absolute path.

The value returned by this method is a fully-qualified file path formatted according to OS conventions, suitable for passing to system file APIs and/or external applications.

Note: This method can only be called when active is True.

convert_to_vault_path Method

Converts a virtual drive file path to a vault-local vault item path (Windows only).

Syntax

def convert_to_vault_path(virtual_file_path: str) -> str: ...

Remarks

This method returns the vault-local absolute path of the vault item (file, directory, or symbolic link) that corresponds to the virtual drive file path specified by VirtualFilePath.

The value passed for VirtualFilePath must be a fully-qualified file path formatted according to OS conventions.

The value returned by this method can be used to access the corresponding vault item using the class APIs.

Note: This method can only be called when active is True.

create_directory Method

Creates a new directory in the vault.

Syntax

def create_directory(directory: str, create_parents: bool) -> None: ...

Remarks

This method creates a new directory in the vault at the path specified by Directory.

The value passed for Directory must be a vault-local absolute path.

The CreateParents parameter specifies whether non-existent parent directories in the specified path should be created as well. If this parameter is False, and one or more parent directories are missing, this method raises an exception.

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

create_link Method

Creates a symbolic link to another file in the vault.

Syntax

def create_link(link_name: str, destination_name: str) -> None: ...

Remarks

This method creates a new symbolic link named LinkName that points to the file specified by DestinationName.

The value passed for LinkName must be a vault-local absolute path. The value passed for DestinationName must also be a vault-local path, but may be absolute or relative to LinkName.

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

create_opened_files_snapshot Method

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

Syntax

def create_opened_files_snapshot() -> None: ...

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.

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 class will attempt to close it before creating a new one.

Note: This method can only be called when active is True, and 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.

delete_file Method

Deletes a vault item.

Syntax

def delete_file(file_name: str) -> None: ...

Remarks

This method deletes the vault item (file, directory, symbolic link, or alternate stream) specified by FileName from the vault.

The value passed for FileName must be a vault-local absolute path.

Please note that:

  • When a file is deleted, any alternate streams it contains are deleted as well.
  • Directories must be empty to be deleted, otherwise this method raises an exception. Use the is_directory_empty method to check whether a directory is empty.
  • Deleting a symbolic link only deletes the link itself, not the file it points to.

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

delete_file_tag Method

Deletes a file tag.

Syntax

def delete_file_tag(file_name: str, tag_id: int, tag_name: str) -> None: ...

Remarks

This method deletes the file tag identified by TagId or TagName from the file, directory, or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

To delete a raw file tag, pass its Id for TagId and pass empty string for TagName. To delete a typed file tag, pass its name for TagName and pass 0 for TagId. If values are provided for both TagId and TagName, this method raises an exception.

Please refer to the File Tags topic for more information.

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

eject_volume Method

Ejects a removable storage volume formatted with the CBFS Storage filesystem (Windows only).

Syntax

def eject_volume(force: bool) -> None: ...

Remarks

If the currently-open vault resides on a removable storage volume formatted with the CBFS Storage filesystem (i.e., if the vault was opened using the open_volume method), this method can be used to eject it. If this method is successful, the vault is closed, and the volume is made available for removal (similar to how the "Eject" functionality provided by Windows Explorer works).

The Force parameter specifies whether the removable storage volume should be forcefully ejected. If Force is False, this method will fail if the vault is currently in use by the system or other applications.

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

file_exists Method

Checks whether a vault item exists.

Syntax

def file_exists(file_name: str) -> bool: ...

Remarks

This method checks whether a vault item (file, directory, symbolic link, or alternate stream) with the specified FileName exists in the vault. If the specified vault item exists, this method returns True; otherwise it returns False.

The value passed for FileName must be a vault-local absolute path.

Note: This method can only be called when active is True.

file_matches_mask Method

Checks whether a particular file or directory name matches the specified mask.

Syntax

def file_matches_mask(mask: str, file_name: str, case_sensitive: bool) -> bool: ...

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 don't provide a translation table, the name is converted to uppercase."

file_tag_exists Method

Checks whether a file tag exists.

Syntax

def file_tag_exists(file_name: str, tag_id: int, tag_name: str) -> bool: ...

Remarks

This method checks whether a file tag with the specified TagId or TagName is attached to the file, directory, or alternate stream specified by FileName. If the specified file tag exists, this method returns True; otherwise it returns False.

The value passed for FileName must be a vault-local absolute path.

To check for a raw file tag, pass its Id for TagId and pass empty string for TagName. To check for a typed file tag, pass its name for TagName and pass 0 for TagId. If values are provided for both TagId and TagName, this method raises an exception.

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

file_time_to_nanoseconds Method

Returns the subsecond part of the time expressed in nanoseconds.

Syntax

def file_time_to_nanoseconds(file_time: datetime.datetime) -> int: ...

Remarks

Use this method to obtain the subsecond part of the FileTime value, expressed in nanoseconds.

file_time_to_unix_time Method

Converts FileTime to unix time format.

Syntax

def file_time_to_unix_time(file_time: datetime.datetime) -> int: ...

Remarks

Use this method to convert the FileTime value to Unix time format. The subsecond part of the value is not preserved; to obtain it, use the file_time_to_nanoseconds method.

find_close Method

Closes a search operation and releases any associated resources.

Syntax

def find_close(search_id: int) -> None: ...

Remarks

This method closes the search operation identified by SearchId, releasing any previously-allocated resources associated with it.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

Note: This method can only be called when active is True.

find_first Method

Searches for the first vault item that matches the specified name and attributes.

Syntax

def find_first(file_mask: str, attributes: int, flags: int) -> int: ...

Remarks

This method initiates a search operation based on the specified FileMask, Attributes, and Flags. If there are any matching vault items (files, directories, symbolic links, or alternate streams), then a search operation ID is returned. If there are no matching vault items, then -1 is returned.

To obtain information about a search result, pass the returned search handle to the following methods:

To retrieve the next search result, pass the returned search handle to the find_next method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the find_close method in order to release the resources associated with it.

Since each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time, and may process each operation's search results in any manner it desires (sequentially, round-robin, etc.).

The FileMask parameter specifies both the directory path to search within and the filename mask to match against; e.g., \directory\to\search\*.txt. (Or, when searching a file's alternate streams, the file path and stream name mask; e.g., \path\to\file:*.) Only the mask may contain wildcards, the path must be specified in vault-local absolute format. Also note that files without an extension will match *, but not *.*.

The Attributes parameter specifies the attributes to match against; items will only match if they have one or more of the specified attributes. The value passed for this parameter should be constructed by OR'ing together zero or more of the values shown below. Passing 0 will allow any file in a directory (or, any alternate stream in a file) to match; it's equivalent to VAULT_FATTR_FILE | VAULT_FATTR_DATA_STREAM.

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by OR'ing together zero or more of the following values:

VAULT_FF_NEED_NAME0x00000001Include entry names (without paths) when returning search results.

VAULT_FF_NEED_FULL_NAME0x00000002Include fully-qualified entry names when returning search results.

VAULT_FF_NEED_ATTRIBUTES0x00000004Include entry attributes when returning search results.

VAULT_FF_NEED_SIZE0x00000008Include entry sizes when returning search results.

VAULT_FF_NEED_METADATA_SIZE0x00000010Include entry metadata sizes when returning search results.

VAULT_FF_NEED_TIMES0x00000020Include entry times when returning search results.

VAULT_FF_NEED_LINK_DEST0x00000040Include symbolic link destinations when returning search results.

VAULT_FF_EMULATE_FAT0x00001000Inserts . and .. pseudo-entries into search results for all directories except the root one.

VAULT_FF_RECURSIVE0x00002000Search recursively in all subdirectories.

VAULT_FF_CASE_INSENSITIVE0x00004000Forces case-insensitive search, even if the vault is case-sensitive.

If Flags is 0, the class uses 0x0000006F (i.e., all VAULT_FF_NEED_* flags except VAULT_FF_NEED_METADATA).

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

find_first_by_query Method

Searches for the first file or directory whose file tags match the specified query.

Syntax

def find_first_by_query(directory: str, query: str, flags: int) -> int: ...

Remarks

This method initiates a search operation within the specified Directory for files and subdirectories whose typed file tags match the specified Query. If there are any matching files or directories, then a search operation ID is returned. If there are no matching files or directories, then -1 is returned.

To obtain information about a search result, pass the returned search handle to the following methods:

To retrieve the next search result, pass the returned search handle to the find_next method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the find_close method in order to release the resources associated with it.

Since each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time, and may process each operation's search results in any manner it desires (sequentially, round-robin, etc.).

The value passed for Directory must be a vault-local absolute path.

The value passed for Query must be a search query constructed using the CBFS Storage Query Language; please refer to that topic for more information.

The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by OR'ing together zero or more of the following values:

VAULT_FF_NEED_NAME0x00000001Include entry names (without paths) when returning search results.

VAULT_FF_NEED_FULL_NAME0x00000002Include fully-qualified entry names when returning search results.

VAULT_FF_NEED_ATTRIBUTES0x00000004Include entry attributes when returning search results.

VAULT_FF_NEED_SIZE0x00000008Include entry sizes when returning search results.

VAULT_FF_NEED_METADATA_SIZE0x00000010Include entry metadata sizes when returning search results.

VAULT_FF_NEED_TIMES0x00000020Include entry times when returning search results.

VAULT_FF_NEED_LINK_DEST0x00000040Include symbolic link destinations when returning search results.

VAULT_FF_EMULATE_FAT0x00001000Inserts . and .. pseudo-entries into search results for all directories except the root one.

VAULT_FF_RECURSIVE0x00002000Search recursively in all subdirectories.

VAULT_FF_CASE_INSENSITIVE0x00004000Forces case-insensitive search, even if the vault is case-sensitive.

If Flags is 0, the class uses 0x0000006F (i.e., all VAULT_FF_NEED_* flags except VAULT_FF_NEED_METADATA).

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

find_next Method

Searches for the next vault item that matches an ongoing search operation.

Syntax

def find_next(search_id: int) -> bool: ...

Remarks

This method searches for the next vault item (file, directory, symbolic link, or alternate stream) that matches the ongoing search operation identified by SearchId. If a matching vault item is found, this method returns True; otherwise it returns False.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query. Please refer to those methods' documentation for more information about search operations.

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

force_unmount Method

Forcefully unmounts the virtual drive associated with the specified vault (Windows only).

Syntax

def force_unmount(vault_file: str) -> None: ...

Remarks

This method instructs the CBFS Storage driver to forcefully unmount the virtual drive associated with the vault storage file specified by VaultFile. Typically, this is only necessary if an application crashes without first unmounting the virtual drive(s) that it created.

Please note that only the processes which have access to a vault storage file may forcefully unmount a virtual drive associated with it.

The value passed for VaultFile must be a fully-qualified file path formatted according to OS conventions.

Note: This method cannot be called within events.

format_volume Method

Formats a storage volume or partition with the CBFS Storage filesystem (Windows only).

Syntax

def format_volume(volume_name: str, flags: int) -> None: ...

Remarks

This method formats the storage volume or partition specified by VolumeName with the CBFS Storage filesystem, allowing it to be opened as a vault using the open_volume method.

The VolumeName parameter specifies the fully-qualified name of a storage volume or partition. DOS names, such as X:, are also valid.

The Flags parameter is used to control formatting options, and should be set by OR'ing together zero or more of the following flags:

VAULT_FMF_FAST_FORMAT0x00000001Perform a fast format; only initialize the pages necessary for storing the filesystem structure.

When this flag is not set, all pages of the new vault are initialized.

Note that formatting a large storage partition or volume can take a significant amount of time, and this method will block until the formatting process is complete.

Note: This method cannot be called when active is True, and cannot be called within events.

get_driver_status Method

Retrieves the status of the system driver.

Syntax

def get_driver_status(product_guid: str, module: int) -> int: ...

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.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

MODULE_STATUS_RUNNING0x00000004The specified module is loaded and running.

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_DRIVER_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 class in Windows. 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 virtual disk driver must be re-installed anytime this module is added or removed.

MODULE_DRIVER_BLOCK0x00000002Virtual disk driver (.sys file).

The product's virtual disk driver module, which provides core functionality; it must be installed for the class to function correctly.

MODULE_DRIVER_FS0x00000004Filesystem driver (.sys file).

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

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBVaultDriveShellHelper2022.dll)

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

Note: Not applicable when calling the get_driver_status method.

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

Note: This method cannot be called within events.

get_file_attributes Method

Retrieves the attributes of a vault item.

Syntax

def get_file_attributes(file_name: str) -> int: ...

Remarks

This method retrieves the attributes of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The specified vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

Note: This method can only be called when active is True.

get_file_compression Method

Retrieves the compression mode of a file or alternate stream.

Syntax

def get_file_compression(file_name: str) -> int: ...

Remarks

This method retrieves the compression mode of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The returned compression mode will be one of the following values:

VAULT_CM_NONE0Don't use compression.

VAULT_CM_DEFAULT1Use default compression (zlib).

VAULT_CM_CUSTOM2Use event-based custom compression.

Compression level is not used.

VAULT_CM_ZLIB3Use zlib compression.

Valid compression levels are 1-9.

VAULT_CM_RLE4Use RLE compression.

Compression level is not used.

Applications that use custom compression must the on_data_compress and on_data_decompress events. Please refer to the Compression topic for more information.

Note: This method can only be called when active is True.

get_file_creation_time Method

Retrieves the creation time of a vault item.

Syntax

def get_file_creation_time(file_name: str) -> datetime.datetime: ...

Remarks

This method retrieves the creation time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path.

Note: This method can only be called when active is True.

get_file_encryption Method

Retrieves the encryption mode of a file or alternate stream.

Syntax

def get_file_encryption(file_name: str) -> int: ...

Remarks

This method retrieves the encryption mode of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The returned encryption mode will be one of the following values:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

Note: This method can only be called when active is True.

get_file_last_access_time Method

Retrieves the last access time of a vault item.

Syntax

def get_file_last_access_time(file_name: str) -> datetime.datetime: ...

Remarks

This method retrieves the creation time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

Note that vault items' last access times are only updated if the use_access_time property is enabled.

The value passed for FileName must be a vault-local absolute path.

Note: This method can only be called when active is True.

get_file_modification_time Method

Retrieves the modification time of a vault item.

Syntax

def get_file_modification_time(file_name: str) -> datetime.datetime: ...

Remarks

This method retrieves the modification time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path.

Note: This method can only be called when active is True.

get_file_size Method

Retrieves the size of a file or alternate stream.

Syntax

def get_file_size(file_name: str) -> int: ...

Remarks

This method retrieves the size, in bytes, of the file or alternate stream specified by FileName. (Note that, for files, the returned value only reflects the size of the file's immediate contents, it does not account for any alternate streams the file may or may not contain.)

The value passed for FileName must be a vault-local absolute path.

Note: This method can only be called when active is True.

get_file_tag Method

Retrieves the binary data held by a raw file tag attached to the specified vault item.

Syntax

def get_file_tag(file_name: str, tag_id: int) -> bytes: ...

Remarks

This method retrieves the binary data held by a raw file tag, identified by TagId, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a raw file tag with the specified TagId attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagId must be in the range 0x0001 to 0xCFFF (inclusive).

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_file_tag_as_ansi_string Method

Retrieves the value of an AnsiString-typed file tag attached to the specified vault item.

Syntax

def get_file_tag_as_ansi_string(file_name: str, tag_name: str) -> str: ...

Remarks

This method retrieves the value of an AnsiString-typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't an AnsiString-typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

This method can only retrieve typed file tags created with the set_file_tag_as_ansi_string method. Typed file tags created with the set_file_tag_as_string method must be retrieved using the get_file_tag_as_string method.

Note: This method can only be called when active is True.

get_file_tag_as_boolean Method

Retrieves the value of a Boolean-typed file tag attached to the specified vault item.

Syntax

def get_file_tag_as_boolean(file_name: str, tag_name: str) -> bool: ...

Remarks

This method retrieves the value of a Boolean-typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a Boolean-typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_file_tag_as_date_time Method

Retrieves the value of a DateTime-typed file tag attached to the specified vault item.

Syntax

def get_file_tag_as_date_time(file_name: str, tag_name: str) -> datetime.datetime: ...

Remarks

This method retrieves the value of a DateTime-typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a DateTime-typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The timestamps returned by this method are specified in UTC.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_file_tag_as_number Method

Retrieves the value of a Number-typed file tag attached to the specified vault item.

Syntax

def get_file_tag_as_number(file_name: str, tag_name: str) -> int: ...

Remarks

This method retrieves the value of a Number-typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a Number-typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_file_tag_as_string Method

Retrieves the value of a String-typed file tag attached to the specified vault item.

Syntax

def get_file_tag_as_string(file_name: str, tag_name: str) -> str: ...

Remarks

This method retrieves the value of a String-typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a String-typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

Please refer to the File Tags topic for more information.

This method can only retrieve typed file tags created with the set_file_tag_as_string method. Typed file tags created with the set_file_tag_as_ansi_string method must be retrieved using the get_file_tag_as_ansi_string method.

Note: This method can only be called when active is True.

get_file_tag_data_type Method

Retrieves the data type of a typed file tag attached to a specific vault item.

Syntax

def get_file_tag_data_type(file_name: str, tag_name: str) -> int: ...

Remarks

This method retrieves the data type of a typed file tag, identified by TagName, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a typed file tag with the specified TagName attached to the specified vault item, this method raises an exception.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The value returned by this method will be one of the following (except VAULT_TDT_RAWDATA, which is not applicable):

VAULT_TDT_RAWDATA0x0The tag is untyped and must be addressed by Id.

VAULT_TDT_BOOLEAN0x1The tag contains Boolean data and must be addressed by name.

VAULT_TDT_STRING0x2The tag contains String (UTF-16LE) data and must be addressed by name.

VAULT_TDT_DATETIME0x3The tag contains DateTime data and must be addressed by name.

VAULT_TDT_NUMBER0x4The tag contains numeric (signed 64-bit) data and must be addressed by name.

VAULT_TDT_ANSISTRING0x5The tag contains AnsiString (8-bit string) data and must be addressed by name.

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_file_tag_size Method

Retrieves the size of a raw file tag attached to the specified vault item.

Syntax

def get_file_tag_size(file_name: str, tag_id: int) -> int: ...

Remarks

This method retrieves the size of the binary data held by a raw file tag, identified by TagId, attached to the vault item (file, directory, or alternate stream) specified by FileName. If there isn't a raw file tag with the specified TagId attached to the specified vault item, this method returns 0 as the tag size.

The value passed for FileName must be a vault-local absolute path. The value passed for TagId must be in the range 0x0001 to 0xCFFF (inclusive).

Please refer to the File Tags topic for more information.

Note: This method can only be called when active is True.

get_module_version Method

Retrieves the version of a given product module.

Syntax

def get_module_version(product_guid: str, module: int) -> int: ...

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_DRIVER_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 class in Windows. 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 virtual disk driver must be re-installed anytime this module is added or removed.

MODULE_DRIVER_BLOCK0x00000002Virtual disk driver (.sys file).

The product's virtual disk driver module, which provides core functionality; it must be installed for the class to function correctly.

MODULE_DRIVER_FS0x00000004Filesystem driver (.sys file).

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

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBVaultDriveShellHelper2022.dll)

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

Note: Not applicable when calling the get_driver_status method.

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

Note: This method cannot be called within events.

get_originator_process_id Method

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

Syntax

def get_originator_process_id() -> int: ...

Remarks

This method can be called within the on_file_password_needed and on_file_access 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).

CBVaultDrive/Windows-specific: 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.

get_originator_process_name Method

Retrieves the name of the process that initiated the operation.

Syntax

def get_originator_process_name() -> str: ...

Remarks

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

CBVaultDrive/Windows-specific: 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.

get_originator_thread_id Method

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

Syntax

def get_originator_thread_id() -> int: ...

Remarks

This method can be called within the on_file_password_needed and on_file_access 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.

get_originator_token Method

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

Syntax

def get_originator_token() -> int: ...

Remarks

This method can be called within the on_file_password_needed event 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.

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

Network Access Notes (CBVaultDrive-specific)

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.

get_search_result_attributes Method

Retrieves the attributes of a vault item found during a search operation.

Syntax

def get_search_result_attributes(search_id: int) -> int: ...

Remarks

This method retrieves the attributes of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

The vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

However, if attributes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_ATTRIBUTES for the find_first/find_first_by_query method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_creation_time Method

Retrieves the creation time of a vault item found during a search operation.

Syntax

def get_search_result_creation_time(search_id: int) -> datetime.datetime: ...

Remarks

This method retrieves the creation time of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the find_first/find_first_by_query method's Flags parameter), this method will always return January 1, 1970 00:00:00 UTC. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_full_name Method

Retrieves the fully-qualified name of a vault item found during a search operation.

Syntax

def get_search_result_full_name(search_id: int) -> str: ...

Remarks

This method retrieves the fully-qualified name of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. (That is, the vault item's vault-local absolute path.) Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

If fully-qualified names were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_FULL_NAME for the find_first/find_first_by_query method's Flags parameter), this method will always return empty string. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_last_access_time Method

Retrieves the last access time of a vault item found during a search operation.

Syntax

def get_search_result_last_access_time(search_id: int) -> datetime.datetime: ...

Remarks

This method retrieves the creation time of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the find_first/find_first_by_query method's Flags parameter), this method will always return January 1, 1970 00:00:00 UTC. Please refer to the documentation for these methods for more information.

Note that vault items' last access times are only updated if the use_access_time property is enabled.

Note: This method can only be called when active is True.

get_search_result_link_destination Method

Retrieves the destination of a symbolic link found during a search operation.

Syntax

def get_search_result_link_destination(search_id: int) -> str: ...

Remarks

This method retrieves the fully-qualified name of a symbolic link found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

If the most-recently-found vault item isn't a symbolic link, or if symbolic link destinations were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_LINK_DEST for the find_first/find_first_by_query method's Flags parameter), this method will always return empty string. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_metadata_size Method

Retrieves the size of the metadata associated with a vault item found during a search operation.

Syntax

def get_search_result_metadata_size(search_id: int) -> int: ...

Remarks

This method retrieves the size of the metadata associated with a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The metadata size of a vault item reflects the total size of all vault pages associated with it which do not contain actual file/stream data; this includes file tags (both internal and application-defined), index pages, B-trees, and all other "filesystem information".

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

If metadata sizes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_METADATA_SIZE for the find_first/find_first_by_query method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_modification_time Method

Retrieves the modification time of a vault item found during a search operation.

Syntax

def get_search_result_modification_time(search_id: int) -> datetime.datetime: ...

Remarks

This method retrieves the modification time of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

The timestamps returned by this method are specified in UTC.

If times were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_TIMES for the find_first/find_first_by_query method's Flags parameter), this method will always return January 1, 1970 00:00:00 UTC. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_name Method

Retrieves the name of a vault item found during a search operation.

Syntax

def get_search_result_name(search_id: int) -> str: ...

Remarks

This method retrieves the name of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

The names returned by this method do not include a path; use get_search_result_full_name if a path is needed.

If names were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_NAME for the find_first/find_first_by_query method's Flags parameter), this method will always return empty string. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

get_search_result_size Method

Retrieves the size of a vault item found during a search operation.

Syntax

def get_search_result_size(search_id: int) -> int: ...

Remarks

This method retrieves the size of a vault item (file, directory, symbolic link, or alternate stream) found via find_first/find_first_by_query/find_next as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information. (Note that, for files, the returned value only reflects the size of the file's immediate contents, it does not account for any alternate streams the file may or may not contain.)

The value passed for SearchId must be a search operation ID returned by find_first or find_first_by_query.

If the vault item is a directory, or if sizes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_SIZE for the find_first/find_first_by_query method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.

Note: This method can only be called when active is True.

initialize Method

Initializes the class.

Syntax

def initialize(product_guid: str) -> None: ...

Remarks

This method initializes the class and must be called each time the application starts before attempting to call any of the class'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).

install Method

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

Syntax

def install(cab_file_name: str, product_guid: str, path_to_install: str, modules_to_install: int, flags: int) -> int: ...

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 in Windows 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_DRIVER_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 class in Windows. 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 virtual disk driver must be re-installed anytime this module is added or removed.

MODULE_DRIVER_BLOCK0x00000002Virtual disk driver (.sys file).

The product's virtual disk driver module, which provides core functionality; it must be installed for the class to function correctly.

MODULE_DRIVER_FS0x00000004Filesystem driver (.sys file).

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

MODULE_HELPER_DLL0x00010000Shell Helper DLL (CBVaultDriveShellHelper2022.dll)

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

Note: 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 class versions (e.g., 2017).

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.

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.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation in Windows 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 (0x0522) error.

Note: This method cannot be called within events.

is_directory_empty Method

Checks whether a directory is empty.

Syntax

def is_directory_empty(directory: str) -> bool: ...

Remarks

This method checks whether the directory specified by Directory is empty (i.e., does not contain any files, subdirectories, or symbolic links). If the specified directory is empty, this method returns True; otherwise it returns False.

The value passed for Directory must be a vault-local absolute path.

Note: This method can only be called when active is True.

is_icon_registered Method

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

Syntax

def is_icon_registered(icon_id: str) -> bool: ...

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.

is_valid_vault Method

Checks whether a local file is a CBFS Storage vault.

Syntax

def is_valid_vault() -> bool: ...

Remarks

This method checks whether the file specified by the vault_file property is a CBFS Storage vault that can be opened by the class. The file being checked must be fully closed when this method is called.

If the specified file is a CBFS Storage vault, this method returns True; otherwise it returns False.

If the callback_mode property is enabled, the check will be performed via the appropriate Vault* events (and the value held by vault_file is simply passed to such events for the application to use).

Note that this method uses a simple detection mechanism; it doesn't perform a full consistency check or attempt any repairs, so applications may still need to call check_and_repair even if this method returns True. If an error occurs during the detection process, this method raises an exception.

Note: This method cannot be called when active is True, and cannot be called within events.

is_valid_vault_volume Method

Checks whether a storage partition or volume is formatted with the CBFS Storage filesystem (Windows only).

Syntax

def is_valid_vault_volume(volume_name: str) -> bool: ...

Remarks

This method checks whether the storage partition or volume specified by VolumeName is formatted with the CBFS Storage filesystem. If the specified storage volume or partition is formatted with the CBFS Storage filesystem, this method returns True; otherwise it returns False.

A storage volume or partition formatted with the CBFS Storage filesystem can be opened as a vault using the open_volume method.

The VolumeName parameter specifies the fully-qualified name of a storage volume or partition. DOS names, such as X:, are also valid.

Note that this method uses a simple detection mechanism; it doesn't perform a full consistency check or attempt any repairs, so applications may still need to call check_and_repair even if this method returns True. If an error occurs during the detection process, this method raises an exception.

Note: This method cannot be called within events.

move_file Method

Renames or moves a vault item.

Syntax

def move_file(old_file_name: str, new_file_name: str, overwrite: bool) -> None: ...

Remarks

This method renames or moves a vault item (file, directory, symbolic link, or alternate stream) from the specified OldFileName to the specified NewFileName. For alternate streams, renaming is always possible, but moving them from one file to another is only allowed if the AllowMoveStreamsBetweenFiles configuration setting is enabled.

The values passed for OldFileName and NewFileName must both be vault-local absolute paths (including the item's old and new names, respectively) in the same vault.

The Overwrite parameter specifies what to do if a vault item with the specified NewFileName already exists. If Overwrite is True, and such an item exists, it will be overwritten by the item specified by OldFileName. But if such an item exists, and Overwrite is False, this method raises an exception.

Please note that the usual rules of deletion still apply for an item being overwritten. Notably, a non-empty directory cannot be overwritten.

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

open_file Method

Opens a new or existing file or alternate stream in the vault.

Syntax

def open_file(file_name: str, open_mode: int, read_enabled: bool, write_enabled: bool, password: str) -> CBFSStorageStream: ...

Remarks

This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.

Please note that files and alternate streams cannot be created or written to if the vault itself is open in read_only mode.

The value passed for FileName must be a vault-local absolute path.

The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are:

VAULT_FOM_CREATE_NEW0Creates a new file or alternate stream if possible, failing if one already exists.

VAULT_FOM_CREATE_ALWAYS1Creates a new file or stream, overwriting an existing one if necessary.

VAULT_FOM_OPEN_EXISTING2Opens a file or stream if it exists; fails otherwise.

VAULT_FOM_OPEN_ALWAYS3Opens a file or stream if it exists; creates a new one otherwise.

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit. (Note: WriteEnabled is ignored if read_only is True.)

The Password parameter works as follows:

  • If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
  • If a new file or alternate stream is created, and the default_file_encryption property is not VAULT_EM_NONE, the specified Password is used to encrypt it.
If the value passed for Password is null or empty string and the password is needed, the class will use the current value of either the default_file_create_password or default_file_access_password property depending on whether the file is being created or opened.

Internally, this method simply calls open_file_ex, passing on all shared parameters' values and using the following defaults for the others:

Please refer to the open_file_ex method's documentation for more information.

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

open_file_ex Method

Opens a new or existing file or alternate stream in the vault.

Syntax

def open_file_ex(file_name: str, open_mode: int, read_enabled: bool, write_enabled: bool, share_deny_read: bool, share_deny_write: bool, encryption: int, password: str, compression: int, compression_level: int, pages_per_block: int) -> CBFSStorageStream: ...

Remarks

This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.

Please note that files and alternate streams cannot be created or written to if the vault itself is open in read_only mode.

The value passed for FileName must be a vault-local absolute path.

The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are:

VAULT_FOM_CREATE_NEW0Creates a new file or alternate stream if possible, failing if one already exists.

VAULT_FOM_CREATE_ALWAYS1Creates a new file or stream, overwriting an existing one if necessary.

VAULT_FOM_OPEN_EXISTING2Opens a file or stream if it exists; fails otherwise.

VAULT_FOM_OPEN_ALWAYS3Opens a file or stream if it exists; creates a new one otherwise.

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit. (Note: WriteEnabled is ignored if read_only is True.)

The ShareDenyRead and ShareDenyWrite parameters specify whether other accessors may read and/or write the specified file or alternate stream simultaneously. To prevent simultaneous read and/or write access, pass True; to allow it, pass False.

The Encryption parameter specifies the encryption mode to use when creating a file or alternate stream. Valid values are:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

The Password parameter works as follows:

  • If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
  • If a file or alternate stream is created, and Encryption is not VAULT_EM_NONE, the specified Password is used to encrypt it.
If the value passed for Password is null or empty string and the password is needed, the class will use the current value of either the default_file_create_password or default_file_access_password property depending on whether the file is being created or opened.

The Compression parameter specifies the compression mode to use when creating a file or alternate stream. Valid values are:

VAULT_CM_NONE0Don't use compression.

VAULT_CM_DEFAULT1Use default compression (zlib).

VAULT_CM_CUSTOM2Use event-based custom compression.

Compression level is not used.

VAULT_CM_ZLIB3Use zlib compression.

Valid compression levels are 1-9.

VAULT_CM_RLE4Use RLE compression.

Compression level is not used.

Applications that use custom compression must the on_data_compress and on_data_decompress events. Please refer to the Compression topic for more information.

The CompressionLevel parameter specifies the compression level to use, if applicable.

The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128); or 0, which is interpreted as "default" (currently 16 for both zlib and RLE). Larger values allow for more efficient compression; however, since a block must be decompressed (and, for writes, recompressed) anytime its data is accessed, larger values can also cause excessive slowdown, especially for random access.

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

open_root_data Method

Opens the vault's root data stream.

Syntax

def open_root_data() -> CBFSStorageStream: ...

Remarks

This method opens the vault's root data stream, returning a stream object that provides access to its data.

Please refer to the Using RootData topic for more information.

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

open_vault Method

Opens a new or existing vault.

Syntax

def open_vault(open_mode: int, journaling_mode: int) -> None: ...

Remarks

This method opens a vault, creating it if necessary based on the specified OpenMode.

The OpenMode parameter specifies what behavior to use when opening a vault. Valid values are:

VAULT_OM_CREATE_NEW0Creates a new vault if possible, failing if one already exists.

VAULT_OM_CREATE_ALWAYS1Creates a new vault, overwriting an existing one if necessary.

VAULT_OM_OPEN_EXISTING2Opens a vault if it exists; fails otherwise.

VAULT_OM_OPEN_ALWAYS3Opens a vault if it exists; creates a new one otherwise.

The JournalingMode parameter specifies whether any form of journaling should be used when working with the vault. Valid values are:

VAULT_JM_NONE0No journaling is used.

This mode ensures the fastest operations but if the application crashes, corruption of the vault is possible.

VAULT_JM_METADATA1Journaling is used only for metadata (filesystem structure and directory contents).

This mode is a balance between speed and reliability.

VAULT_JM_FULL2Journaling is used for both filesystem structure and file data and metadata.

This is the slowest but the most reliable option.

When a vault is being created or opened, the vault_file and/or callback_mode properties are used to specify its location. If callback_mode is disabled (default), the class creates or opens a file-based vault at the path specified by vault_file.

If callback_mode is enabled, then the application itself controls where the vault is located and how it is accessed via the Vault* events (and the value held by vault_file is simply passed to said events for the application to use). For brevity, vaults created and accessed using callback mode are referred to as "callback mode vaults"; please refer to the Callback Mode topic for more information.

The class also has a number of other properties and configuration settings used when creating or opening a vault, all of which are listed below. Please refer to each one's documentation for more information, including usage restrictions.

If a file-based vault's storage file (or the storage device it is located on) is marked as read-only, then the read_only property must be enabled before this method is called. If an application attempts to open a vault with a read-only storage file in read-write mode, this method raises an exception.

For the CBVaultDrive class on Windows, an attempt to open a vault file that is compressed or encrypted using NTFS capabilities will lead to an error being reported by this method. It is necessary to not use NTFS compression or encryption on the file in order to avoid a system-wide deadlock in Windows internals.

Note: This method cannot be called when active is True, and cannot be called within events.

open_volume Method

Opens a storage volume or partition formatted with the CBFS Storage filesystem as a vault (Windows only).

Syntax

def open_volume(volume_name: str, journaling_mode: int) -> None: ...

Remarks

This method opens the storage volume or partition specified by VolumeName as a vault.

If the specified volume or partition is not formatted with the CBFS Storage filesystem, this method raises an exception.

The JournalingMode parameter specifies whether any form of journaling should be used when working with the vault. Valid values are:

VAULT_JM_NONE0No journaling is used.

This mode ensures the fastest operations but if the application crashes, corruption of the vault is possible.

VAULT_JM_METADATA1Journaling is used only for metadata (filesystem structure and directory contents).

This mode is a balance between speed and reliability.

VAULT_JM_FULL2Journaling is used for both filesystem structure and file data and metadata.

This is the slowest but the most reliable option.

The VolumeName parameter specifies the fully-qualified name of a storage volume or partition. DOS names, such as X:, are also valid.

Note: This method cannot be called when active is True, and cannot be called within events.

register_icon Method

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

Syntax

def register_icon(icon_path: str, product_guid: str, icon_id: str) -> bool: ...

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 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 class API and the Installer DLL included with the product; please refer to the Driver Installation in Windows 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 (0x0522) error.

Note: This method cannot be called within events.

remove_denied_process Method

Removes a rule that prevents a process from accessing the virtual drive.

Syntax

def remove_denied_process(process_file_name: str, process_id: int) -> None: ...

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 only be called when active is True, and 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

Removes a rule that allows a process to access the virtual drive.

Syntax

def remove_granted_process(process_file_name: str, process_id: int) -> None: ...

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 only be called when active is True, and 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

Removes a mounting point for the virtual drive.

Syntax

def remove_mounting_point(index: int, mounting_point: str, flags: int, authentication_id: int) -> None: ...

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.

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

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

Syntax

def reset_icon() -> None: ...

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 only be called after creating a virtual drive, and cannot be called within events.

resolve_link Method

Retrieves the destination of a symbolic link.

Syntax

def resolve_link(link_name: str, normalize: bool) -> str: ...

Remarks

This method retrieves the destination pointed to by the symbolic link specified by LinkName.

The value passed for LinkName must be a vault-local absolute path.

As the create_link method's documentation describes, symbolic links can be created with either relative or absolute vault-local paths. The Normalize parameter specifies whether the class should normalize the specified link's destination before returning it. Passing True will ensure a vault-local absolute path is always returned; passing False will cause the original destination path to be returned.

Note: This method can only be called when active is True.

set_file_attributes Method

Sets the attributes of a vault item.

Syntax

def set_file_attributes(file_name: str, attributes: int) -> None: ...

Remarks

This method sets the attributes of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Attributes parameter specifies the new attributes for the vault item, which should be constructed by OR'ing together one or more of the following values:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

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

set_file_compression Method

Compresses or decompresses a file or alternate stream.

Syntax

def set_file_compression(file_name: str, compression: int, compression_level: int, pages_per_block: int, password: str) -> None: ...

Remarks

This method changes the compression mode used to compress the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Compression parameter specifies the new compression mode to use. Valid values are:

VAULT_CM_NONE0Don't use compression.

VAULT_CM_DEFAULT1Use default compression (zlib).

VAULT_CM_CUSTOM2Use event-based custom compression.

Compression level is not used.

VAULT_CM_ZLIB3Use zlib compression.

Valid compression levels are 1-9.

VAULT_CM_RLE4Use RLE compression.

Compression level is not used.

Applications that use custom compression must the on_data_compress and on_data_decompress events. Please refer to the Compression topic for more information.

The CompressionLevel parameter specifies the compression level to use, if applicable.

The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128); or 0, which is interpreted as "default" (currently 16 for both zlib and RLE). Larger values allow for more efficient compression; however, since a block must be decompressed (and, for writes, recompressed) anytime its data is accessed, larger values can also cause excessive slowdown, especially for random access.

The Password parameter specifies the password to use to access the file's data, if it is encrypted.

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

set_file_creation_time Method

Sets the creation time of a vault item.

Syntax

def set_file_creation_time(file_name: str, creation_time: datetime.datetime) -> None: ...

Remarks

This method sets the creation time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The CreationTime parameter specifies the new creation time for the vault item, which must be specified in UTC.

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

set_file_encryption Method

Encrypts, decrypts, or changes the encryption password of a file or alternate stream.

Syntax

def set_file_encryption(file_name: str, encryption: int, old_password: str, new_password: str) -> None: ...

Remarks

This method changes the encryption mode and/or password used to encrypt the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Encryption parameter specifies the new encryption mode to use. Valid values are:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

The OldPassword parameter specifies the current encryption password, if applicable.

The NewPassword parameter specifies the new encryption password to use, if applicable.

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

set_file_last_access_time Method

Sets the last access time of a vault item.

Syntax

def set_file_last_access_time(file_name: str, last_access_time: datetime.datetime) -> None: ...

Remarks

This method sets the last access time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The LastAccessTime parameter specifies the new last access time for the vault item, which must be specified in UTC.

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

set_file_modification_time Method

Sets the modification time of a vault item.

Syntax

def set_file_modification_time(file_name: str, modification_time: datetime.datetime) -> None: ...

Remarks

This method sets the modification time of the vault item (file, directory, symbolic link, or alternate stream) specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The ModificationTime parameter specifies the new modification time for the vault item, which must be specified in UTC.

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

set_file_size Method

Sets the size of a file or alternate stream.

Syntax

def set_file_size(file_name: str, size: int, password: str) -> None: ...

Remarks

This method sets the size of the file or alternate stream specified by FileName.

The value passed for FileName must be a vault-local absolute path.

The Size parameter specifies the new size of the file or alternate stream, which must be greater than or equal to 0.

Applications can also change the size of a file or alternate stream using the stream objects returned by the open_file and open_file_ex methods.

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

set_file_tag Method

Attaches a raw file tag with binary data to the specified vault item.

Syntax

def set_file_tag(file_name: str, tag_id: int, data: bytes) -> None: ...

Remarks

This method attaches a raw file tag with binary data to the vault item (file, directory, or alternate stream) specified by FileName using the specified TagId. If a raw file tag with the specified TagId is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagId must be in the range 0x0001 to 0xCFFF (inclusive).

The Data parameter specifies the raw binary data to store in the file tag; it may be up to 65531 bytes in length.

Please refer to the File Tags topic for more information.

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

set_file_tag_as_ansi_string Method

Attaches an AnsiString-typed file tag to the specified vault item.

Syntax

def set_file_tag_as_ansi_string(file_name: str, tag_name: str, value: str) -> None: ...

Remarks

This method attaches an AnsiString-typed file tag to the vault item (file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The Value parameter specifies the AnsiString value to store in the file tag; it may be up to 65529 - (name_length * 2) bytes in length (where name_length is measured in characters), including null terminators for both the AnsiString value and the name.

Please refer to the File Tags topic for more information.

Please note that AnsiString file tag values are converted to UTF-16LE when referenced in a search query string. To minimize the chance of string-conversion-related issues, it is recommended that applications only store ASCII characters in AnsiString-typed file tags, and prefer String-typed file tags (created using set_file_tag_as_string) in all other cases.

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

set_file_tag_as_boolean Method

Attaches a Boolean-typed file tag to the specified vault item.

Syntax

def set_file_tag_as_boolean(file_name: str, tag_name: str, value: bool) -> None: ...

Remarks

This method attaches a Boolean-typed file tag to the vault item (file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The Value parameter specifies the Boolean value to store in the file tag.

Please refer to the File Tags topic for more information.

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

set_file_tag_as_date_time Method

Attaches a DateTime-typed file tag to the specified vault item.

Syntax

def set_file_tag_as_date_time(file_name: str, tag_name: str, value: datetime.datetime) -> None: ...

Remarks

This method attaches a DateTime-typed file tag to the vault item (file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The Value parameter specifies the DateTime value to store in the file tag, which must be specified in UTC.

Please refer to the File Tags topic for more information.

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

set_file_tag_as_number Method

Attaches a Number-typed file tag to the specified vault item.

Syntax

def set_file_tag_as_number(file_name: str, tag_name: str, value: int) -> None: ...

Remarks

This method attaches a Number-typed file tag to the vault item (file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The Value parameter specifies the Number value to store in the file tag.

Please refer to the File Tags topic for more information.

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

set_file_tag_as_string Method

Attaches a String-typed file tag to the specified vault item.

Syntax

def set_file_tag_as_string(file_name: str, tag_name: str, value: str) -> None: ...

Remarks

This method attaches a String-typed file tag to the vault item (file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.

The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).

The Value parameter specifies the UTF-16LE String value to store in the file tag; it may be up to 65529 - (name_length * 2) bytes in length (where name_length is measured in characters), including null terminators for both the String value and the name.

Please refer to the File Tags topic for more information.

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

set_icon Method

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

Syntax

def set_icon(icon_id: str) -> None: ...

Remarks

This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual drive in Windows 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 only be called after creating a virtual drive, and 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

Shuts down or reboots the operating system.

Syntax

def shutdown_system(shutdown_prompt: str, timeout: int, force_close_apps: bool, reboot: bool) -> bool: ...

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 class API and the Installer DLL included with the product; please refer to the Driver Installation in Windows topic for more information about the latter.

Note: This method cannot be called within events.

uninstall Method

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

Syntax

def uninstall(cab_file_name: str, product_guid: str, installed_path: str, flags: int) -> int: ...

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 in Windows 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.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

UNINSTALL_VERSION_ALL0x00000003Uninstall modules from all product versions.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation in Windows 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 (0x0522) error.

Note: This method cannot be called within events.

unix_time_to_file_time Method

Converts the date/time in Unix format to Windows FileTime format.

Syntax

def unix_time_to_file_time(unix_time: int, nanoseconds: int) -> datetime.datetime: ...

Remarks

Use this method to convert the date/time in Unix format to Windows FileTime format.

Pass the Unix time value to UnixTime and optionally pass the subsecond part of the time, expressed in nanoseconds, to the Nanoseconds parameter. If the subsecond part of the time is not available, set Nanoseconds to zero (0) value.

unregister_icon Method

Unregisters an existing overlay icon (Windows only).

Syntax

def unregister_icon(product_guid: str, icon_id: str) -> bool: ...

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 class API and the Installer DLL included with the product; please refer to the Driver Installation in Windows 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 (0x0522) error.

Note: This method cannot be called within events.

update_vault_encryption Method

Encrypts, decrypts, or changes the encryption password of the vault.

Syntax

def update_vault_encryption(encryption: int, old_password: str, new_password: str) -> None: ...

Remarks

This method changes the encryption mode and/or password used to encrypt the vault.

The Encryption parameter specifies the new encryption mode to use. Valid values are:

VAULT_EM_NONE0x0Don't use encryption.

VAULT_EM_DEFAULT0x1Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256).

VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA2560x2Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA2560x3Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA2560x4Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA2560x5Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE0x23Use event-based custom 256-bit encryption with custom key derivation.

256-bit (32-byte) block size.

VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE0x24Use event-based custom 512-bit encryption with custom key derivation.

512-bit (64-byte) block size.

VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE0x25Use event-based custom 1024-bit encryption with custom key derivation.

1024-bit (128-byte) block size.

VAULT_EM_CUSTOM256_DIRECT_KEY0x43Use event-based custom 256-bit encryption with no key derivation.

256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM512_DIRECT_KEY0x44Use event-based custom 512-bit encryption with no key derivation.

512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_CUSTOM1024_DIRECT_KEY0x45Use event-based custom 1024-bit encryption with no key derivation.

1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation.

VAULT_EM_UNKNOWN0xFFUnidentified or unknown encryption.

Applications that use custom encryption must implement at least the on_data_encrypt and on_data_decrypt events; and certain custom encryption modes may also require that the on_hash_calculate or on_key_derive event be implemented as well. Please refer to the Encryption topic for more information.

The OldPassword parameter specifies the current encryption password, if applicable.

The NewPassword parameter specifies the new encryption password to use, if applicable.

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

on_data_compress Event

Fires to compress a block of data using a custom compression algorithm.

Syntax

class CBVaultDriveDataCompressEventParams(object):
  @property
  def in_data() -> c_void_p: ...

  @property
  def in_size() -> int: ...

  @property
  def out_data() -> c_void_p: ...

  @property
  def out_size() -> int: ...
  @out_size.setter
  def out_size(value) -> None: ...

  @property
  def compression_level() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_data_compress() -> Callable[[CBVaultDriveDataCompressEventParams], None]: ...
@on_data_compress.setter
def on_data_compress(event_hook: Callable[[CBVaultDriveDataCompressEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to compress a block of data using an application-defined compression algorithm. Please refer to the Compression topic for more information.

This event only needs to be handled by applications that use the VAULT_CM_CUSTOM compression mode. To handle this event properly, applications must compress all InSize bytes of data in the InData buffer, write the compressed data to the OutData buffer, and set OutSize to reflect the total number of bytes written to OutData.

Note that OutSize is initially set to the capacity of the OutData buffer. If the OutData buffer is not large enough to accommodate all of the data after compression (which, while uncommon, may occur with some compression algorithms), do not write any data to OutData. Instead, set ResultCode to VAULT_ERR_BUFFER_TOO_SMALL to inform the class that the current block of data should remain uncompressed.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The CompressionLevel specifies the requested compression level. Possible values are 0 through 9; where 0 means "use the default compression level". Applications may ignore this value if it is not needed by their compression algorithm.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_data_decompress Event

Fires to decompress a block of data using a custom compression algorithm.

Syntax

class CBVaultDriveDataDecompressEventParams(object):
  @property
  def in_data() -> c_void_p: ...

  @property
  def in_size() -> int: ...

  @property
  def out_data() -> c_void_p: ...

  @property
  def out_size() -> int: ...
  @out_size.setter
  def out_size(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_data_decompress() -> Callable[[CBVaultDriveDataDecompressEventParams], None]: ...
@on_data_decompress.setter
def on_data_decompress(event_hook: Callable[[CBVaultDriveDataDecompressEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to decompress a block of data using an application-defined compression algorithm. Please refer to the Compression topic for more information.

This event only needs to be handled by applications that use the VAULT_CM_CUSTOM compression mode. To handle this event properly, applications must decompress all InSize bytes of data in the InData buffer, write the decompressed data to the OutData buffer, and set OutSize to reflect the total number of bytes written to OutData.

Note that OutSize is initially set to the capacity of the OutData buffer, which (under normal circumstances) should be large enough to accommodate all of the decompressed data. Only if the vault is corrupted should the OutData buffer ever be too small to hold the decompressed data; so if this occurs, do not write any data to OutData. Instead, set ResultCode to VAULT_ERR_VAULT_CORRUPTED.

Please refer to 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_data_decrypt Event

Fires to decrypt a block of data using a custom encryption implementation.

Syntax

class CBVaultDriveDataDecryptEventParams(object):
  @property
  def key() -> c_void_p: ...

  @property
  def key_length() -> int: ...

  @property
  def salt1() -> c_void_p: ...

  @property
  def salt_1_size() -> int: ...

  @property
  def salt2() -> c_void_p: ...

  @property
  def salt_2_size() -> int: ...

  @property
  def data() -> c_void_p: ...

  @property
  def data_size() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_data_decrypt() -> Callable[[CBVaultDriveDataDecryptEventParams], None]: ...
@on_data_decrypt.setter
def on_data_decrypt(event_hook: Callable[[CBVaultDriveDataDecryptEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to decrypt a block of data using an application-defined encryption implementation. Please refer to the Encryption topic for more information.

This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM* encryption modes. To handle this event properly, applications must decrypt all DataSize bytes of data in the Data buffer. After decrypting the data, applications must write it back to the Data buffer. The size of the decrypted data must match DataSize, which is always a multiple of 32.

The Key buffer contains the encryption key (e.g., password) specified for the file, alternate stream, or vault whose data is being decrypted. The KeyLength parameter specifies the length, in bytes, of Key.

The Salt1 and Salt2 buffers contain the same salt values provided when the data was encrypted in an earlier on_data_encrypt event. The Salt1Size and Salt2Size parameters specify the length, in bytes, of Salt1 and Salt2.

Please refer to 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_data_encrypt Event

Fires to encrypt a block of data using a custom encryption implementation.

Syntax

class CBVaultDriveDataEncryptEventParams(object):
  @property
  def key() -> c_void_p: ...

  @property
  def key_length() -> int: ...

  @property
  def salt1() -> c_void_p: ...

  @property
  def salt_1_size() -> int: ...

  @property
  def salt2() -> c_void_p: ...

  @property
  def salt_2_size() -> int: ...

  @property
  def data() -> c_void_p: ...

  @property
  def data_size() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_data_encrypt() -> Callable[[CBVaultDriveDataEncryptEventParams], None]: ...
@on_data_encrypt.setter
def on_data_encrypt(event_hook: Callable[[CBVaultDriveDataEncryptEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to encrypt a block of data using an application-defined encryption implementation. Please refer to the Encryption topic for more information.

This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM* encryption modes. To handle this event properly, applications must encrypt all DataSize bytes of data in the Data buffer. After encrypting the data, applications must write it back to the Data buffer. The size of the encrypted data must match DataSize, which is always a multiple of 32.

The Key buffer contains the encryption key (e.g., password) specified for the file, alternate stream, or vault whose data is being decrypted. The KeyLength parameter specifies the length, in bytes, of Key.

The Salt1 and Salt2 buffers contain salt values that can be used to strengthen encryption, if desired. The Salt1Size and Salt2Size parameters specify the length, in bytes, of Salt1 and Salt2.

Please refer to 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_ejected Event

Fires when the media and virtual drive have been ejected (Windows only).

Syntax

class CBVaultDriveEjectedEventParams(object):
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_ejected() -> Callable[[CBVaultDriveEjectedEventParams], None]: ...
@on_ejected.setter
def on_ejected(event_hook: Callable[[CBVaultDriveEjectedEventParams], None]) -> None: ...

Remarks

This event fires when a user has ejected the media and virtual drive using the Eject command in Windows 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 close_vault (it is called automatically with its Force 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 Reporting and Handling topic for more information.

on_error Event

Fires if an unhandled error occurs during an event.

Syntax

class CBVaultDriveErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class CBVaultDrive:
@property
def on_error() -> Callable[[CBVaultDriveErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[CBVaultDriveErrorEventParams], None]) -> None: ...

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to help track down unhandled errors in an application's event handlers.

on_file_access Event

Fires when the OS wants to create or open a file or directory.

Syntax

class CBVaultDriveFileAccessEventParams(object):
  @property
  def file_name() -> str: ...

  @property
  def existing_attributes() -> int: ...

  @property
  def desired_access() -> int: ...

  @property
  def attributes() -> int: ...

  @property
  def options() -> int: ...

  @property
  def share_mode() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_file_access() -> Callable[[CBVaultDriveFileAccessEventParams], None]: ...
@on_file_access.setter
def on_file_access(event_hook: Callable[[CBVaultDriveFileAccessEventParams], None]) -> None: ...

Remarks

This optional event fires when the OS wants to create or open the existing file or directory specified by FileName. It can be used to control and optionally restrict access to files and directories. The event fires when FireFileAccessEvent setting is enabled (by default, it is disabled for performance reasons).

This event also fires when the OS wants to create or 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.

The ExistingAttributes parameter contains the attributes of the file or directory being opened, if one already exists; otherwise, it contains 0. To determine whether the request is for a file or a directory, compare ExistingAttributes against the VAULT_FATTR_DIRECTORY or VAULT_FATTR_FILE constant respectively, like so: // Check whether the request is for a file or a directory. bool isDirectory = ExistingAttributes & CBFSVAULT_FATTR_DIRECTORY == CBFSVAULT_FATTR_DIRECTORY; bool isFile = ExistingAttributes & CBFSVAULT_FATTR_FILE == CBFSVAULT_FATTR_FILE;

The DesiredAccess parameter specifies the mode of access to the file or directory desired by the process that initiated the request. It can be one of the following values:

STG_DACCESS_READ0x00000001Grant/deny read access.

STG_DACCESS_WRITE0x00000002Grant/deny write access.

STG_DACCESS_READWRITE0x00000003Grant/deny read and write access.

The Attributes parameter contains the value of Attributes, passed by the originator process; it may contain zero or more of the following attributes:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

Windows: The Options parameter includes flags and options that are described in the CreateOptions parameter of the Native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to Native API. If you need those flags, check both functions' descriptions.

Linux, macOS: this parameter is not used.

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.

The ResultCode parameter will always be 0 when the event is fired. Applications may perform the necessary access control using one of GetOriginator* methods, and set ResultCode to 0 to indicate that the file or directory may be opened, or to a system-specific error code to tell the OS about an error. Please refer to the Error Reporting and Handling topic for more information.

Note: an application may not access the drive and its contents from an event handler, as this will cause a deadlock.

on_file_after_copy Event

Fires after the file has been copied during file export/import operations.

Syntax

class CBVaultDriveFileAfterCopyEventParams(object):
  @property
  def source_path() -> str: ...

  @property
  def destination_path() -> str: ...

  @property
  def attributes() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_file_after_copy() -> Callable[[CBVaultDriveFileAfterCopyEventParams], None]: ...
@on_file_after_copy.setter
def on_file_after_copy(event_hook: Callable[[CBVaultDriveFileAfterCopyEventParams], None]) -> None: ...

Remarks

This event fires when the class is executing the copy_to_vault or copy_from_vault method after the file specified by SourcePath has been copied to a file identified by DestinationPath.

For a directory, the event fires after the directory identified by SourcePath has been created as DestinationPath and all of the source directory's contents have been processed.

The event will fire only if the VAULT_CFF_FIRE_COPY_EVENTS flag is included in the Flags parameter of the copy_from_vault or copy_to_vault method. Also, the event will not fire for the base directory that was passed to the copy_to_vault or copy_from_vault method.

A process may check whether it was a file or directory copied by inspecting the value of the Attributes parameter, which contains the attributes of the file as a 32-bit integer. the attributes are composed of one or more of the following values:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

To cancel further copying, return the VAULT_ERR_INTERRUPTED_BY_USER error code via ResultCode.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_file_before_copy Event

Fires before the file is copied during file export/import operations.

Syntax

class CBVaultDriveFileBeforeCopyEventParams(object):
  @property
  def source_path() -> str: ...

  @property
  def destination_path() -> str: ...

  @property
  def attributes() -> int: ...
  @attributes.setter
  def attributes(value) -> None: ...

  @property
  def destination_exists() -> bool: ...

  @property
  def skip() -> bool: ...
  @skip.setter
  def skip(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_file_before_copy() -> Callable[[CBVaultDriveFileBeforeCopyEventParams], None]: ...
@on_file_before_copy.setter
def on_file_before_copy(event_hook: Callable[[CBVaultDriveFileBeforeCopyEventParams], None]) -> None: ...

Remarks

This event fires when the class is executing the copy_to_vault or copy_from_vault method before the file specified by SourcePath is copied to a file identified by DestinationPath or before the directory identified by SourcePath is about to be created as DestinationPath.

The event will fire only if the VAULT_CFF_FIRE_COPY_EVENTS flag is included in the Flags parameter of the copy_from_vault or copy_to_vault method. Also, the event will not fire for the base directory that was passed to the copy_to_vault or copy_from_vault method.

A process may check whether it is file or directory being copied by inspecting the value of the Attributes parameter, which contains the attributes of the file as a 32-bit integer. the attributes are composed of one or more of the following values:

VAULT_FATTR_FILE0x00000001The entry is a file.

VAULT_FATTR_DIRECTORY0x00000002The entry is a directory.

VAULT_FATTR_DATA_STREAM0x00000004The entry is an alternate data stream.

VAULT_FATTR_COMPRESSED0x00000008The file or stream is compressed.

VAULT_FATTR_ENCRYPTED0x00000010The file or stream is encrypted.

VAULT_FATTR_SYMLINK0x00000020The entry is a symbolic link.

VAULT_FATTR_READONLY0x00000040The file is read-only.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_ARCHIVE0x00000080The file requires archiving.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_HIDDEN0x00000100The file is hidden.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_SYSTEM0x00000200The file is a system file.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_TEMPORARY0x00000400The file is temporary.

This attribute is not used by CBFS Storage, but it can be set and retrieved.

VAULT_FATTR_DELETE_ON_CLOSE0x00000800The file should be deleted when the last handle to the file is closed.

This attribute is currently not supported by CBFS Storage.

VAULT_FATTR_RESERVED_00x00001000Reserved.

VAULT_FATTR_RESERVED_10x00002000Reserved.

VAULT_FATTR_RESERVED_20x00004000Reserved.

VAULT_FATTR_RESERVED_30x00008000Reserved.

VAULT_FATTR_NO_USER_CHANGE0x0000F03FA mask which includes all attributes that cannot be changed.

Applications cannot use the set_file_attributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, RESERVED_3.

VAULT_FATTR_USER_DEFINED0x7FF00000A mask for application-defined attributes.

Applications can use the set_file_attributes method to set custom attributes, so long as their values are covered by this mask.

VAULT_FATTR_ANY_FILE0x7FFFFFFFA mask which includes any and all attributes.

An event handler may change the following attributes: VAULT_FATTR_READONLY, VAULT_FATTR_ARCHIVE, VAULT_FATTR_HIDDEN, VAULT_FATTR_SYSTEM, VAULT_FATTR_TEMPORARY. When files are immported to the vault, an event handler may also set user-defined flags that match the VAULT_FATTR_USER_DEFINED mask.

The DestinationExists flag indicates the presense of the file or directory at the moment when the event is fired. Note that when copying the files from the vault, there is a possibility that a file gets created or deleted outside of the class; the value of this parameter may become inaccurate.

To skip the file, set the Skip parameter to true. When the file is skipped, on_file_after_copy does not fire.

To cancel copying, return the VAULT_ERR_INTERRUPTED_BY_USER error code via ResultCode.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_file_password_needed Event

Fires if a password is needed to open an encrypted file.

Syntax

class CBVaultDriveFilePasswordNeededEventParams(object):
  @property
  def file_name() -> str: ...

  @property
  def password() -> str: ...
  @password.setter
  def password(value) -> None: ...

  @property
  def ttl_in_cache() -> int: ...
  @ttl_in_cache.setter
  def ttl_in_cache(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_file_password_needed() -> Callable[[CBVaultDriveFilePasswordNeededEventParams], None]: ...
@on_file_password_needed.setter
def on_file_password_needed(event_hook: Callable[[CBVaultDriveFilePasswordNeededEventParams], None]) -> None: ...

Remarks

This event fires when the encrypted file specified by FileName is being opened if a valid password has not been provided (either directly, or via the default_file_access_password property or cache_file_password method). This event will not fire if a valid password has already been provided, or if the file specified by FileName does not exist in the vault.

To allow access to the specified file, set the Password parameter to the correct password.

If an invalid password is provided by the event handler, the event will fire again.

To prevent access to the specified file or to stop being asked for a password in a loop, return the VAULT_ERR_INVALID_PASSWORD error code via ResultCode.

The TTLInCache parameter specifies time to seconds that the class keeps the password in the internal cache to reduce the number of requests for a password. The value of 0 tells the class to discard the password after the first use.

Note that this event can be fired on different threads, and possibly even on several threads concurrently. As an alternative to handling this event, applications can provide a default file encryption password using the default_file_access_password property, and/or call the cache_file_password method (before a file is opened) to specify a one-time-use password.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_hash_calculate Event

Fires to calculate a password hash using a custom hashing implementation.

Syntax

class CBVaultDriveHashCalculateEventParams(object):
  @property
  def password() -> c_void_p: ...

  @property
  def password_size() -> int: ...

  @property
  def salt() -> c_void_p: ...

  @property
  def salt_size() -> int: ...

  @property
  def hash() -> c_void_p: ...

  @property
  def hash_size() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_hash_calculate() -> Callable[[CBVaultDriveHashCalculateEventParams], None]: ...
@on_hash_calculate.setter
def on_hash_calculate(event_hook: Callable[[CBVaultDriveHashCalculateEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to calculate a password hash using an application-defined hashing implementation. The calculated hash is used to check the password's validity before using it for encryption. Please refer to the Encryption topic for more information.

This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM*_DIRECT_KEY encryption modes. To handle this event property, applications must calculate a hash of the data in the Password buffer (whose length, in bytes, is specified by PasswordSize). The calculated hash must be written to the Hash buffer. The size of the calculated hash must not exceed HashSize.

Applications may, if desired, perform their own password validation and return a predefined value for the hash. Applications should not use the same process for key derivation and hash calculation (or should, at the very least, ensure that salt is used in both operations).

The Salt buffer contains a salt value that can be used (if desired) to strengthen security by increasing the uniqueness of the hash. The SaltSize parameter specifies the length, in bytes, of Salt.

Please refer to 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_key_derive Event

Fires to derive an encryption key using a custom key derivation implementation.

Syntax

class CBVaultDriveKeyDeriveEventParams(object):
  @property
  def password() -> c_void_p: ...

  @property
  def password_size() -> int: ...

  @property
  def salt() -> c_void_p: ...

  @property
  def salt_size() -> int: ...

  @property
  def key() -> c_void_p: ...

  @property
  def key_size() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_key_derive() -> Callable[[CBVaultDriveKeyDeriveEventParams], None]: ...
@on_key_derive.setter
def on_key_derive(event_hook: Callable[[CBVaultDriveKeyDeriveEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to derive an encryption key using an application-defined key derivation implementation. Please refer to the Encryption topic for more information.

This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM*_CUSTOM_KEY_DERIVE encryption modes. To handle this event properly, applications must derive an encryption key from the data in the Password buffer (whose length, in bytes, is specified by PasswordSize). The derived encryption key must be written to the Key buffer. The size of the derived encryption key must not exceed KeySize.

Applications should not use the same process for key derivation and hash calculation (or should, at the very least, ensure that salt is used in both operations).

The Salt buffer contains a salt value that can be used (if desired) to strengthen security by increasing the uniqueness of the derived key. The SaltSize parameter specifies the length, in bytes, of Salt.

Please refer to 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_progress Event

Fires to indicate the progress of long-running vault operations.

Syntax

class CBVaultDriveProgressEventParams(object):
  @property
  def operation() -> int: ...

  @property
  def file_name() -> str: ...

  @property
  def progress() -> int: ...

  @property
  def total() -> int: ...

  @property
  def can_stop() -> bool: ...

  @property
  def stop() -> bool: ...
  @stop.setter
  def stop(value) -> None: ...

# In class CBVaultDrive:
@property
def on_progress() -> Callable[[CBVaultDriveProgressEventParams], None]: ...
@on_progress.setter
def on_progress(event_hook: Callable[[CBVaultDriveProgressEventParams], None]) -> None: ...

Remarks

This event fires anytime the class needs to report the progress of a long-running vault operation. Certain operations may cause this event to fire repeatedly.

The Operation parameter specifies which long-running operation caused this event to fire. Possible values are:

VAULT_PO_FORMATTING0Formatting a vault.

VAULT_PO_CHECKING_11Checking a vault (stage 1).

VAULT_PO_CHECKING_22Checking a vault (stage 2).

VAULT_PO_CHECKING_33Checking a vault (stage 3).

VAULT_PO_CHECKING_44Checking a vault (stage 4).

VAULT_PO_CHECKING_55Checking a vault (stage 5).

VAULT_PO_PAGE_CORRUPTED8Processing a corrupted vault page.

VAULT_PO_PAGE_ORPHANED9Processing an orphaned vault page.

VAULT_PO_COMPRESSING10Compressing a file or alternate stream.

VAULT_PO_DECOMPRESSING11Decompressing a file or alternate stream.

VAULT_PO_ENCRYPTING12Encrypting a vault, file, or alternate stream.

VAULT_PO_DECRYPTING13Decrypting a vault, file, or alternate stream

VAULT_PO_COMPACTING14Compacting a vault.

VAULT_PO_RESIZING15Resizing a vault.

VAULT_PO_CALCULATING_SIZE16Calculating a vault's size.

VAULT_PO_COPYING_FILES_TO_VAULT17Copying files to a vault.

VAULT_PO_COPYING_FILES_FROM_VAULT18Copying files from a vault.

When the operation is copying of files from or to the vault, FileName contains the path of the source file being copied.

The Progress and Total parameters reflect the current and maximum progress values. Both will be 0 if the operation's progression cannot be determined.

The CanStop parameter indicates whether the application may interrupt the operation by setting the Stop parameter to True. Note that some operations can only be interrupted at certain points over the course of their lifetime.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_close Event

Fires to close a callback mode vault.

Syntax

class CBVaultDriveVaultCloseEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_close() -> Callable[[CBVaultDriveVaultCloseEventParams], None]: ...
@on_vault_close.setter
def on_vault_close(event_hook: Callable[[CBVaultDriveVaultCloseEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to close the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must close the vault specified by VaultHandle, and invalidate the handle itself.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_delete Event

Fires to delete a callback mode vault.

Syntax

class CBVaultDriveVaultDeleteEventParams(object):
  @property
  def vault() -> str: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_delete() -> Callable[[CBVaultDriveVaultDeleteEventParams], None]: ...
@on_vault_delete.setter
def on_vault_delete(event_hook: Callable[[CBVaultDriveVaultDeleteEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to delete the callback mode vault identified by Vault.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must delete the vault identified by Vault.

The Vault parameter contains an application-defined vault identifier (name, file path, etc.). The value of this parameter will always match the current value of the vault_file property.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_flush Event

Fires to flush a callback mode vault's data out to storage.

Syntax

class CBVaultDriveVaultFlushEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_flush() -> Callable[[CBVaultDriveVaultFlushEventParams], None]: ...
@on_vault_flush.setter
def on_vault_flush(event_hook: Callable[[CBVaultDriveVaultFlushEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to flush the data of the callback mode vault specified by VaultHandle out to storage.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must flush all data currently buffered for the vault specified by VaultHandle out to storage. For example, if the application is storing vault data in a file on disk, it could call FlushFileBuffers() on Windows.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_get_parent_size Event

Fires to determine how much free space is available for growing a callback mode vault.

Syntax

class CBVaultDriveVaultGetParentSizeEventParams(object):
  @property
  def vault() -> str: ...

  @property
  def vault_handle() -> int: ...

  @property
  def free_space() -> int: ...
  @free_space.setter
  def free_space(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_get_parent_size() -> Callable[[CBVaultDriveVaultGetParentSizeEventParams], None]: ...
@on_vault_get_parent_size.setter
def on_vault_get_parent_size(event_hook: Callable[[CBVaultDriveVaultGetParentSizeEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to determine how much free space is available for growing the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must set FreeSpace to indicate how many bytes of free space are available in the "parent storage" of the vault specified by VaultHandle. For example:

  • If the vault is stored in a file, return the amount of free space on the associated disk.
  • If the vault is stored in memory, return the amount of memory available to the application (keeping in mind any other memory needs the application may have).
  • If the vault is stored on some remote system, query it to determine how much free space is available.

The Vault parameter contains an application-defined vault identifier (name, file path, etc.). The value of this parameter will always match the current value of the vault_file property.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_get_size Event

Fires to determine the size of a callback mode vault.

Syntax

class CBVaultDriveVaultGetSizeEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def size() -> int: ...
  @size.setter
  def size(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_get_size() -> Callable[[CBVaultDriveVaultGetSizeEventParams], None]: ...
@on_vault_get_size.setter
def on_vault_get_size(event_hook: Callable[[CBVaultDriveVaultGetSizeEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to determine the size of the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must set Size to indicate the size, in bytes, of the vault specified by VaultHandle.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_open Event

Fires to open a new or existing callback mode vault.

Syntax

class CBVaultDriveVaultOpenEventParams(object):
  @property
  def vault() -> str: ...

  @property
  def vault_handle() -> int: ...
  @vault_handle.setter
  def vault_handle(value) -> None: ...

  @property
  def open_mode() -> int: ...

  @property
  def read_only() -> bool: ...
  @read_only.setter
  def read_only(value) -> None: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_open() -> Callable[[CBVaultDriveVaultOpenEventParams], None]: ...
@on_vault_open.setter
def on_vault_open(event_hook: Callable[[CBVaultDriveVaultOpenEventParams], None]) -> None: ...

Remarks

This event fires when the class wants to open the callback mode vault identified by Vault.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must open the vault identified by Vault, creating it if necessary based on the specified OpenMode, and return an associated information in VaultHandle.

If the ReadOnly parameter is initially True, the application must open the vault in read-only mode. If ReadOnly is initially False, the application may choose whether to open the vault in read-only or read-write mode, and should update the ReadOnly parameter accordingly, if necessary.

If, for any reason, the vault cannot be opened in a manner consistent with the specified OpenMode, the application must return an appropriate error code via ResultCode.

The Vault parameter contains an application-defined vault identifier (name, file path, etc.). The value of this parameter will always match the current value of the vault_file property.

The VaultHandle parameter is used to return some application-defined handle that uniquely identifies the opened vault. The class uses the returned handle to populate the VaultHandle parameters of the other Vault* events fired for the vault later.

The OpenMode parameter specifies what behavior to use when opening the vault. Valid values are:

VAULT_OM_CREATE_NEW0Creates a new vault if possible, failing if one already exists.

VAULT_OM_CREATE_ALWAYS1Creates a new vault, overwriting an existing one if necessary.

VAULT_OM_OPEN_EXISTING2Opens a vault if it exists; fails otherwise.

VAULT_OM_OPEN_ALWAYS3Opens a vault if it exists; creates a new one otherwise.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_read Event

Fires to read data from a callback mode vault.

Syntax

class CBVaultDriveVaultReadEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def offset() -> int: ...

  @property
  def buffer() -> c_void_p: ...

  @property
  def count() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_read() -> Callable[[CBVaultDriveVaultReadEventParams], None]: ...
@on_vault_read.setter
def on_vault_read(event_hook: Callable[[CBVaultDriveVaultReadEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to read data from the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must read Count bytes of data from the vault specified by VaultHandle into Buffer, starting at the specified Offset in the vault.

Count is always a multiple of the vault's page_size. If, for any reason, an application cannot read exactly Count bytes of data from the vault, it must return an appropriate error code via ResultCode.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_set_size Event

Fires to resize a callback mode vault.

Syntax

class CBVaultDriveVaultSetSizeEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def new_size() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_set_size() -> Callable[[CBVaultDriveVaultSetSizeEventParams], None]: ...
@on_vault_set_size.setter
def on_vault_set_size(event_hook: Callable[[CBVaultDriveVaultSetSizeEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to resize the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must grow or shrink the vault specified by VaultHandle in order to reach the specified NewSize. When growing a vault, applications do not need to sanitize newly-allocated space.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_vault_write Event

Fires to write data to a callback mode vault.

Syntax

class CBVaultDriveVaultWriteEventParams(object):
  @property
  def vault_handle() -> int: ...

  @property
  def offset() -> int: ...

  @property
  def buffer() -> c_void_p: ...

  @property
  def count() -> int: ...

  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_vault_write() -> Callable[[CBVaultDriveVaultWriteEventParams], None]: ...
@on_vault_write.setter
def on_vault_write(event_hook: Callable[[CBVaultDriveVaultWriteEventParams], None]) -> None: ...

Remarks

This event fires when the class needs to write data to the callback mode vault specified by VaultHandle.

This event only needs to be handled if the callback_mode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must write Count bytes of data from Buffer to the vault specified by VaultHandle, starting at the specified Offset in the vault.

Count is always a multiple of the vault's page_size. If, for any reason, an application cannot write exactly Count bytes of data to the vault, it must return an appropriate error code via ResultCode.

Please refer to the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier on_vault_open event.

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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.

Note: when a storage is opened concurrently in read-only mode by several applications using CBVaultDrive or CBMemoryDrive class, the event will fire only in the first application. To prevent such a situation, always open a vault in read-write mode.

on_worker_thread_creation Event

Fires just after a new worker thread is created.

Syntax

class CBVaultDriveWorkerThreadCreationEventParams(object):
  @property
  def result_code() -> int: ...
  @result_code.setter
  def result_code(value) -> None: ...

# In class CBVaultDrive:
@property
def on_worker_thread_creation() -> Callable[[CBVaultDriveWorkerThreadCreationEventParams], None]: ...
@on_worker_thread_creation.setter
def on_worker_thread_creation(event_hook: Callable[[CBVaultDriveWorkerThreadCreationEventParams], None]) -> None: ...

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 class 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 isn't available, security checks failed, etc.), set it to a non-zero value to report an appropriate error. Please refer to the Error Reporting and Handling topic for more information.

on_worker_thread_termination Event

Fires just before a worker thread is terminated.

Syntax

class CBVaultDriveWorkerThreadTerminationEventParams(object):
# In class CBVaultDrive:
@property
def on_worker_thread_termination() -> Callable[[CBVaultDriveWorkerThreadTerminationEventParams], None]: ...
@on_worker_thread_termination.setter
def on_worker_thread_termination(event_hook: Callable[[CBVaultDriveWorkerThreadTerminationEventParams], None]) -> None: ...

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 class 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.

CBFSStorageStream Type

Syntax

cbfsstorage.CBFSStorageStream

Remarks

The CBFSStorageStream type is returned by some of the CBVaultDrive class's methods. All stream types in CBFS Storage share a common API, inherited from Python's io.RawIOBase class, documented below.

Note that, for brevity, many of the members offered by io.RawIOBase are not documented here; please refer to the Python documentation for more information.

Properties

length Gets the length of the stream, in bytes.

length
readable Whether the stream supports reading.

readable()
seekable Whether the stream supports seeking.

seekable()
tell Gets the current position within the stream.

tell()
writable Whether the stream supports writing.

writeable()

Methods

close Flushes and closes the stream. Has no effect if the stream is already closed.

close()
flush Forces all data held by the stream's buffers to be written out to storage.

flush()
read Reads a specified number of bytes from the stream and returns them, advancing the current position within the stream by the number of bytes read.

read(n=-1)

Up to n bytes will be read from the stream and returned. If n is unspecified or -1, all bytes are read. Fewer than n bytes may be returned if fewer than n bytes are read.

readall Reads and returns all bytes available in the stream from the current position onwards.

readall()
readinto Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read.

readinto(b)

Up to len(b) bytes are read into b, and the number of bytes read is returned. The object b should be a pre-allocated, writable array of bytes, either bytearray or a writable memoryview.

seek Sets the current position within the stream based on a particular point of origin.

seek(offset, whence=SEEK_SET)

offset specifies the offset in the stream to seek to, relative to whence, which must be either SEEK_SET, SEEK_CUR, or SEEK_END (or a corresponding integer value) as described by the io.IOBase.seek documentation.

Returns the new position within the stream.

truncate Sets the length of the current stream.

truncate(size=None)

Resizes the current stream to size bytes (or to the current position if size is None).

Returns the new size of the stream.

write Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written.

write(b)

The bytes in b are written to the stream, and the number of bytes written in returned. The object b should be an array of bytes, either bytes, bytearray, or memoryview.

CBVaultDrive Config Settings

The class 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 class, access to these internal properties is provided through the config method.

CBVaultDrive Config Settings

AllowMoveStreamsBetweenFiles:   Whether alternate streams may be moved from one file to another.

This setting specifies whether alternate streams may be moved from one file to another using move_file or (for the CBVaultDrive or CBMemoryDrive class) directly by the OS.

By default, this setting is disabled, and alternate streams can only be renamed within the same file, not moved between them.

Note: This setting 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 close_vault.

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 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).

AutoCompactDelay:   How long a vault must remain idle before starting automatic compaction.

When a vault is open, and the auto_compact_at property is set to a non-zero value, the class will automatically compact the vault in the background as necessary (assuming it is eligible for automatic compaction, as described by the auto_compact_at documentation). This setting specifies how many milliseconds a vault must remain idle before starting automatic compaction operations.

By default, this setting is set to 0, and automatic compaction operations will start without delay.

Note: This setting cannot be changed within events.

DefaultFileCompressionLevel:   The default compression level to use when creating files and alternate streams.

This setting specifies the default compression level that the class should use when creating files and alternate streams, if applicable. Valid values are 0 through 9; where 0 means "use the default compression level for the selected compression algorithm".

By default, this setting is set to 0.

FireFileAccessEvent:   Whether FileAccess event is fired.

This setting specifies whether on_file_access event is fired; it is disabled by default.

LoggingEnabled:   Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this class; it is disabled by default. Please refer to the Error Reporting and Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxNonPagedNameLength:   The maximum number of name characters to store directly within a vault item.

This setting specifies the maximum number of name characters that may be stored within a vault item directly. If a vault item's name is longer than the specified value, then the first MaxNonPagedNameLength characters are stored directly, and the rest are stored in a dedicated vault page. The minimum valid non-paged name length is four characters (4).

A vault's max non-paged name length is permanent, it cannot be changed after the vault is created. When a vault is open, this setting cannot be changed, it can only be queried to obtain the value used by the vault.

By default, this setting is set to 0, and the class will automatically choose an optimal value when creating a vault based on page_size.

Note: This setting cannot be changed when active is True, and cannot be changed within events.

MaxWorkerThreadCount:   The maximum number of worker threads to use to fire events.

This setting specifies the maximum number of worker threads the class 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.

MinWorkerThreadCount:   The minimum number of worker threads to use to fire events.

This setting specifies the minimum number of worker threads the class 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.

PageCacheSize:   The size of the in-memory vault page cache.

This setting controls the size of the built-in data cache; it is specified in bytes. The cache must be large enough to contain at least 8 pages, so this setting's minimum valid value is 8 times the value of the page_size property.

By default, this setting is set to 16777216 (16 MB).

Note: This setting can only be changed when active is True.

PartSize:   The part size used by a multipart vault.

This setting controls the part size to use when creating new multipart vaults, and reflects the part size used by the currently-open vault. Part size is specified in bytes.

A multipart vault's part size is permanent, it cannot be changed after the vault is created. When a vault is open, this setting cannot be changed, it can only be queried to obtain the value used by the vault.

By default, this setting is set to 0, and the class will not create multipart vaults.

Note: This setting cannot be changed when active is True, and 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.

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.

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 cannot be changed within events.

CBVaultDrive Errors

The class uses the error codes shown below, all of which are also available as constants for applications' convenience. System error codes, all of which are positive, may also be used as necessary for virtual-drive-related errors. Please refer to the Error Reporting and Handling topic for more information.

CBVaultDrive Errors

-1   The specified file is not a CBFS Storage vault. (VAULT_ERR_INVALID_VAULT_FILE)
-2   The specified page size is not valid. (VAULT_ERR_INVALID_PAGE_SIZE)
-3   The vault is corrupted. Please call check_and_repair. (VAULT_ERR_VAULT_CORRUPTED)
-4   Too many transactions active. (VAULT_ERR_TOO_MANY_TRANSACTIONS)
-5   A file, directory, symbolic link, or alternate stream with the specified name already exists. (VAULT_ERR_FILE_ALREADY_EXISTS)
-6   One or more transactions are still active. (VAULT_ERR_TRANSACTIONS_STILL_ACTIVE)
-7   The specified file tag already exists. (VAULT_ERR_TAG_ALREADY_EXISTS)
-8   The specified file, directory, symbolic link, or alternate stream was not found. (VAULT_ERR_FILE_NOT_FOUND)
-9   The specified path was not found. (VAULT_ERR_PATH_NOT_FOUND)
-10   The specified file or alternate stream is already open in an exclusive access mode. (VAULT_ERR_SHARING_VIOLATION)
-11   Cannot seek beyond the end of a file or alternate stream. (VAULT_ERR_SEEK_BEYOND_EOF)
-12   There are no other files, directories, symbolic links, or alternate streams that match the search criteria. (VAULT_ERR_NO_MORE_FILES)
-13   The specified name is not valid. (VAULT_ERR_INVALID_FILE_NAME)
-14   The requested operation cannot be performed while a vault is open. (VAULT_ERR_VAULT_ACTIVE)
-15   A vault must be open before the requested operation can be performed. (VAULT_ERR_VAULT_NOT_ACTIVE)
-16   The specified password is incorrect. (VAULT_ERR_INVALID_PASSWORD)
-17   The requested operation cannot be performed; the vault is open in read-only mode. (VAULT_ERR_VAULT_READ_ONLY)
-18   Can't use custom encryption; no custom encryption event handlers provided. (VAULT_ERR_NO_ENCRYPTION_HANDLERS)
-19   Out of memory. (VAULT_ERR_OUT_OF_MEMORY)
-20   A symbolic link's destination file could not be found. (VAULT_ERR_SYMLINK_DESTINATION_NOT_FOUND)
-21   The specified file is not a symbolic link. (VAULT_ERR_FILE_IS_NOT_SYMLINK)
-22   The specified buffer is too small to hold the requested value. (VAULT_ERR_BUFFER_TOO_SMALL)
-23   Decompression failed (possible due to corruption). (VAULT_ERR_BAD_COMPRESSED_DATA)
-24   Invalid parameter. (VAULT_ERR_INVALID_PARAMETER)
-25   The vault is full (and cannot be automatically resized). (VAULT_ERR_VAULT_FULL)
-26   Operation interrupted by user. (VAULT_ERR_INTERRUPTED_BY_USER)
-27   The specified file tag was not found. (VAULT_ERR_TAG_NOT_FOUND)
-28   The specified directory is not empty. (VAULT_ERR_DIRECTORY_NOT_EMPTY)
-29   The file or alternate stream was closed unexpectedly; the handle is no longer valid. (VAULT_ERR_HANDLE_CLOSED)
-30   Invalid file or alternate stream handle. (VAULT_ERR_INVALID_STREAM_HANDLE)
-31   Access denied. (VAULT_ERR_FILE_ACCESS_DENIED)
-32   Can't use custom compression; no custom compression event handlers provided. (VAULT_ERR_NO_COMPRESSION_HANDLERS)
-33   Not implemented in this version of CBFS Storage. (VAULT_ERR_NOT_IMPLEMENTED)
-35   The CBFS Storage system driver has not been installed. (VAULT_ERR_DRIVER_NOT_INSTALLED)
-37   The specified vault cannot be opened, it was created using a newer version of CBFS Storage. (VAULT_ERR_NEW_VAULT_VERSION)
-38   The specified file is not a directory. (VAULT_ERR_FILE_IS_NOT_DIRECTORY)
-39   The specified file tag data type is not valid. (VAULT_ERR_INVALID_TAG_DATA_TYPE)
-40   The specified vault storage file does not exist. (VAULT_ERR_VAULT_FILE_DOES_NOT_EXIST)
-41   The specified vault storage file already exists. (VAULT_ERR_VAULT_FILE_ALREADY_EXISTS)
-42   Some callback mode event handler has returned an unidentified error. (VAULT_ERR_CALLBACK_MODE_FAILURE)
-43   External library could not be initialized or used. (VAULT_ERR_EXTERNAL_ERROR)

Special Use Errors

21   ERROR_NOT_READY: Reported by the methods of the class if initialize has not been called or did not succeed.
575   ERROR_APP_INIT_FAILURE: Reported by the methods of the class 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.
618   ERROR_UNSUPPORTED_COMPRESSION: Reported by the OpenVault method of CBVaultDrive when the vault file is compressed or encrypted (e.g., using built-in NTFS mechanisms), which is not supported.
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.
6002   ERROR_FILE_ENCRYPTED: Reported by the by the OpenVault method of CBVaultDrive when the vault file is encrypted, which is not supported.

Copyright (c) 2023 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2022 Python Edition - Version 22.0 [Build 8517]