CBDrive Class

Properties   Methods   Events   Configuration Settings   Errors  

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

Syntax

CBDrive

Remarks

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

Unlike the CBVault class, which can be used as-is, the CBDrive class requires additional deployment steps; please refer to the CBDrive-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 CBDrive class instance controls a single vault-based virtual drive. Applications can use multiple instances of the CBDrive class if their use-case requires that multiple vaults be mounted simultaneously.

Here's how to get up and running:

  1. Ensure that the required Prerequisites have been satisfied. On Windows, for example, this involves installing the system driver, which can be done using the Install method.
  2. Call the Initialize method to initialize the CBDrive class. This must be done each time the application starts (if the application is using multiple CBDrive class instances, only the first instance created should be used to call Initialize).
  3. If the application is using custom compression, custom encryption, or callback mode, ensure that the appropriate event handlers have been implemented. Please refer to the linked topics for more information.
  4. Call the OpenVault 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 AddMountingPoint 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 CloseVault 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.

AccessDeniedProcessCountThe number of records in the AccessDeniedProcess arrays.
AccessDeniedProcessDesiredAccessThe kind of access granted or denied.
AccessDeniedProcessIncludeChildrenWhether child processes are affected.
AccessDeniedProcessIdThe Id of the target process.
AccessDeniedProcessNameThe filename of the target process's executable.
AccessGrantedProcessCountThe number of records in the AccessGrantedProcess arrays.
AccessGrantedProcessDesiredAccessThe kind of access granted or denied.
AccessGrantedProcessIncludeChildrenWhether child processes are affected.
AccessGrantedProcessIdThe Id of the target process.
AccessGrantedProcessNameThe filename of the target process's executable.
ActiveWhether a vault has been opened and mounted as a virtual drive.
AutoCompactAtThe free space percentage threshold a vault must reach to be eligible for automatic compaction.
CallbackModeWhether the class should operate in callback mode.
CaseSensitiveWhether the class should open a vault in case-sensitive mode.
DefaultFileCompressionThe default compression mode to use when creating files and alternate streams.
DefaultFileEncryptionThe default encryption mode to use when creating files and alternate streams.
DefaultFilePasswordThe default encryption password to use when creating or opening files and alternate streams.
FileSystemNameThe name of the virtual filesystem.
IsCorruptedWhether the vault is corrupted.
LastWriteTimeThe last modification time of the vault.
LogoAn application-defined text-based logo stored in the second page of a vault.
MountingPointCountThe number of records in the MountingPoint arrays.
MountingPointAuthenticationIdThe Authentication ID used when creating the mounting point, if applicable.
MountingPointFlagsThe flags used to create the mounting point.
MountingPointNameThe mounting point name.
PageSizeThe vault's page size.
PathSeparatorThe path separator character to use when returning vault paths.
PossibleFreeSpaceThe maximum amount of free space the vault could possibly have available.
PossibleSizeThe maximum size the vault could possibly be.
ProcessRestrictionsEnabledWhether process access restrictions are enabled.
ReadOnlyWhether the class should open a vault in read-only mode.
ReportPossibleSizeHow the class should report the virtual drive's size and free space to the OS.
StorageCharacteristicsThe characteristic flags to create the virtual drive with. (Windows only).
StorageTypeThe 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).
UnmountOnTerminationWhether the virtual drive should be unmounted if the application terminates. (Windows only).
UseAccessTimeWhether the class should keep track of last access times for vault items.
UseJournalingWhether the class should open a vault in journaling mode.
UseSystemCacheWhether the operating system's cache is used.
VaultEncryptionThe whole-vault encryption mode.
VaultFileThe vault to create and/or open.
VaultFreeSpaceThe actual amount of free space the vault has available.
VaultPasswordThe whole-vault encryption password.
VaultSizeThe actual size of the vault.
VaultSizeMaxThe maximum size a vault can be.
VaultSizeMinThe minimum size a vault can be.
VaultStateInformation 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.

