CBDrive Component
Properties Methods Events Configuration Settings Errors
The CBDrive component lets applications create a vault, manipulate its contents, and mount it as a virtual drive.
Syntax
callback.CBFSStorage.Cbdrive
Remarks
The CBDrive component provides a superset of the functionality offered by the CBVault component. In addition to allowing applications to create and interact with a vault directly, the CBDrive component can mount a vault as a virtual drive, allowing its contents to be accessed by the system and third-party applications.
Unlike the CBVault component, which can be used as-is, the CBDrive component requires additional deployment steps; please refer to the Driver-specific deployment topics deployment topics for more information. For more information about using CBFS Storage's many features, please refer to the extensive General Information topics.
The CBDrive component is available on Windows, Linux, and macOS platforms.
Getting Started
Each CBDrive component instance controls a single vault-based virtual drive. Applications can use multiple instances of the CBDrive component if their use-case requires that multiple vaults be mounted simultaneously.
Here's how to get up and running:
- 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.
- Call the Initialize method to initialize the CBDrive component. This must be done each time the application starts (if the application is using multiple CBDrive component instances, only the first instance created should be used to call Initialize).
- 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.
- Call the OpenVault method to create/open a vault and mount it as a virtual drive.
- Create one or more Mounting Points for the virtual drive using the AddMountingPoint method.
- At this point, the system and other processes will be able to access the vault's contents via the virtual drive.
- Later, the application can close the vault and unmount the associated virtual drive by calling the CloseVault method.
Property List
The following is the full list of the properties of the component with short descriptions. Click on the links for further details.
AccessDeniedProcesses | Collection of access rules that define which processes may not access the virtual drive. |
AccessGrantedProcesses | Collection of access rules that define which processes may access the virtual drive. |
Active | Whether a vault has been opened and mounted as a virtual drive. |
AutoCompactAt | The free space percentage threshold a vault must reach to be eligible for automatic compaction. |
CallbackMode | Whether the component should operate in callback mode. |
CaseSensitive | Whether the component should open a vault in case-sensitive mode. |
DefaultFileCompression | The default compression mode to use when creating files and alternate streams. |
DefaultFileEncryption | The default encryption mode to use when creating files and alternate streams. |
DefaultFilePassword | The default encryption password to use when creating or opening files and alternate streams. |
FileSystemName | The name of the virtual filesystem. |
IsCorrupted | Whether the vault is corrupted. |
LastWriteTime | The last modification time of the vault. |
Logo | An application-defined text-based logo stored in the second page of a vault. |
MountingPoints | Collection of mounting points for the virtual drive. |
PageSize | The vault's page size. |
PathSeparator | The path separator character to use when returning vault paths. |
PossibleFreeSpace | The maximum amount of free space the vault could possibly have available. |
PossibleSize | The maximum size the vault could possibly be. |
ProcessRestrictionsEnabled | Whether process access restrictions are enabled. |
ReadOnly | Whether the component should open a vault in read-only mode. |
ReportPossibleSize | How the component should report the virtual drive's size and free space to the OS. |
StorageCharacteristics | The characteristic flags to create the virtual drive with. (Windows only). |
StorageType | The type of virtual drive to create. (Windows only). |
Tag | Stores application-defined data specific to this instance of the component. |
Timeout | How long vault events may execute before timing out. (Windows only). |
UnmountOnTermination | Whether the virtual drive should be unmounted if the application terminates. (Windows only). |
UseAccessTime | Whether the component should keep track of last access times for vault items. |
UseJournaling | Whether the component should open a vault in journaling mode. |
UseSystemCache | Whether the operating system's cache is used. |
VaultEncryption | The whole-vault encryption mode. |
VaultFile | The vault to create and/or open. |
VaultFreeSpace | The actual amount of free space the vault has available. |
VaultPassword | The whole-vault encryption password. |
VaultSize | The actual size of the vault. |
VaultSizeMax | The maximum size a vault can be. |
VaultSizeMin | The minimum size a vault can be. |
VaultState | Information about the state of the vault. |
Method List
The following is the full list of the methods of the component with short descriptions. Click on the links for further details.
AddDeniedProcess | Adds a rule that prevents a process from accessing the virtual drive. |
AddGrantedProcess | Adds a rule that allows a process to access the virtual drive. |
AddMountingPoint | Adds a mounting point for the virtual drive. |
CacheFilePassword | Caches an encryption password to use the next time a file or alternate stream is accessed. |
CheckAndRepair | Checks a vault's consistency and repairs it as necessary. |
CheckFilePassword | Verifies whether a particular file password is correct. |
CheckVaultPassword | Verifies whether a particular vault password is correct. |
CloseVault | Closes the vault. |
CompactVault | Compacts the vault. |
Config | Sets or retrieves a configuration setting. |
ConvertToDrivePath | Converts a vault-local vault item path to a virtual drive file path. |
ConvertToVaultPath | Converts a virtual drive file path to a vault-local vault item path. |
CreateDirectory | Creates a new directory in the vault. |
CreateLink | Creates a symbolic link to another file in the vault. |
DeleteFile | Deletes a vault item. |
DeleteFileTag | Deletes a file tag. |
EjectVolume | Ejects a removable storage volume formatted with the CBFS Storage filesystem. (Windows only). |
FileExists | Checks whether a vault item exists. |
FileMatchesMask | Checks whether a particular file or directory name matches the specified mask. |
FileTagExists | Checks whether a file tag exists. |
FindClose | Closes a search operation and releases any associated resources. |
FindFirst | Searches for the first vault item that matches the specified name and attributes. |
FindFirstByQuery | Searches for the first file or directory whose file tags match the specified query. |
FindNext | Searches for the next vault item that matches an ongoing search operation. |
ForceUnmount | Forcefully unmounts the virtual drive associated with the specified vault. (Windows only). |
FormatVolume | Formats a storage volume or partition with the CBFS Storage filesystem. (Windows only). |
GetDriverStatus | Retrieves the status of the system driver. |
GetFileAttributes | Retrieves the attributes of a vault item. |
GetFileCompression | Retrieves the compression mode of a file or alternate stream. |
GetFileCreationTime | Retrieves the creation time of a vault item. |
GetFileEncryption | Retrieves the encryption mode of a file or alternate stream. |
GetFileLastAccessTime | Retrieves the last access time of a vault item. |
GetFileModificationTime | Retrieves the modification time of a vault item. |
GetFileSize | Retrieves the size of a file or alternate stream. |
GetFileTag | Retrieves the binary data held by a raw file tag attached to the specified vault item. |
GetFileTagAsAnsiString | Retrieves the value of an AnsiString-typed file tag attached to the specified vault item. |
GetFileTagAsBoolean | Retrieves the value of a Boolean-typed file tag attached to the specified vault item. |
GetFileTagAsDateTime | Retrieves the value of a DateTime-typed file tag attached to the specified vault item. |
GetFileTagAsNumber | Retrieves the value of a Number-typed file tag attached to the specified vault item. |
GetFileTagAsString | Retrieves the value of a String-typed file tag attached to the specified vault item. |
GetFileTagDataType | Retrieves the data type of a typed file tag attached to a specific vault item. |
GetFileTagSize | Retrieves the size of a raw file tag attached to the specified vault item. |
GetModuleVersion | Retrieves the version of a given product module. |
GetOriginatorProcessId | Retrieves the Id of the process (PID) that initiated the operation. |
GetOriginatorProcessName | Retrieves the name of the process that initiated the operation. |
GetOriginatorThreadId | Retrieves the Id of the thread that initiated the operation. (Windows only). |
GetOriginatorToken | Retrieves the security token associated with the process that initiated the operation. (Windows only). |
GetSearchResultAttributes | Retrieves the attributes of a vault item found during a search operation. |
GetSearchResultCreationTime | Retrieves the creation time of a vault item found during a search operation. |
GetSearchResultFullName | Retrieves the fully-qualified name of a vault item found during a search operation. |
GetSearchResultLastAccessTime | Retrieves the last access time of a vault item found during a search operation. |
GetSearchResultLinkDestination | Retrieves the destination of a symbolic link found during a search operation. |
GetSearchResultMetadataSize | Retrieves the size of the metadata associated with a vault item found during a search operation. |
GetSearchResultModificationTime | Retrieves the modification time of a vault item found during a search operation. |
GetSearchResultName | Retrieves the name of a vault item found during a search operation. |
GetSearchResultSize | Retrieves the size of a vault item found during a search operation. |
Initialize | Initializes the component. |
Install | Installs (or upgrades) the product's system drivers and/or helper DLL. (Windows only). |
IsCBFSStorageVault | Checks whether a local file is a CBFS Storage vault. |
IsCBFSStorageVolume | Checks whether a storage partition or volume is formatted with the CBFS Storage filesystem. |
IsDirectoryEmpty | Checks whether a directory is empty. |
IsIconRegistered | Checks whether the specified icon is registered. |
MoveFile | Renames or moves a vault item. |
OpenFile | Opens a new or existing file or alternate stream in the vault. |
OpenFileEx | Opens a new or existing file or alternate stream in the vault. |
OpenRootData | Opens the vault's root data stream. |
OpenVault | Opens a new or existing vault. |
OpenVolume | Opens a storage volume or partition formatted with the CBFS Storage filesystem as a vault. (Windows only). |
RegisterIcon | Registers an icon that can be displayed as an overlay on the virtual drive in Windows Explorer. |
RemoveDeniedProcess | Removes a rule that prevents a process from accessing the virtual drive. |
RemoveGrantedProcess | Removes a rule that allows a process to access the virtual drive. |
RemoveMountingPoint | Removes a mounting point for the virtual drive. |
ResetIcon | Resets the virtual drive's icon back to default by deselecting the active overlay icon. |
ResolveLink | Retrieves the destination of a symbolic link. |
SetFileAttributes | Sets the attributes of a vault item. |
SetFileCompression | Compresses or decompresses a file or alternate stream. |
SetFileCreationTime | Sets the creation time of a vault item. |
SetFileEncryption | Encrypts, decrypts, or changes the encryption password of a file or alternate stream. |
SetFileLastAccessTime | Sets the last access time of a vault item. |
SetFileModificationTime | Sets the modification time of a vault item. |
SetFileSize | Sets the size of a file or alternate stream. |
SetFileTag | Attaches a raw file tag with binary data to the specified vault item. |
SetFileTagAsAnsiString | Attaches an AnsiString-typed file tag to the specified vault item. |
SetFileTagAsBoolean | Attaches a Boolean-typed file tag to the specified vault item. |
SetFileTagAsDateTime | Attaches a DateTime-typed file tag to the specified vault item. |
SetFileTagAsNumber | Attaches a Number-typed file tag to the specified vault item. |
SetFileTagAsString | Attaches a String-typed file tag to the specified vault item. |
SetIcon | Selects a registered overlay icon for display on the virtual drive in Windows Explorer. |
ShutdownSystem | Shuts down or reboots the operating system. |
Uninstall | Uninstalls the product's system drivers and/or helper DLL. (Windows only). |
UnregisterIcon | Unregisters an existing overlay icon. |
UpdateVaultEncryption | Encrypts, decrypts, or changes the encryption password of the vault. |
Event List
The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.
DataCompress | Fires to compress a block of data using a custom compression algorithm. |
DataDecompress | Fires to decompress a block of data using a custom compression algorithm. |
DataDecrypt | Fires to decrypt a block of data using a custom encryption implementation. |
DataEncrypt | Fires to encrypt a block of data using a custom encryption implementation. |
Ejected | Fires when the media and virtual drive have been ejected. |
Error | Fires if an unhandled error occurs during an event. |
FilePasswordNeeded | Fires if a password is needed to open an encrypted file. |
HashCalculate | Fires to calculate a password hash using a custom hashing implementation. |
KeyDerive | Fires to derive an encryption key using a custom key derivation implementation. |
Progress | Fires to indicate the progress of long-running vault operations. |
VaultClose | Fires to close a callback mode vault. |
VaultDelete | Fires to delete a callback mode vault. |
VaultFlush | Fires to flush a callback mode vault's data out to storage. |
VaultGetParentSize | Fires to determine how much free space is available for growing a callback mode vault. |
VaultGetSize | Fires to determine the size of a callback mode vault. |
VaultOpen | Fires to open a new or existing callback mode vault. |
VaultRead | Fires to read data from a callback mode vault. |
VaultSetSize | Fires to resize a callback mode vault. |
VaultWrite | Fires to write data to a callback mode vault. |
Configuration Settings
The following is a list of configuration settings for the component with short descriptions. Click on the links for further details.
AllowMoveStreamsBetweenFiles | Whether alternate streams may be moved from one file to another. |
AlwaysJournalMetadata | Whether filesystem structure is always saved during modification, like in Journaling mode. |
AsyncDeleteStorageNotifications | Whether system broadcasts for virtual drive deletion are sent asynchronously. |
AutoCompactDelay | How long a vault must remain idle before starting automatic compaction. |
DefaultFileCompressionLevel | The default compression level to use when creating files and alternate streams. |
LoggingEnabled | Whether extended logging is enabled. |
MaxNonPagedNameLength | The maximum number of name characters to store directly within a vault item. |
PageCacheSize | The size of the in-memory vault page cache. |
PartSize | The part size used by a multipart vault. |
SupportSearchIndexer | Specifies whether the driver must take additional measures to support indexing by Windows Search. |
VolumeGuidName | The GUID of the mounted volume. |