AddDeniedProcessAdds a rule that prevents a process from accessing the virtual drive.
AddGrantedProcessAdds a rule that allows a process to access the virtual drive.
AddMountingPointAdds a mounting point for the virtual drive.
CacheFilePasswordCaches an encryption password to use the next time a file or alternate stream is accessed.
CheckAndRepairChecks a vault's consistency and repairs it as necessary.
CheckFilePasswordVerifies whether a particular file password is correct.
CheckVaultPasswordVerifies whether a particular vault password is correct.
CloseVaultCloses the vault.
CompactVaultCompacts the vault.
ConfigSets or retrieves a configuration setting.
ConvertToDrivePathConverts a vault-local vault item path to a virtual drive file path.
ConvertToVaultPathConverts a virtual drive file path to a vault-local vault item path.
CreateDirectoryCreates a new directory in the vault.
CreateLinkCreates a symbolic link to another file in the vault.
DeleteFileDeletes a vault item.
DeleteFileTagDeletes a file tag.
EjectVolumeEjects a removable storage volume formatted with the CBFS Storage filesystem. (Windows only).
FileExistsChecks whether a vault item exists.
FileMatchesMaskChecks whether a particular file or directory name matches the specified mask.
FileTagExistsChecks whether a file tag exists.
FindCloseCloses a search operation and releases any associated resources.
FindFirstSearches for the first vault item that matches the specified name and attributes.
FindFirstByQuerySearches for the first file or directory whose file tags match the specified query.
FindNextSearches for the next vault item that matches an ongoing search operation.
ForceUnmountForcefully unmounts the virtual drive associated with the specified vault. (Windows only).
FormatVolumeFormats a storage volume or partition with the CBFS Storage filesystem. (Windows only).
GetDriverStatusRetrieves the status of the system driver.
GetFileAttributesRetrieves the attributes of a vault item.
GetFileCompressionRetrieves the compression mode of a file or alternate stream.
GetFileCreationTimeRetrieves the creation time of a vault item.
GetFileEncryptionRetrieves the encryption mode of a file or alternate stream.
GetFileLastAccessTimeRetrieves the last access time of a vault item.
GetFileModificationTimeRetrieves the modification time of a vault item.
GetFileSizeRetrieves the size of a file or alternate stream.
GetFileTagRetrieves the binary data held by a raw file tag attached to the specified vault item.
GetFileTagAsAnsiStringRetrieves the value of an AnsiString-typed file tag attached to the specified vault item.
GetFileTagAsBooleanRetrieves the value of a Boolean-typed file tag attached to the specified vault item.
GetFileTagAsDateTimeRetrieves the value of a DateTime-typed file tag attached to the specified vault item.
GetFileTagAsNumberRetrieves the value of a Number-typed file tag attached to the specified vault item.
GetFileTagAsStringRetrieves the value of a String-typed file tag attached to the specified vault item.
GetFileTagDataTypeRetrieves the data type of a typed file tag attached to a specific vault item.
GetFileTagSizeRetrieves the size of a raw file tag attached to the specified vault item.
GetModuleVersionRetrieves the version of a given product module.
GetOriginatorProcessIdRetrieves the Id of the process (PID) that initiated the operation.
GetOriginatorProcessNameRetrieves the name of the process that initiated the operation.
GetOriginatorThreadIdRetrieves the Id of the thread that initiated the operation. (Windows only).
GetOriginatorTokenRetrieves the security token associated with the process that initiated the operation. (Windows only).
GetSearchResultAttributesRetrieves the attributes of a vault item found during a search operation.
GetSearchResultCreationTimeRetrieves the creation time of a vault item found during a search operation.
GetSearchResultFullNameRetrieves the fully-qualified name of a vault item found during a search operation.
GetSearchResultLastAccessTimeRetrieves the last access time of a vault item found during a search operation.
GetSearchResultLinkDestinationRetrieves the destination of a symbolic link found during a search operation.
GetSearchResultMetadataSizeRetrieves the size of the metadata associated with a vault item found during a search operation.
GetSearchResultModificationTimeRetrieves the modification time of a vault item found during a search operation.
GetSearchResultNameRetrieves the name of a vault item found during a search operation.
GetSearchResultSizeRetrieves the size of a vault item found during a search operation.
InitializeInitializes the class.
InstallInstalls (or upgrades) the product's system drivers and/or helper DLL. (Windows only).
IsCBFSStorageVaultChecks whether a local file is a CBFS Storage vault.
IsCBFSStorageVolumeChecks whether a storage partition or volume is formatted with the CBFS Storage filesystem.
IsDirectoryEmptyChecks whether a directory is empty.
IsIconRegisteredChecks whether the specified icon is registered.
MoveFileRenames or moves a vault item.
OpenFileOpens a new or existing file or alternate stream in the vault.
OpenFileExOpens a new or existing file or alternate stream in the vault.
OpenRootDataOpens the vault's root data stream.
OpenVaultOpens a new or existing vault.
OpenVolumeOpens a storage volume or partition formatted with the CBFS Storage filesystem as a vault. (Windows only).
RegisterIconRegisters an icon that can be displayed as an overlay on the virtual drive in Windows Explorer.
RemoveDeniedProcessRemoves a rule that prevents a process from accessing the virtual drive.
RemoveGrantedProcessRemoves a rule that allows a process to access the virtual drive.
RemoveMountingPointRemoves a mounting point for the virtual drive.
ResetIconResets the virtual drive's icon back to default by deselecting the active overlay icon.
ResolveLinkRetrieves the destination of a symbolic link.
SetFileAttributesSets the attributes of a vault item.
SetFileCompressionCompresses or decompresses a file or alternate stream.
SetFileCreationTimeSets the creation time of a vault item.
SetFileEncryptionEncrypts, decrypts, or changes the encryption password of a file or alternate stream.
SetFileLastAccessTimeSets the last access time of a vault item.
SetFileModificationTimeSets the modification time of a vault item.
SetFileSizeSets the size of a file or alternate stream.
SetFileTagAttaches a raw file tag with binary data to the specified vault item.
SetFileTagAsAnsiStringAttaches an AnsiString-typed file tag to the specified vault item.
SetFileTagAsBooleanAttaches a Boolean-typed file tag to the specified vault item.
SetFileTagAsDateTimeAttaches a DateTime-typed file tag to the specified vault item.
SetFileTagAsNumberAttaches a Number-typed file tag to the specified vault item.
SetFileTagAsStringAttaches a String-typed file tag to the specified vault item.
SetIconSelects a registered overlay icon for display on the virtual drive in Windows Explorer.
ShutdownSystemShuts down or reboots the operating system.
UninstallUninstalls the product's system drivers and/or helper DLL. (Windows only).
UnregisterIconUnregisters an existing overlay icon.
UpdateVaultEncryptionEncrypts, 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.

DataCompressFires to compress a block of data using a custom compression algorithm.
DataDecompressFires to decompress a block of data using a custom compression algorithm.
DataDecryptFires to decrypt a block of data using a custom encryption implementation.
DataEncryptFires to encrypt a block of data using a custom encryption implementation.
EjectedFires when the media and virtual drive have been ejected.
ErrorFires if an unhandled error occurs during an event.
FilePasswordNeededFires if a password is needed to open an encrypted file.
HashCalculateFires to calculate a password hash using a custom hashing implementation.
KeyDeriveFires to derive an encryption key using a custom key derivation implementation.
ProgressFires to indicate the progress of long-running vault operations.
VaultCloseFires to close a callback mode vault.
VaultDeleteFires to delete a callback mode vault.
VaultFlushFires to flush a callback mode vault's data out to storage.
VaultGetParentSizeFires to determine how much free space is available for growing a callback mode vault.
VaultGetSizeFires to determine the size of a callback mode vault.
VaultOpenFires to open a new or existing callback mode vault.
VaultReadFires to read data from a callback mode vault.
VaultSetSizeFires to resize a callback mode vault.
VaultWriteFires to write data to a callback mode vault.

Configuration Settings


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

AllowMoveStreamsBetweenFilesWhether alternate streams may be moved from one file to another.
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.
DeviceChangeBroadcastsEnabledWhether the user-mode API broadcasts WM_DEVICECHANGE messages.
LoggingEnabledWhether extended logging is enabled.
MaxNonPagedNameLengthThe maximum number of name characters to store directly within a vault item.
PageCacheSizeThe size of the in-memory vault page cache.
PartSizeThe part size used by a multipart vault.
SupportSearchIndexerSpecifies whether the driver must take additional measures to support indexing by Windows Search.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

 
 
Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 C++ Edition - Version 20.0 [Build 7649]