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
CBVaultDrive
Remarks
The CBVaultDrive class provides a superset of the functionality offered by the CBFS Vault product. 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 CBFS Vault, 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:
- 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 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).
- 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 class 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 | This property specifies the free space percentage threshold a vault must reach to be eligible for automatic compaction. |
CallbackMode | This property specifies whether the class should operate in callback mode. |
CaseSensitive | This property specifies whether the class should open a vault in case-sensitive mode. |
DefaultFileAccessPassword | This property specifies the default encryption password to use when opening files and alternate streams. |
DefaultFileCompression | This property specifies the default compression mode to use when creating files and alternate streams. |
DefaultFileCreatePassword | This property specifies the default encryption password to use when creating new files and alternate streams. |
DefaultFileEncryption | This property specifies the default encryption mode to use when creating files and alternate streams. |
FileSystemName | The name of the virtual filesystem. |
IsCorrupted | This property specifies whether the vault is corrupted. |
LastWriteTime | This property specifies the last modification time of the vault. |
Logo | This property specifies an application-defined text-based logo stored in the second page of a vault. |
MountingPoints | Collection of mounting points for the virtual drive. |
OpenFiles | Collection of information about the objects in the virtual drive that are currently open. |
PageSize | This property specifies the vault's page size. |
PathSeparator | This property specifies the path separator character to use when returning vault paths. |
PossibleFreeSpace | This property specifies the maximum amount of free space the vault could possibly have available. |
PossibleSize | This property specifies the maximum size the vault could possibly be. |
ProcessRestrictionsEnabled | Whether process access restrictions are enabled. |
ReadOnly | This property specifies whether the class should open a vault in read-only mode. |
ReportPossibleSize | How the class should report the virtual drive's size and free space to the OS. |
SerializeEvents | Whether events should be fired on a single worker thread, or many. |
StorageCharacteristics | The characteristic flags to create the virtual drive with (Windows only). |
StorageGUID | The GUID to create the virtual drive with. |
StorageType | The type of virtual drive to create (Windows only). |
Tag | This property stores application-defined data specific to a particular instance of the class. |
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 | This property specifies whether the class should keep track of last access times for vault items. |
UseSystemCache | This property specifies whether the operating system's cache is used. |
VaultEncryption | This property specifies the whole-vault encryption mode. |
VaultFile | This property specifies the vault to create or open. |
VaultFreeSpace | This property reflects the actual amount of free space the vault has available. |
VaultPassword | This property specifies the whole-vault encryption password. |
VaultSize | This property specifies the actual size of the vault. |
VaultSizeMax | This property specifies the maximum size a vault can be. |
VaultSizeMin | This property specifies the minimum size a vault can be. |
VaultState | This property specifies information 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.
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 | This method caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password. |
CheckAndRepair | This method checks a vault's consistency and repairs it as necessary. |
CheckFilePassword | This method verifies whether a particular file password is correct. |
CheckVaultPassword | This method verifies whether a particular vault password is correct. |
CloseOpenedFilesSnapshot | Closes the previously-created opened files snapshot. |
CloseVault | Closes the vault. |
CompactVault | This method compacts the vault. |
Config | Sets or retrieves a configuration setting. |
ConvertToDrivePath | Converts a vault-local vault item path to a virtual drive file path (Windows only). |
ConvertToVaultPath | Converts a virtual drive file path to a vault-local vault item path (Windows only). |
CreateDirectory | This method creates a new directory in the vault. |
CreateLink | This method creates a symbolic link to another file in the vault. |
CreateOpenedFilesSnapshot | Creates a snapshot of information about files that are currently open. |
DeleteFile | This method deletes a vault item. |
DeleteFileTag | This method deletes a file tag. |
EjectVolume | Ejects a removable storage volume formatted with the CBFS Storage filesystem (Windows only). |
FileExists | This method checks whether a vault item exists. |
FileMatchesMask | This method checks whether a particular file or directory name matches the specified mask. |
FileTagExists | This method checks whether a file tag exists. |
FileTimeToNanoseconds | This method returns the subsecond part of the time expressed in nanoseconds. |
FileTimeToUnixTime | This method converts FileTime to Unix time format. |
FindClose | This method closes a search operation and releases any associated resources. |
FindFirst | This method searches for the first vault item that matches the specified name and attributes. |
FindFirstByQuery | This method searches for the first file or directory whose file tags match the specified query. |
FindNext | This method 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 | This method retrieves the attributes of a vault item. |
GetFileCompression | This method retrieves the compression mode of a file or alternate stream. |
GetFileCreationTime | This method retrieves the creation time of a vault item. |
GetFileEncryption | This method retrieves the encryption mode of a file or alternate stream. |
GetFileLastAccessTime | This method retrieves the last access time of a vault item. |
GetFileModificationTime | This method retrieves the modification time of a vault item. |
GetFileSize | This method retrieves the size of a file or alternate stream. |
GetFileTag | This method retrieves the binary data held by a raw file tag attached to the specified vault item. |
GetFileTagAsAnsiString | This method retrieves the value of an AnsiString-typed file tag attached to the specified vault item. |
GetFileTagAsBoolean | This method retrieves the value of a Boolean-typed file tag attached to the specified vault item. |
GetFileTagAsDateTime | This method retrieves the value of a DateTime-typed file tag attached to the specified vault item. |
GetFileTagAsNumber | This method retrieves the value of a Number-typed file tag attached to the specified vault item. |
GetFileTagAsString | This method retrieves the value of a String-typed file tag attached to the specified vault item. |
GetFileTagDataType | This method retrieves the data type of a typed file tag attached to a specific vault item. |
GetFileTagSize | This method 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 (Windows only). |
GetOriginatorProcessName | Retrieves the name of the process that initiated the operation (Windows only). |
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 | This method retrieves the attributes of a vault item found during a search operation. |
GetSearchResultCreationTime | This method retrieves the creation time of a vault item found during a search operation. |
GetSearchResultFullName | This method retrieves the fully qualified name of a vault item found during a search operation. |
GetSearchResultLastAccessTime | This method retrieves the last access time of a vault item found during a search operation. |
GetSearchResultLinkDestination | This method retrieves the destination of a symbolic link found during a search operation. |
GetSearchResultMetadataSize | This method retrieves the size of the metadata associated with a vault item found during a search operation. |
GetSearchResultModificationTime | This method retrieves the modification time of a vault item found during a search operation. |
GetSearchResultName | This method retrieves the name of a vault item found during a search operation. |
GetSearchResultSize | This method retrieves the size of a vault item found during a search operation. |
Initialize | This method initializes the class. |
Install | Installs (or upgrades) the product's system drivers and/or the helper DLL (Windows only). |
IsDirectoryEmpty | This method checks whether a directory is empty. |
IsIconRegistered | Checks whether the specified icon is registered (Windows only). |
IsValidVault | This method checks whether a local file is a CBFS Storage vault. |
IsValidVaultVolume | Checks whether a storage partition or volume is formatted with the CBFS Storage filesystem (Windows only). |
MoveFile | This method renames or moves a vault item. |
OpenFile | This method opens a new or existing file or alternate stream in the vault. |
OpenFileEx | This method opens a new or existing file or alternate stream in the vault. |
OpenRootData | This method opens the vault's root data stream. |
OpenVault | This method 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 File Explorer (Windows only). |
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 (Windows only). |
ResolveLink | This method retrieves the destination of a symbolic link. |
SetFileAttributes | This method sets the attributes of a vault item. |
SetFileCompression | This method compresses or decompresses a file or alternate stream. |
SetFileCreationTime | This method sets the creation time of a vault item. |
SetFileEncryption | This method encrypts, decrypts, or changes the encryption password of a file or alternate stream. |
SetFileLastAccessTime | This method sets the last access time of a vault item. |
SetFileModificationTime | This method sets the modification time of a vault item. |
SetFileSize | This method sets the size of a file or alternate stream. |
SetFileTag | This method attaches a raw file tag with binary data to the specified vault item. |
SetFileTagAsAnsiString | This method attaches an AnsiString-typed file tag to the specified vault item. |
SetFileTagAsBoolean | This method attaches a Boolean-typed file tag to the specified vault item. |
SetFileTagAsDateTime | This method attaches a DateTime-typed file tag to the specified vault item. |
SetFileTagAsNumber | This method attaches a Number-typed file tag to the specified vault item. |
SetFileTagAsString | This method 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 File Explorer (Windows only). |
ShutdownSystem | Shuts down or reboots the operating system. |
Uninstall | Uninstalls the product's system drivers and/or helper DLL (Windows only). |
UnixTimeToFileTime | This method converts the date/time in Unix format to the Windows FileTime format. |
UnregisterIcon | Unregisters an existing overlay icon (Windows only). |
UpdateVaultEncryption | This method encrypts, 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.
DataCompress | This event fires to compress a block of data using a custom compression algorithm. |
DataDecompress | This event fires to decompress a block of data using a custom compression algorithm. |
DataDecrypt | This event fires to decrypt a block of data using a custom encryption implementation. |
DataEncrypt | This event fires to encrypt a block of data using a custom encryption implementation. |
Ejected | Fires when the media and virtual drive have been ejected (Windows only). |
Error | This event fires if an unhandled error occurs during an event. |
FileAccess | Fires when the OS wants to create or open a file or directory. |
FileAfterCopy | This event fires after the file has been copied during file export/import operations. |
FileBeforeCopy | This event fires before the file is copied during file export/import operations. |
FilePasswordNeeded | This event fires if a password is needed to open an encrypted file. |
HashCalculate | This event fires to calculate a password hash using a custom hashing implementation. |
KeyDerive | This event fires to derive an encryption key using a custom key derivation implementation. |
Progress | This event fires to indicate the progress of long-running vault operations. |
VaultClose | This event fires to close a callback mode vault. |
VaultDelete | This event fires to delete a callback mode vault. |
VaultFlush | This event fires to flush a callback mode vault's data out to storage. |
VaultGetParentSize | This event fires to determine how much free space is available for growing a callback mode vault. |
VaultGetSize | This event fires to determine the size of a callback mode vault. |
VaultOpen | This event fires to open a new or existing callback mode vault. |
VaultRead | This event fires to read data from a callback mode vault. |
VaultSetSize | This event fires to resize a callback mode vault. |
VaultWrite | This event fires to write data to a callback mode vault. |
WorkerThreadCreation | Fires just after a new worker thread is created. |
WorkerThreadTermination | Fires 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.
AllowMoveStreamsBetweenFiles | Whether alternate streams may be moved from one file to another. |
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. |
FireFileAccessEvent | Whether FileAccess event is fired. |
LoggingEnabled | Whether extended logging is enabled. |
MaxNonPagedNameLength | The maximum number of name characters to store directly within a vault item. |
MaxWorkerThreadCount | The maximum number of worker threads to use to fire events. |
MinWorkerThreadCount | The minimum number of worker threads to use to fire events. |
PageCacheSize | The size of the in-memory vault page cache. |
PartSize | The part size used by a multipart vault. |
StorageNamePrefix | The fixed prefix to use in device object names. |
SupportSearchIndexer | Specifies whether the driver must take additional measures to support indexing by Windows Search. |
VolumeGuidName | The GUID of the mounted volume. |
WorkerInitialStackSize | The initial stack size to create worker threads with. |
AccessDeniedProcesses Property (CBVaultDrive Class)
Collection of access rules that define which processes may not access the virtual drive.
Syntax
CBFSStorageList<CBFSStorageProcessAccessRule>* GetAccessDeniedProcesses();
int cbfsstorage_cbvaultdrive_getaccessdeniedprocesscount(void* lpObj);
int cbfsstorage_cbvaultdrive_getaccessdeniedprocessdesiredaccess(void* lpObj, int accessdeniedprocessindex);
int cbfsstorage_cbvaultdrive_getaccessdeniedprocessincludechildren(void* lpObj, int accessdeniedprocessindex);
int cbfsstorage_cbvaultdrive_getaccessdeniedprocessid(void* lpObj, int accessdeniedprocessindex);
char* cbfsstorage_cbvaultdrive_getaccessdeniedprocessname(void* lpObj, int accessdeniedprocessindex);
int GetAccessDeniedProcessCount(); int GetAccessDeniedProcessDesiredAccess(int iAccessDeniedProcessIndex); bool GetAccessDeniedProcessIncludeChildren(int iAccessDeniedProcessIndex); int GetAccessDeniedProcessId(int iAccessDeniedProcessIndex); QString GetAccessDeniedProcessName(int iAccessDeniedProcessIndex);
Remarks
This property holds a collection of ProcessAccessRule objects representing rules that deny processes certain kinds of access to the virtual drive.
Please refer to the AddDeniedProcess and RemoveDeniedProcess methods for more information.
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.
This property is read-only and not available at design time.
Data Type
AccessGrantedProcesses Property (CBVaultDrive Class)
Collection of access rules that define which processes may access the virtual drive.
Syntax
CBFSStorageList<CBFSStorageProcessAccessRule>* GetAccessGrantedProcesses();
int cbfsstorage_cbvaultdrive_getaccessgrantedprocesscount(void* lpObj);
int cbfsstorage_cbvaultdrive_getaccessgrantedprocessdesiredaccess(void* lpObj, int accessgrantedprocessindex);
int cbfsstorage_cbvaultdrive_getaccessgrantedprocessincludechildren(void* lpObj, int accessgrantedprocessindex);
int cbfsstorage_cbvaultdrive_getaccessgrantedprocessid(void* lpObj, int accessgrantedprocessindex);
char* cbfsstorage_cbvaultdrive_getaccessgrantedprocessname(void* lpObj, int accessgrantedprocessindex);
int GetAccessGrantedProcessCount(); int GetAccessGrantedProcessDesiredAccess(int iAccessGrantedProcessIndex); bool GetAccessGrantedProcessIncludeChildren(int iAccessGrantedProcessIndex); int GetAccessGrantedProcessId(int iAccessGrantedProcessIndex); QString GetAccessGrantedProcessName(int iAccessGrantedProcessIndex);
Remarks
This property holds a collection of ProcessAccessRule objects representing rules that grant processes certain kinds of access to the virtual drive.
Please refer to the AddGrantedProcess and RemoveGrantedProcess methods for more information.
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.
This property is read-only and not available at design time.
Data Type
Active Property (CBVaultDrive Class)
Whether a vault has been opened and mounted as a virtual drive.
Syntax
ANSI (Cross Platform) int GetActive(); Unicode (Windows) BOOL GetActive();
int cbfsstorage_cbvaultdrive_getactive(void* lpObj);
bool GetActive();
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 OpenVault or OpenVolume method has been called successfully.
This property is read-only and not available at design time.
Data Type
Boolean
AutoCompactAt Property (CBVaultDrive Class)
This property specifies the free space percentage threshold a vault must reach to be eligible for automatic compaction.
Syntax
ANSI (Cross Platform) int GetAutoCompactAt();
int SetAutoCompactAt(int iAutoCompactAt); Unicode (Windows) INT GetAutoCompactAt();
INT SetAutoCompactAt(INT iAutoCompactAt);
int cbfsstorage_cbvaultdrive_getautocompactat(void* lpObj);
int cbfsstorage_cbvaultdrive_setautocompactat(void* lpObj, int iAutoCompactAt);
int GetAutoCompactAt();
int SetAutoCompactAt(int iAutoCompactAt);
Default Value
25
Remarks
This property specifies the percentage of free space a vault must have, at minimum, 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 CompactVault method for more information about the compacting process.
To guard against excessive automatic compaction operations, applications can set the AutoCompactDelay configuration setting to a nonzero value. Alternatively, this property can be set to 0 to disable automatic compaction completely.
A vault opened in ReadOnly mode will never be compacted, regardless of this property's value.
Note: This property cannot be changed within events.
Data Type
Integer
CallbackMode Property (CBVaultDrive Class)
This property specifies whether the class should operate in callback mode.
Syntax
ANSI (Cross Platform) int GetCallbackMode();
int SetCallbackMode(int bCallbackMode); Unicode (Windows) BOOL GetCallbackMode();
INT SetCallbackMode(BOOL bCallbackMode);
int cbfsstorage_cbvaultdrive_getcallbackmode(void* lpObj);
int cbfsstorage_cbvaultdrive_setcallbackmode(void* lpObj, int bCallbackMode);
bool GetCallbackMode();
int SetCallbackMode(bool bCallbackMode);
Default Value
FALSE
Remarks
This property specifies whether the class should operate in callback mode, causing all vault access to be performed through the following events. Please refer to the Callback Mode topic for more information.
When this property is enabled, the following events must all be implemented for the class to function correctly:
- VaultClose
- VaultDelete
- VaultFlush
- VaultGetParentSize
- VaultGetSize
- VaultOpen
- VaultRead
- VaultSetSize
- VaultWrite
Note: This property cannot be changed when Active is true, and it cannot be changed within events.
Data Type
Boolean
CaseSensitive Property (CBVaultDrive Class)
This property specifies whether the class should open a vault in case-sensitive mode.
Syntax
ANSI (Cross Platform) int GetCaseSensitive();
int SetCaseSensitive(int bCaseSensitive); Unicode (Windows) BOOL GetCaseSensitive();
INT SetCaseSensitive(BOOL bCaseSensitive);
int cbfsstorage_cbvaultdrive_getcasesensitive(void* lpObj);
int cbfsstorage_cbvaultdrive_setcasesensitive(void* lpObj, int bCaseSensitive);
bool GetCaseSensitive();
int SetCaseSensitive(bool bCaseSensitive);
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 it cannot be changed within events.
Data Type
Boolean
DefaultFileAccessPassword Property (CBVaultDrive Class)
This property specifies the default encryption password to use when opening files and alternate streams.
Syntax
ANSI (Cross Platform) char* GetDefaultFileAccessPassword();
int SetDefaultFileAccessPassword(const char* lpszDefaultFileAccessPassword); Unicode (Windows) LPWSTR GetDefaultFileAccessPassword();
INT SetDefaultFileAccessPassword(LPCWSTR lpszDefaultFileAccessPassword);
char* cbfsstorage_cbvaultdrive_getdefaultfileaccesspassword(void* lpObj);
int cbfsstorage_cbvaultdrive_setdefaultfileaccesspassword(void* lpObj, const char* lpszDefaultFileAccessPassword);
QString GetDefaultFileAccessPassword();
int SetDefaultFileAccessPassword(QString qsDefaultFileAccessPassword);
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 CacheFilePassword method (before a file is opened) to specify a one-time-use password or may specify file encryption passwords dynamically using the FilePasswordNeeded event.
Data Type
String
DefaultFileCompression Property (CBVaultDrive Class)
This property specifies the default compression mode to use when creating files and alternate streams.
Syntax
ANSI (Cross Platform) int GetDefaultFileCompression();
int SetDefaultFileCompression(int iDefaultFileCompression); Unicode (Windows) INT GetDefaultFileCompression();
INT SetDefaultFileCompression(INT iDefaultFileCompression);
int cbfsstorage_cbvaultdrive_getdefaultfilecompression(void* lpObj);
int cbfsstorage_cbvaultdrive_setdefaultfilecompression(void* lpObj, int iDefaultFileCompression);
int GetDefaultFileCompression();
int SetDefaultFileCompression(int iDefaultFileCompression);
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 as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress 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.
Data Type
Integer
DefaultFileCreatePassword Property (CBVaultDrive Class)
This property specifies the default encryption password to use when creating new files and alternate streams.
Syntax
ANSI (Cross Platform) char* GetDefaultFileCreatePassword();
int SetDefaultFileCreatePassword(const char* lpszDefaultFileCreatePassword); Unicode (Windows) LPWSTR GetDefaultFileCreatePassword();
INT SetDefaultFileCreatePassword(LPCWSTR lpszDefaultFileCreatePassword);
char* cbfsstorage_cbvaultdrive_getdefaultfilecreatepassword(void* lpObj);
int cbfsstorage_cbvaultdrive_setdefaultfilecreatepassword(void* lpObj, const char* lpszDefaultFileCreatePassword);
QString GetDefaultFileCreatePassword();
int SetDefaultFileCreatePassword(QString qsDefaultFileCreatePassword);
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.
Data Type
String
DefaultFileEncryption Property (CBVaultDrive Class)
This property specifies the default encryption mode to use when creating files and alternate streams.
Syntax
ANSI (Cross Platform) int GetDefaultFileEncryption();
int SetDefaultFileEncryption(int iDefaultFileEncryption); Unicode (Windows) INT GetDefaultFileEncryption();
INT SetDefaultFileEncryption(INT iDefaultFileEncryption);
int cbfsstorage_cbvaultdrive_getdefaultfileencryption(void* lpObj);
int cbfsstorage_cbvaultdrive_setdefaultfileencryption(void* lpObj, int iDefaultFileEncryption);
int GetDefaultFileEncryption();
int SetDefaultFileEncryption(int iDefaultFileEncryption);
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 as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive 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 DefaultFileCreatePassword property.
Data Type
Integer
FileSystemName Property (CBVaultDrive Class)
The name of the virtual filesystem.
Syntax
ANSI (Cross Platform) char* GetFileSystemName();
int SetFileSystemName(const char* lpszFileSystemName); Unicode (Windows) LPWSTR GetFileSystemName();
INT SetFileSystemName(LPCWSTR lpszFileSystemName);
char* cbfsstorage_cbvaultdrive_getfilesystemname(void* lpObj);
int cbfsstorage_cbvaultdrive_setfilesystemname(void* lpObj, const char* lpszFileSystemName);
QString GetFileSystemName();
int SetFileSystemName(QString qsFileSystemName);
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 it cannot be changed within events.
Data Type
String
IsCorrupted Property (CBVaultDrive Class)
This property specifies whether the vault is corrupted.
Syntax
ANSI (Cross Platform) int GetIsCorrupted(); Unicode (Windows) BOOL GetIsCorrupted();
int cbfsstorage_cbvaultdrive_getiscorrupted(void* lpObj);
bool GetIsCorrupted();
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 VaultState property.
The VAULT_ST_CORRUPTED flag is set automatically anytime the class detects that a vault's integrity has been compromised. Calling the CheckAndRepair method for a corrupted vault will clear the flag.
This property is read-only and not available at design time.
Data Type
Boolean
LastWriteTime Property (CBVaultDrive Class)
This property specifies the last modification time of the vault.
Syntax
ANSI (Cross Platform) int64 GetLastWriteTime(); Unicode (Windows) LONG64 GetLastWriteTime();
int64 cbfsstorage_cbvaultdrive_getlastwritetime(void* lpObj);
QDateTime GetLastWriteTime();
Default Value
0
Remarks
This property reflects the vault's last modification time, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
This property is read-only and not available at design time.
Data Type
Long64
Logo Property (CBVaultDrive Class)
This property specifies an application-defined text-based logo stored in the second page of a vault.
Syntax
ANSI (Cross Platform) char* GetLogo();
int SetLogo(const char* lpszLogo); Unicode (Windows) LPWSTR GetLogo();
INT SetLogo(LPCWSTR lpszLogo);
char* cbfsstorage_cbvaultdrive_getlogo(void* lpObj);
int cbfsstorage_cbvaultdrive_setlogo(void* lpObj, const char* lpszLogo);
QString GetLogo();
int SetLogo(QString qsLogo);
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 thus can 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.
Data Type
String
MountingPoints Property (CBVaultDrive Class)
Collection of mounting points for the virtual drive.
Syntax
CBFSStorageList<CBFSStorageMountingPoint>* GetMountingPoints();
int cbfsstorage_cbvaultdrive_getmountingpointcount(void* lpObj);
int64 cbfsstorage_cbvaultdrive_getmountingpointauthenticationid(void* lpObj, int mountingpointindex);
int cbfsstorage_cbvaultdrive_getmountingpointflags(void* lpObj, int mountingpointindex);
char* cbfsstorage_cbvaultdrive_getmountingpointname(void* lpObj, int mountingpointindex);
int GetMountingPointCount(); qint64 GetMountingPointAuthenticationId(int iMountingPointIndex); int GetMountingPointFlags(int iMountingPointIndex); QString GetMountingPointName(int iMountingPointIndex);
Remarks
This property holds a collection of MountingPoint objects, each of which represents an available mounting point for the virtual drive.
Please refer to the AddMountingPoint and RemoveMountingPoint methods for more information.
Note: 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.
This property is read-only and not available at design time.
Data Type
OpenFiles Property (CBVaultDrive Class)
Collection of information about the objects in the virtual drive that are currently open.
Syntax
CBFSStorageList<CBFSStorageOpenFile>* GetOpenFiles();
int cbfsstorage_cbvaultdrive_getopenfilescount(void* lpObj);
char* cbfsstorage_cbvaultdrive_getopenfilename(void* lpObj, int openfileindex);
int cbfsstorage_cbvaultdrive_getopenfileprocessid(void* lpObj, int openfileindex);
char* cbfsstorage_cbvaultdrive_getopenfileprocessname(void* lpObj, int openfileindex);
int GetOpenFilesCount(); QString GetOpenFileName(int iOpenFileIndex); int GetOpenFileProcessId(int iOpenFileIndex); QString GetOpenFileProcessName(int iOpenFileIndex);
Remarks
This property holds a collection of OpenFile objects representing filesystem objects (files, directories, etc.) from the virtual drive that are currently open. The collection is populated anytime CreateOpenedFilesSnapshot is called, and cleared when CloseOpenedFilesSnapshot is called; please refer to those methods for more information.
Note: The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.
This property is read-only and not available at design time.
Data Type
PageSize Property (CBVaultDrive Class)
This property specifies the vault's page size.
Syntax
ANSI (Cross Platform) int GetPageSize();
int SetPageSize(int iPageSize); Unicode (Windows) INT GetPageSize();
INT SetPageSize(INT iPageSize);
int cbfsstorage_cbvaultdrive_getpagesize(void* lpObj);
int cbfsstorage_cbvaultdrive_setpagesize(void* lpObj, int iPageSize);
int GetPageSize();
int SetPageSize(int iPageSize);
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 it cannot be changed within events.
Data Type
Integer
PathSeparator Property (CBVaultDrive Class)
This property specifies the path separator character to use when returning vault paths.
Syntax
ANSI (Cross Platform) int GetPathSeparator();
int SetPathSeparator(int iPathSeparator); Unicode (Windows) INT GetPathSeparator();
INT SetPathSeparator(INT iPathSeparator);
int cbfsstorage_cbvaultdrive_getpathseparator(void* lpObj);
int cbfsstorage_cbvaultdrive_setpathseparator(void* lpObj, int iPathSeparator);
int GetPathSeparator();
int SetPathSeparator(int iPathSeparator);
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 as follows:
VAULT_PSC_BACKSLASH | 92 | Backslash ('\').
This character is the Windows path separator. |
VAULT_PSC_SLASH | 47 | Forward slash ('/').
This character is the Unix-style path separator. |
Note: 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 it cannot be changed within events.
Data Type
Integer
PossibleFreeSpace Property (CBVaultDrive Class)
This property specifies the maximum amount of free space the vault could possibly have available.
Syntax
ANSI (Cross Platform) int64 GetPossibleFreeSpace(); Unicode (Windows) LONG64 GetPossibleFreeSpace();
int64 cbfsstorage_cbvaultdrive_getpossiblefreespace(void* lpObj);
qint64 GetPossibleFreeSpace();
Default Value
0
Remarks
This property reflects the maximum amount of free space, in bytes, that the vault could possibly have available. That is, it is the amount of free space that would be available if the vault automatically grew to its maximum PossibleSize right now, without any additional data being written to it. Therefore:
- If VaultSizeMax is 0 (unlimited): this property is equivalent to VaultFreeSpace + parent_free_space.
- If VaultSizeMax is not 0: this property is equivalent to VaultFreeSpace + min(parent_free_space, (VaultSizeMax - VaultSize)).
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., VaultFile) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides through the VaultGetParentSize event.
Please refer to the Vault Size topic for more information.
This property is read-only and not available at design time.
Data Type
Long64
PossibleSize Property (CBVaultDrive Class)
This property specifies the maximum size the vault could possibly be.
Syntax
ANSI (Cross Platform) int64 GetPossibleSize(); Unicode (Windows) LONG64 GetPossibleSize();
int64 cbfsstorage_cbvaultdrive_getpossiblesize(void* lpObj);
qint64 GetPossibleSize();
Default Value
0
Remarks
This property reflects the maximum size, in bytes, that the vault could possibly be. That is, it 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:
- If VaultSizeMax is 0 (unlimited): this property is equivalent to VaultFreeSpace + parent_free_space.
- If VaultSizeMax is not 0: this property matches VaultSizeMax.
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., VaultFile) resides, as reported by the OS. For a Callback Mode vault, this is whatever value the application provides through the VaultGetParentSize event.
Please refer to the VaultSize topic for more information.
This property is read-only and not available at design time.
Data Type
Long64
ProcessRestrictionsEnabled Property (CBVaultDrive Class)
Whether process access restrictions are enabled.
Syntax
ANSI (Cross Platform) int GetProcessRestrictionsEnabled();
int SetProcessRestrictionsEnabled(int bProcessRestrictionsEnabled); Unicode (Windows) BOOL GetProcessRestrictionsEnabled();
INT SetProcessRestrictionsEnabled(BOOL bProcessRestrictionsEnabled);
int cbfsstorage_cbvaultdrive_getprocessrestrictionsenabled(void* lpObj);
int cbfsstorage_cbvaultdrive_setprocessrestrictionsenabled(void* lpObj, int bProcessRestrictionsEnabled);
bool GetProcessRestrictionsEnabled();
int SetProcessRestrictionsEnabled(bool bProcessRestrictionsEnabled);
Default Value
FALSE
Remarks
This property controls whether the class should enforce per-process access restrictions; by default, it is disabled. When enabled, the AddGrantedProcess and AddDeniedProcess methods can be used to add process-specific access rules for the class to enforce across the entire virtual drive.
When an application enables this propery, it should use the AddGrantedProcess method to add at least one pocess as allowed; otherwise, the data will be inaccessible.
The current process access rules are reflected by the AccessGrantedProcess* and AccessDeniedProcess* properties.
Note: The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.
Data Type
Boolean
ReadOnly Property (CBVaultDrive Class)
This property specifies whether the class should open a vault in read-only mode.
Syntax
ANSI (Cross Platform) int GetReadOnly();
int SetReadOnly(int bReadOnly); Unicode (Windows) BOOL GetReadOnly();
INT SetReadOnly(BOOL bReadOnly);
int cbfsstorage_cbvaultdrive_getreadonly(void* lpObj);
int cbfsstorage_cbvaultdrive_setreadonly(void* lpObj, int bReadOnly);
bool GetReadOnly();
int SetReadOnly(bool bReadOnly);
Default Value
FALSE
Remarks
This property specifies whether the class should open a vault in read-only mode. When a vault is opened in read-only mode, the following restrictions apply:
- No new vault items (e.g., 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 CheckAndRepair.
Note: This list may not necessarily be exhaustive.
Note: This property cannot be changed when Active is true, and it cannot be changed within events.
Data Type
Boolean
ReportPossibleSize Property (CBVaultDrive Class)
How the class should report the virtual drive's size and free space to the OS.
Syntax
ANSI (Cross Platform) int GetReportPossibleSize();
int SetReportPossibleSize(int bReportPossibleSize); Unicode (Windows) BOOL GetReportPossibleSize();
INT SetReportPossibleSize(BOOL bReportPossibleSize);
int cbfsstorage_cbvaultdrive_getreportpossiblesize(void* lpObj);
int cbfsstorage_cbvaultdrive_setreportpossiblesize(void* lpObj, int bReportPossibleSize);
bool GetReportPossibleSize();
int SetReportPossibleSize(bool bReportPossibleSize);
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 PossibleSize and PossibleFreeSpace properties. When this property is disabled, the class will use the values of the VaultSize and PossibleSize 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 VaultSizeMin and VaultSizeMax 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.
Data Type
Boolean
SerializeEvents Property (CBVaultDrive Class)
Whether events should be fired on a single worker thread, or many.
Syntax
ANSI (Cross Platform) int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents); Unicode (Windows) INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);
Possible Values
SE_ON_MULTIPLE_THREADS(0),
SE_ON_ONE_WORKER_THREAD(1)
int cbfsstorage_cbvaultdrive_getserializeevents(void* lpObj);
int cbfsstorage_cbvaultdrive_setserializeevents(void* lpObj, int iSerializeEvents);
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);
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 it cannot be changed within events.
Data Type
Integer
StorageCharacteristics Property (CBVaultDrive Class)
The characteristic flags to create the virtual drive with (Windows only).
Syntax
ANSI (Cross Platform) int GetStorageCharacteristics();
int SetStorageCharacteristics(int iStorageCharacteristics); Unicode (Windows) INT GetStorageCharacteristics();
INT SetStorageCharacteristics(INT iStorageCharacteristics);
int cbfsstorage_cbvaultdrive_getstoragecharacteristics(void* lpObj);
int cbfsstorage_cbvaultdrive_setstoragecharacteristics(void* lpObj, int iStorageCharacteristics);
int GetStorageCharacteristics();
int SetStorageCharacteristics(int iStorageCharacteristics);
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_DISKETTE | 0x00000001 | The storage is a floppy disk device.
This flag is not supported when StorageType is set to STGT_DISK_PNP. |
STGC_READONLY_DEVICE | 0x00000002 | The storage is a read-only device. |
STGC_WRITE_ONCE_MEDIA | 0x00000008 | The storage device's media can only be written to once.
This flag is not supported when StorageType is set to STGT_DISK_PNP. |
STGC_REMOVABLE_MEDIA | 0x00000010 | The 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_LETTER | 0x00002000 | The 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 AddMountingPoint method's Flags parameter instead. When this flag is present, the StorageGUID property must be set. This flag only works when StorageType is set to STGT_DISK_PNP. |
STGC_SHOW_IN_EJECTION_TRAY | 0x00004000 | The 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 StorageType is set to STGT_DISK_PNP. |
STGC_ALLOW_EJECTION | 0x00008000 | The 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 StorageType is set to STGT_DISK_PNP. |
STGC_RESERVED_1 | 0x00010000 | Reserved, do not use. |
STGC_RESERVED_2 | 0x00020000 | Reserved, do not use. |
Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.
Data Type
Integer
StorageGUID Property (CBVaultDrive Class)
The GUID to create the virtual drive with.
Syntax
ANSI (Cross Platform) char* GetStorageGUID();
int SetStorageGUID(const char* lpszStorageGUID); Unicode (Windows) LPWSTR GetStorageGUID();
INT SetStorageGUID(LPCWSTR lpszStorageGUID);
char* cbfsstorage_cbvaultdrive_getstorageguid(void* lpObj);
int cbfsstorage_cbvaultdrive_setstorageguid(void* lpObj, const char* lpszStorageGUID);
QString GetStorageGUID();
int SetStorageGUID(QString qsStorageGUID);
Default Value
""
Remarks
This property is used to specify a GUID for the virtual drive, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property may be left empty; in the latter case, the driver will generate a unique value when a drive is mounted.
Some software uses a drive's GUID for the purpose of setting and maintaining certain configuration parameters. Therefore, applications are expected to use the same GUID when repeatedly creating a virtual drive that represents the same data.
In multiuser environments (Terminal Server, Citrix and similar software) where the application may be run concurrently by different users, using the same GUID for all users will cause a name conflict. To avoid it, mix the constant GUID value with the user-unique information such as the hash of the username or SID. This way, each user will use a constant but distinct GUID for their virtual drive.
Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.
Data Type
String
StorageType Property (CBVaultDrive Class)
The type of virtual drive to create (Windows only).
Syntax
ANSI (Cross Platform) int GetStorageType();
int SetStorageType(int iStorageType); Unicode (Windows) INT GetStorageType();
INT SetStorageType(INT iStorageType);
int cbfsstorage_cbvaultdrive_getstoragetype(void* lpObj);
int cbfsstorage_cbvaultdrive_setstoragetype(void* lpObj, int iStorageType);
int GetStorageType();
int SetStorageType(int iStorageType);
Default Value
0
Remarks
This property specifies what type of virtual drive should be created. Windows File Explorer uses this information to display the appropriate icon and apply the appropriate security settings for the virtual drive. Other applications may also make use of this information in various ways.
Possible values are:
STGT_DISK | 0x00000000 | Create a regular disk device. |
STGT_CDROM | 0x00000001 | Create a CD-ROM or DVD device. |
STGT_DISK_PNP | 0x00000003 | Create a plug-and-play storage device.
Important: The PNP Bus system driver must be installed in PnP mode for this option to function properly; this is done by specifying the corresponding constant in a call to the Install method. |
Note: This property cannot be changed after a virtual drive is created, and it cannot be changed within events.
Plug-and-play Virtual Drives
Virtual drives created as plug-and-play (STGT_DISK_PNP) require that a "physical device" be visible in the Disk Manager snap-in of the Microsoft Management Console (mmc.exe). This can be accomplished by calling the AddMountingPoint method and including the STGMP_MOUNT_MANAGER flag in the value passed for its Flags parameter.
In addition to supporting the STGC_REMOVABLE_MEDIA StorageCharacteristics flag, which specifies whether a virtual drive's media is removable or non-removable, plug-and-play virtual drives also support the STGC_ALLOW_EJECTION flag, which specifies whether a virtual drive itself is removable or non-removable.
Data Type
Integer
Tag Property (CBVaultDrive Class)
This property stores application-defined data specific to a particular instance of the class.
Syntax
ANSI (Cross Platform) int64 GetTag();
int SetTag(int64 lTag); Unicode (Windows) LONG64 GetTag();
INT SetTag(LONG64 lTag);
int64 cbfsstorage_cbvaultdrive_gettag(void* lpObj);
int cbfsstorage_cbvaultdrive_settag(void* lpObj, int64 lTag);
qint64 GetTag();
int SetTag(qint64 lTag);
Default Value
0
Remarks
This property can be used to store data specific to a particular instance of the class.
Data Type
Long64
Timeout Property (CBVaultDrive Class)
How long vault events may execute before timing out (Windows only).
Syntax
ANSI (Cross Platform) int GetTimeout();
int SetTimeout(int iTimeout); Unicode (Windows) INT GetTimeout();
INT SetTimeout(INT iTimeout);
int cbfsstorage_cbvaultdrive_gettimeout(void* lpObj);
int cbfsstorage_cbvaultdrive_settimeout(void* lpObj, int iTimeout);
int GetTimeout();
int SetTimeout(int iTimeout);
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.
Data Type
Integer
UnmountOnTermination Property (CBVaultDrive Class)
Whether the virtual drive should be unmounted if the application terminates (Windows only).
Syntax
ANSI (Cross Platform) int GetUnmountOnTermination();
int SetUnmountOnTermination(int bUnmountOnTermination); Unicode (Windows) BOOL GetUnmountOnTermination();
INT SetUnmountOnTermination(BOOL bUnmountOnTermination);
int cbfsstorage_cbvaultdrive_getunmountontermination(void* lpObj);
int cbfsstorage_cbvaultdrive_setunmountontermination(void* lpObj, int bUnmountOnTermination);
bool GetUnmountOnTermination();
int SetUnmountOnTermination(bool bUnmountOnTermination);
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 ForceUnmount 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.
Data Type
Boolean
UseAccessTime Property (CBVaultDrive Class)
This property specifies whether the class should keep track of last access times for vault items.
Syntax
ANSI (Cross Platform) int GetUseAccessTime();
int SetUseAccessTime(int bUseAccessTime); Unicode (Windows) BOOL GetUseAccessTime();
INT SetUseAccessTime(BOOL bUseAccessTime);
int cbfsstorage_cbvaultdrive_getuseaccesstime(void* lpObj);
int cbfsstorage_cbvaultdrive_setuseaccesstime(void* lpObj, int bUseAccessTime);
bool GetUseAccessTime();
int SetUseAccessTime(bool bUseAccessTime);
Default Value
FALSE
Remarks
This property specifies whether the class should update the last access time for vault items (e.g., files, directories, symbolic links, and alternate streams) every time they are accessed.
Note: Keeping track of access times will slow down operations.
Note: This property cannot be changed when Active is true, and it cannot be changed within events.
Data Type
Boolean
UseSystemCache Property (CBVaultDrive Class)
This property specifies whether the operating system's cache is used.
Syntax
ANSI (Cross Platform) int GetUseSystemCache();
int SetUseSystemCache(int bUseSystemCache); Unicode (Windows) BOOL GetUseSystemCache();
INT SetUseSystemCache(BOOL bUseSystemCache);
int cbfsstorage_cbvaultdrive_getusesystemcache(void* lpObj);
int cbfsstorage_cbvaultdrive_setusesystemcache(void* lpObj, int bUseSystemCache);
bool GetUseSystemCache();
int SetUseSystemCache(bool bUseSystemCache);
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, 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 VaultFile 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 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 it cannot be changed within events.
Data Type
Boolean
VaultEncryption Property (CBVaultDrive Class)
This property specifies the whole-vault encryption mode.
Syntax
ANSI (Cross Platform) int GetVaultEncryption();
int SetVaultEncryption(int iVaultEncryption); Unicode (Windows) INT GetVaultEncryption();
INT SetVaultEncryption(INT iVaultEncryption);
int cbfsstorage_cbvaultdrive_getvaultencryption(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultencryption(void* lpObj, int iVaultEncryption);
int GetVaultEncryption();
int SetVaultEncryption(int iVaultEncryption);
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 as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive 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 VaultPassword property must be set as well.
When an existing vault is opened, the class updates VaultEncryption 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 VaultPassword. If VaultPassword is incorrect, the attempt will fail and the vault will not be opened.
The VaultEncryption and VaultPassword properties cannot be used to change an open vault's whole-vault encryption mode or password; use the UpdateVaultEncryption method.
Please refer to the Encryption topic for more information.
Note: This property cannot be changed when Active is true, and it cannot be changed within events.
Data Type
Integer
VaultFile Property (CBVaultDrive Class)
This property specifies the vault to create or open.
Syntax
ANSI (Cross Platform) char* GetVaultFile();
int SetVaultFile(const char* lpszVaultFile); Unicode (Windows) LPWSTR GetVaultFile();
INT SetVaultFile(LPCWSTR lpszVaultFile);
char* cbfsstorage_cbvaultdrive_getvaultfile(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultfile(void* lpObj, const char* lpszVaultFile);
QString GetVaultFile();
int SetVaultFile(QString qsVaultFile);
Default Value
""
Remarks
This property specifies the vault to create or open when the OpenVault method is called.
When the CallbackMode property is disabled (default), this property specifies the vault storage file to create or open. It must be set to a fully qualified file path formatted according to OS conventions.
When the CallbackMode property is enabled, this property is only used to populate the Vault parameter of the VaultOpen, VaultGetParentSize, and VaultDelete 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 it cannot be changed within events.
Data Type
String
VaultFreeSpace Property (CBVaultDrive Class)
This property reflects the actual amount of free space the vault has available.
Syntax
ANSI (Cross Platform) int64 GetVaultFreeSpace(); Unicode (Windows) LONG64 GetVaultFreeSpace();
int64 cbfsstorage_cbvaultdrive_getvaultfreespace(void* lpObj);
qint64 GetVaultFreeSpace();
Default Value
0
Remarks
This property reflects the actual amount of free space, in bytes, that the vault currently has available. A vault's actual free space is based on its actual size, which is reflected by the VaultSize property.
Applications can also determine the maximum amount of free space the vault could possibly have by querying the PossibleFreeSpace property; please refer to its documentation, as well as the Vault Size topic, for more information.
This property is read-only and not available at design time.
Data Type
Long64
VaultPassword Property (CBVaultDrive Class)
This property specifies the whole-vault encryption password.
Syntax
ANSI (Cross Platform) char* GetVaultPassword();
int SetVaultPassword(const char* lpszVaultPassword); Unicode (Windows) LPWSTR GetVaultPassword();
INT SetVaultPassword(LPCWSTR lpszVaultPassword);
char* cbfsstorage_cbvaultdrive_getvaultpassword(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultpassword(void* lpObj, const char* lpszVaultPassword);
QString GetVaultPassword();
int SetVaultPassword(QString qsVaultPassword);
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 VaultEncryption property must be set as well.
When an existing vault is opened, the class updates VaultEncryption 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 VaultPassword. If VaultPassword is incorrect, the attempt will fail and the vault will not be opened.
The VaultEncryption and VaultPassword properties cannot be used to change an open vault's whole-vault encryption mode or password; use the UpdateVaultEncryption method.
Please refer to the Encryption topic for more information.
Note: This property cannot be changed when Active is true, and it cannot be changed within events.
Data Type
String
VaultSize Property (CBVaultDrive Class)
This property specifies the actual size of the vault.
Syntax
ANSI (Cross Platform) int64 GetVaultSize();
int SetVaultSize(int64 lVaultSize); Unicode (Windows) LONG64 GetVaultSize();
INT SetVaultSize(LONG64 lVaultSize);
int64 cbfsstorage_cbvaultdrive_getvaultsize(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultsize(void* lpObj, int64 lVaultSize);
qint64 GetVaultSize();
int SetVaultSize(qint64 lVaultSize);
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 VaultFreeSpace bytes).
- A vault cannot shrink beyond VaultSizeMin bytes.
- If VaultSizeMax is not 0 (unlimited), a vault cannot grow beyond VaultSizeMax bytes.
- If a vault grows enough to reach or exceed its AutoCompactAt threshold, it will automatically shrink again when the next automatic compaction occurs.
Applications can determine the maximum size a vault could possibly be by querying the PossibleSize property. Please refer to the Vault Size topic for more information.
Note: This property can be changed only when Active is true, and it cannot be changed within events.
This property is not available at design time.
Data Type
Long64
VaultSizeMax Property (CBVaultDrive Class)
This property specifies the maximum size a vault can be.
Syntax
ANSI (Cross Platform) int64 GetVaultSizeMax();
int SetVaultSizeMax(int64 lVaultSizeMax); Unicode (Windows) LONG64 GetVaultSizeMax();
INT SetVaultSizeMax(LONG64 lVaultSizeMax);
int64 cbfsstorage_cbvaultdrive_getvaultsizemax(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultsizemax(void* lpObj, int64 lVaultSizeMax);
qint64 GetVaultSizeMax();
int SetVaultSizeMax(qint64 lVaultSizeMax);
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 * PageSize or VaultSizeMin (whichever is greater).
The limit imposed by this property, if any, applies to both explicit growth of a vault via the VaultSize 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.
Data Type
Long64
VaultSizeMin Property (CBVaultDrive Class)
This property specifies the minimum size a vault can be.
Syntax
ANSI (Cross Platform) int64 GetVaultSizeMin();
int SetVaultSizeMin(int64 lVaultSizeMin); Unicode (Windows) LONG64 GetVaultSizeMin();
INT SetVaultSizeMin(LONG64 lVaultSizeMin);
int64 cbfsstorage_cbvaultdrive_getvaultsizemin(void* lpObj);
int cbfsstorage_cbvaultdrive_setvaultsizemin(void* lpObj, int64 lVaultSizeMin);
qint64 GetVaultSizeMin();
int SetVaultSizeMin(qint64 lVaultSizeMin);
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 VaultSizeMax, unless VaultSizeMax is set to 0 (unlimited).
The limit imposed by this property applies to both explicit shrinking of a vault via the VaultSize property or the CompactVault 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.
Data Type
Long64
VaultState Property (CBVaultDrive Class)
This property specifies information about the state of the vault.
Syntax
ANSI (Cross Platform) int GetVaultState(); Unicode (Windows) INT GetVaultState();
int cbfsstorage_cbvaultdrive_getvaultstate(void* lpObj);
int GetVaultState();
Default Value
0
Remarks
This property reflects the current state of the vault; its value consists of one or more of the following flags, ORed together:
VAULT_ST_FIXED_SIZE | 0x00000001 | The vault is a fixed size. |
VAULT_ST_READ_ONLY | 0x00000002 | The vault was opened in read-only mode.
Please refer to the ReadOnly property for more information. |
VAULT_ST_CORRUPTED | 0x00000004 | The vault is corrupted.
Applications can use the CheckAndRepair method to try to repair vault corruption. Please refer to the Vault Corruption topic for more information. |
VAULT_ST_TRANSACTIONS_USED | 0x00000008 | The vault was opened in journaling mode.
Please refer to the UseJournaling property for more information. |
VAULT_ST_ACCESS_TIME_USED | 0x00000010 | Last access times are being tracked.
Please refer to the UseAccessTime property for more information. |
VAULT_ST_ENCRYPTED | 0x00000020 | The vault is encrypted with whole-vault encryption.
Please refer to the Encryption topic for more information. |
VAULT_ST_VALID_PASSWORD_SET | 0x00000040 | The correct whole-vault encryption password has been provided.
Please refer to the Encryption topic for more information. |
VAULT_ST_PHYSICAL_VOLUME | 0x00000080 | The 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_PARTED | 0x00000100 | The 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 and not available at design time.
Data Type
Integer
AddDeniedProcess Method (CBVaultDrive Class)
Adds a rule that prevents a process from accessing the virtual drive .
Syntax
ANSI (Cross Platform) int AddDeniedProcess(const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess); Unicode (Windows) INT AddDeniedProcess(LPCWSTR lpszProcessFileName, INT iProcessId, BOOL bChildProcesses, INT iDesiredAccess);
int cbfsstorage_cbvaultdrive_adddeniedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);
int AddDeniedProcess(const QString& qsProcessFileName, int iProcessId, bool bChildProcesses, int iDesiredAccess);
Remarks
When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that denies the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.
Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full file name of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.
ChildProcesses controls whether the rule also applies to children of the target process.
DesiredAccess specifies the access right to deny; valid values are:
STG_DACCESS_READ | 0x00000001 | Grant/deny read access. |
STG_DACCESS_WRITE | 0x00000002 | Grant/deny write access. |
STG_DACCESS_READWRITE | 0x00000003 | Grant/deny read and write access. |
To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveDeniedProcess method.
Note: This method can be called only when Active is true, and it cannot be called within events.
The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
AddGrantedProcess Method (CBVaultDrive Class)
Adds a rule that allows a process to access the virtual drive .
Syntax
ANSI (Cross Platform) int AddGrantedProcess(const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess); Unicode (Windows) INT AddGrantedProcess(LPCWSTR lpszProcessFileName, INT iProcessId, BOOL bChildProcesses, INT iDesiredAccess);
int cbfsstorage_cbvaultdrive_addgrantedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId, int bChildProcesses, int iDesiredAccess);
int AddGrantedProcess(const QString& qsProcessFileName, int iProcessId, bool bChildProcesses, int iDesiredAccess);
Remarks
When the ProcessRestrictionsEnabled property is enabled, this method can be used to add an access rule that grants the process specified by ProcessFileName or ProcessId the access right specified by DesiredAccess.
Processes that are already running can be specified by passing their process Id (PID) for the ProcessId parameter (in which case ProcessFileName should be empty). Processes that have not yet started can be specified by passing the full file name of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.
ChildProcesses controls whether the rule also applies to children of the target process.
DesiredAccess specifies the access right to grant; valid values are:
STG_DACCESS_READ | 0x00000001 | Grant/deny read access. |
STG_DACCESS_WRITE | 0x00000002 | Grant/deny write access. |
STG_DACCESS_READWRITE | 0x00000003 | Grant/deny read and write access. |
To remove the process access rule later, pass the same ProcessFileName and ProcessId values to the RemoveGrantedProcess method.
Note: This method can be called only when Active is true, and it cannot be called within events.
The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
AddMountingPoint Method (CBVaultDrive Class)
Adds a mounting point for the virtual drive.
Syntax
ANSI (Cross Platform) int AddMountingPoint(const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId); Unicode (Windows) INT AddMountingPoint(LPCWSTR lpszMountingPoint, INT iFlags, LONG64 lAuthenticationId);
int cbfsstorage_cbvaultdrive_addmountingpoint(void* lpObj, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);
int AddMountingPoint(const QString& qsMountingPoint, int iFlags, qint64 lAuthenticationId);
Remarks
This method adds a new mounting point for the virtual drive (which must have already been created using OpenVault). 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_SIMPLE | 0x00010000 | Create 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_MANAGER | 0x00020000 | Create a mounting point that appears to the system as a physical device.
When the StorageType 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_NETWORK | 0x00040000 | Create a network mounting point.
Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows File Explorer will not correctly recognize the "network" drive. This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER. |
STGMP_LOCAL | 0x10000000 | Specifies 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 AddMountingPoint 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_DRIVE | 0x00000001 | Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows File Explorer). |
STGMP_NETWORK_HIDDEN_SHARE | 0x00000002 | Indicates 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_ACCESS | 0x00000004 | Makes 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_ACCESS | 0x00000008 | Makes 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_NAME | 0x00000010 | Specifies 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_ASYNC | 0x20000000 | Causes the method to return immediately without waiting for mounting notifications to be sent to the system. |
STGMP_AUTOCREATE_DRIVE_LETTER | 0x40000000 | Tells 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. |
Linux and macOS:
STGMP_LOCAL_FUSE | 0x10000000 | Creates a mounting point, accessible only for current user.
If this flag is not passed, the "-oallow_other" option of FUSE is used. |
STGMP_SYMLINK_DEBUG | 0x40000000 | Prints debug messages to stderr
The messages generated by the class are printed. |
STGMP_SYMLINK_SYSTEM_DEBUG | 0x20000000 | Prints debug messages generated by the FUSE library to stderr |
STGMP_NETWORK_MACOS | 0x00040000 | Create 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 OpenVault (CBVaultDrive) or CreateVault 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 AddMountingPoint 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.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CacheFilePassword Method (CBVaultDrive Class)
This method caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password.
Syntax
ANSI (Cross Platform) int CacheFilePassword(const char* lpszFileName, const char* lpszPassword, int iTTLInCache, int bRemoveFromCache); Unicode (Windows) INT CacheFilePassword(LPCWSTR lpszFileName, LPCWSTR lpszPassword, INT iTTLInCache, BOOL bRemoveFromCache);
int cbfsstorage_cbvaultdrive_cachefilepassword(void* lpObj, const char* lpszFileName, const char* lpszPassword, int iTTLInCache, int bRemoveFromCache);
int CacheFilePassword(const QString& qsFileName, const QString& qsPassword, int iTTLInCache, bool bRemoveFromCache);
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 fails with an error.
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 DefaultFileAccessPassword property or provide such passwords dynamically using the FilePasswordNeeded event.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CheckAndRepair Method (CBVaultDrive Class)
This method checks a vault's consistency and repairs it as necessary.
Syntax
ANSI (Cross Platform) int CheckAndRepair(int iFlags); Unicode (Windows) INT CheckAndRepair(INT iFlags);
int cbfsstorage_cbvaultdrive_checkandrepair(void* lpObj, int iFlags);
int CheckAndRepair(int iFlags);
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 IsCorrupted 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, because 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 it should be set by ORing together zero or more of the following flags:
VAULT_CR_CHECK_ONLY | 0x00000001 | Check only, do not attempt any repairs. |
VAULT_CR_CHECK_ALL_PAGES | 0x00000002 | Check all vault pages, including empty ones.
When this flag is not present, only the vault pages that are marked as occupied are checked. |
Note: This method cannot be called when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CheckFilePassword Method (CBVaultDrive Class)
This method verifies whether a particular file password is correct.
Syntax
ANSI (Cross Platform) bool CheckFilePassword(const char* lpszFileName, const char* lpszPassword); Unicode (Windows) bool CheckFilePassword(LPCWSTR lpszFileName, LPCWSTR lpszPassword);
bool cbfsstorage_cbvaultdrive_checkfilepassword(void* lpObj, const char* lpszFileName, const char* lpszPassword);
bool CheckFilePassword(const QString& qsFileName, const QString& qsPassword);
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 be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
CheckVaultPassword Method (CBVaultDrive Class)
This method verifies whether a particular vault password is correct.
Syntax
ANSI (Cross Platform) bool CheckVaultPassword(const char* lpszPassword); Unicode (Windows) bool CheckVaultPassword(LPCWSTR lpszPassword);
bool cbfsstorage_cbvaultdrive_checkvaultpassword(void* lpObj, const char* lpszPassword);
bool CheckVaultPassword(const QString& qsPassword);
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 be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
CloseOpenedFilesSnapshot Method (CBVaultDrive Class)
Closes the previously-created opened files snapshot.
Syntax
ANSI (Cross Platform) int CloseOpenedFilesSnapshot(); Unicode (Windows) INT CloseOpenedFilesSnapshot();
int cbfsstorage_cbvaultdrive_closeopenedfilessnapshot(void* lpObj);
int CloseOpenedFilesSnapshot();
Remarks
This method closes the opened files snapshot previously created by CreateOpenedFilesSnapshot, 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.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CloseVault Method (CBVaultDrive Class)
Closes the vault.
Syntax
ANSI (Cross Platform) int CloseVault(int bForce); Unicode (Windows) INT CloseVault(BOOL bForce);
int cbfsstorage_cbvaultdrive_closevault(void* lpObj, int bForce);
int CloseVault(bool bForce);
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 be called only when Active is true.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CompactVault Method (CBVaultDrive Class)
This method compacts the vault.
Syntax
ANSI (Cross Platform) bool CompactVault(); Unicode (Windows) bool CompactVault();
bool cbfsstorage_cbvaultdrive_compactvault(void* lpObj);
bool CompactVault();
Remarks
This method triggers vault compaction, which is 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 is 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 AutoCompactAt property. Applications can also use the AutoCompactDelay configuration setting to add a delay to the automatic compaction trigger.
Note: A vault opened in ReadOnly mode cannot be compacted, either automatically or explicitly.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
Config Method (CBVaultDrive Class)
Sets or retrieves a configuration setting.
Syntax
ANSI (Cross Platform) char* Config(const char* lpszConfigurationString); Unicode (Windows) LPWSTR Config(LPCWSTR lpszConfigurationString);
char* cbfsstorage_cbvaultdrive_config(void* lpObj, const char* lpszConfigurationString);
QString Config(const QString& qsConfigurationString);
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.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
ConvertToDrivePath Method (CBVaultDrive Class)
Converts a vault-local vault item path to a virtual drive file path (Windows only).
Syntax
ANSI (Cross Platform) char* ConvertToDrivePath(const char* lpszVaultFilePath); Unicode (Windows) LPWSTR ConvertToDrivePath(LPCWSTR lpszVaultFilePath);
char* cbfsstorage_cbvaultdrive_converttodrivepath(void* lpObj, const char* lpszVaultFilePath);
QString ConvertToDrivePath(const QString& qsVaultFilePath);
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 be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
ConvertToVaultPath Method (CBVaultDrive Class)
Converts a virtual drive file path to a vault-local vault item path (Windows only).
Syntax
ANSI (Cross Platform) char* ConvertToVaultPath(const char* lpszVirtualFilePath); Unicode (Windows) LPWSTR ConvertToVaultPath(LPCWSTR lpszVirtualFilePath);
char* cbfsstorage_cbvaultdrive_converttovaultpath(void* lpObj, const char* lpszVirtualFilePath);
QString ConvertToVaultPath(const QString& qsVirtualFilePath);
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 be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
CreateDirectory Method (CBVaultDrive Class)
This method creates a new directory in the vault.
Syntax
ANSI (Cross Platform) int CreateDirectory(const char* lpszDirectory, int bCreateParents); Unicode (Windows) INT CreateDirectory(LPCWSTR lpszDirectory, BOOL bCreateParents);
int cbfsstorage_cbvaultdrive_createdirectory(void* lpObj, const char* lpszDirectory, int bCreateParents);
int CreateDirectory(const QString& qsDirectory, bool bCreateParents);
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 nonexistent 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 fails with an error.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CreateLink Method (CBVaultDrive Class)
This method creates a symbolic link to another file in the vault.
Syntax
ANSI (Cross Platform) int CreateLink(const char* lpszLinkName, const char* lpszDestinationName); Unicode (Windows) INT CreateLink(LPCWSTR lpszLinkName, LPCWSTR lpszDestinationName);
int cbfsstorage_cbvaultdrive_createlink(void* lpObj, const char* lpszLinkName, const char* lpszDestinationName);
int CreateLink(const QString& qsLinkName, const QString& qsDestinationName);
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 it may be absolute or relative to LinkName.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
CreateOpenedFilesSnapshot Method (CBVaultDrive Class)
Creates a snapshot of information about files that are currently open.
Syntax
ANSI (Cross Platform) int CreateOpenedFilesSnapshot(); Unicode (Windows) INT CreateOpenedFilesSnapshot();
int cbfsstorage_cbvaultdrive_createopenedfilessnapshot(void* lpObj);
int CreateOpenedFilesSnapshot();
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 CloseOpenedFilesSnapshot 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 be called only when Active is true, and it cannot be called within events.
The methods and properties related to open files snapshots are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that creation, use, and cleanup of open files snapshots occurs in a thread-safe manner.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
DeleteFile Method (CBVaultDrive Class)
This method deletes a vault item.
Syntax
ANSI (Cross Platform) int DeleteFile(const char* lpszFileName); Unicode (Windows) INT DeleteFile(LPCWSTR lpszFileName);
int cbfsstorage_cbvaultdrive_deletefile(void* lpObj, const char* lpszFileName);
int DeleteFile(const QString& qsFileName);
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 the following:
- When a file is deleted, any alternate streams it contains are deleted as well.
- Directories must be empty to be deleted; otherwise, this method fails with an error. Use the IsDirectoryEmpty 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
DeleteFileTag Method (CBVaultDrive Class)
This method deletes a file tag.
Syntax
ANSI (Cross Platform) int DeleteFileTag(const char* lpszFileName, int iTagId, const char* lpszTagName); Unicode (Windows) INT DeleteFileTag(LPCWSTR lpszFileName, INT iTagId, LPCWSTR lpszTagName);
int cbfsstorage_cbvaultdrive_deletefiletag(void* lpObj, const char* lpszFileName, int iTagId, const char* lpszTagName);
int DeleteFileTag(const QString& qsFileName, int iTagId, const QString& qsTagName);
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 an 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 fails with an error.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
EjectVolume Method (CBVaultDrive Class)
Ejects a removable storage volume formatted with the CBFS Storage filesystem (Windows only).
Syntax
ANSI (Cross Platform) int EjectVolume(int bForce); Unicode (Windows) INT EjectVolume(BOOL bForce);
int cbfsstorage_cbvaultdrive_ejectvolume(void* lpObj, int bForce);
int EjectVolume(bool bForce);
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 OpenVolume 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 File 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
FileExists Method (CBVaultDrive Class)
This method checks whether a vault item exists.
Syntax
ANSI (Cross Platform) bool FileExists(const char* lpszFileName); Unicode (Windows) bool FileExists(LPCWSTR lpszFileName);
bool cbfsstorage_cbvaultdrive_fileexists(void* lpObj, const char* lpszFileName);
bool FileExists(const QString& qsFileName);
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 be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FileMatchesMask Method (CBVaultDrive Class)
This method checks whether a particular file or directory name matches the specified mask.
Syntax
ANSI (Cross Platform) bool FileMatchesMask(const char* lpszMask, const char* lpszFileName, int bCaseSensitive); Unicode (Windows) bool FileMatchesMask(LPCWSTR lpszMask, LPCWSTR lpszFileName, BOOL bCaseSensitive);
bool cbfsstorage_cbvaultdrive_filematchesmask(void* lpObj, const char* lpszMask, const char* lpszFileName, int bCaseSensitive);
bool FileMatchesMask(const QString& qsMask, const QString& qsFileName, bool bCaseSensitive);
Remarks
This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.
Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.
Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FileTagExists Method (CBVaultDrive Class)
This method checks whether a file tag exists.
Syntax
ANSI (Cross Platform) bool FileTagExists(const char* lpszFileName, int iTagId, const char* lpszTagName); Unicode (Windows) bool FileTagExists(LPCWSTR lpszFileName, INT iTagId, LPCWSTR lpszTagName);
bool cbfsstorage_cbvaultdrive_filetagexists(void* lpObj, const char* lpszFileName, int iTagId, const char* lpszTagName);
bool FileTagExists(const QString& qsFileName, int iTagId, const QString& qsTagName);
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 an 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 fails with an error.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FileTimeToNanoseconds Method (CBVaultDrive Class)
This method returns the subsecond part of the time expressed in nanoseconds.
Syntax
ANSI (Cross Platform) int FileTimeToNanoseconds(int64 lFileTime); Unicode (Windows) INT FileTimeToNanoseconds(LONG64 lFileTime);
int cbfsstorage_cbvaultdrive_filetimetonanoseconds(void* lpObj, int64 lFileTime);
int FileTimeToNanoseconds(QDateTime qdtFileTime);
Remarks
Use this method to obtain the subsecond part of the FileTime value, expressed in nanoseconds.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FileTimeToUnixTime Method (CBVaultDrive Class)
This method converts FileTime to Unix time format.
Syntax
ANSI (Cross Platform) int64 FileTimeToUnixTime(int64 lFileTime); Unicode (Windows) LONG64 FileTimeToUnixTime(LONG64 lFileTime);
int64 cbfsstorage_cbvaultdrive_filetimetounixtime(void* lpObj, int64 lFileTime);
qint64 FileTimeToUnixTime(QDateTime qdtFileTime);
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 FileTimeToNanoseconds method.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FindClose Method (CBVaultDrive Class)
This method closes a search operation and releases any associated resources.
Syntax
ANSI (Cross Platform) int FindClose(int64 lSearchId); Unicode (Windows) INT FindClose(LONG64 lSearchId);
int cbfsstorage_cbvaultdrive_findclose(void* lpObj, int64 lSearchId);
int FindClose(qint64 lSearchId);
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 FindFirst or FindFirstByQuery.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
FindFirst Method (CBVaultDrive Class)
This method searches for the first vault item that matches the specified name and attributes.
Syntax
ANSI (Cross Platform) int64 FindFirst(const char* lpszFileMask, int iAttributes, int iFlags); Unicode (Windows) LONG64 FindFirst(LPCWSTR lpszFileMask, INT iAttributes, INT iFlags);
int64 cbfsstorage_cbvaultdrive_findfirst(void* lpObj, const char* lpszFileMask, int iAttributes, int iFlags);
qint64 FindFirst(const QString& qsFileMask, int iAttributes, int iFlags);
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:
- GetSearchResultAttributes
- GetSearchResultCreationTime
- GetSearchResultFullName
- GetSearchResultLastAccessTime
- GetSearchResultLinkDestination
- GetSearchResultMetadataSize
- GetSearchResultModificationTime
- GetSearchResultName
- GetSearchResultSize
To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method to release the resources associated with it.
Because 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 (e.g., sequentially, round robin).
The FileMask parameter specifies both the directory path to search within and the file name mask to match against (e.g., \directory\to\search\*.txt). Or, when searching a file's alternate streams, it specifies 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 match only if they have one or more of the specified attributes. The value passed for this parameter should be constructed by ORing together zero or more of the following values. Passing 0 will allow any file in a directory (or, any alternate stream in a file) to match; it is equivalent to VAULT_FATTR_FILE | VAULT_FATTR_DATA_STREAM.
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that 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 ORing together zero or more of the following values:
VAULT_FF_NEED_NAME | 0x00000001 | Include entry names (without paths) when returning search results. |
VAULT_FF_NEED_FULL_NAME | 0x00000002 | Include fully qualified entry names when returning search results. |
VAULT_FF_NEED_ATTRIBUTES | 0x00000004 | Include entry attributes when returning search results. |
VAULT_FF_NEED_SIZE | 0x00000008 | Include entry sizes when returning search results. |
VAULT_FF_NEED_METADATA_SIZE | 0x00000010 | Include entry metadata sizes when returning search results. |
VAULT_FF_NEED_TIMES | 0x00000020 | Include entry times when returning search results. |
VAULT_FF_NEED_LINK_DEST | 0x00000040 | Include symbolic link destinations when returning search results. |
VAULT_FF_EMULATE_FAT | 0x00001000 | Inserts . and .. pseudo-entries into search results for all directories except the root one. |
VAULT_FF_RECURSIVE | 0x00002000 | Search recursively in all subdirectories. |
VAULT_FF_CASE_INSENSITIVE | 0x00004000 | Forces case-insensitive search, even if the vault is case-sensitive. |
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FindFirstByQuery Method (CBVaultDrive Class)
This method searches for the first file or directory whose file tags match the specified query.
Syntax
ANSI (Cross Platform) int64 FindFirstByQuery(const char* lpszDirectory, const char* lpszQuery, int iFlags); Unicode (Windows) LONG64 FindFirstByQuery(LPCWSTR lpszDirectory, LPCWSTR lpszQuery, INT iFlags);
int64 cbfsstorage_cbvaultdrive_findfirstbyquery(void* lpObj, const char* lpszDirectory, const char* lpszQuery, int iFlags);
qint64 FindFirstByQuery(const QString& qsDirectory, const QString& qsQuery, int iFlags);
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:
- GetSearchResultAttributes
- GetSearchResultCreationTime
- GetSearchResultFullName
- GetSearchResultLastAccessTime
- GetSearchResultLinkDestination
- GetSearchResultMetadataSize
- GetSearchResultModificationTime
- GetSearchResultName
- GetSearchResultSize
To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method to release the resources associated with it.
Because 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 (e.g., sequentially, round robin).
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 ORing together zero or more of the following values:
VAULT_FF_NEED_NAME | 0x00000001 | Include entry names (without paths) when returning search results. |
VAULT_FF_NEED_FULL_NAME | 0x00000002 | Include fully qualified entry names when returning search results. |
VAULT_FF_NEED_ATTRIBUTES | 0x00000004 | Include entry attributes when returning search results. |
VAULT_FF_NEED_SIZE | 0x00000008 | Include entry sizes when returning search results. |
VAULT_FF_NEED_METADATA_SIZE | 0x00000010 | Include entry metadata sizes when returning search results. |
VAULT_FF_NEED_TIMES | 0x00000020 | Include entry times when returning search results. |
VAULT_FF_NEED_LINK_DEST | 0x00000040 | Include symbolic link destinations when returning search results. |
VAULT_FF_EMULATE_FAT | 0x00001000 | Inserts . and .. pseudo-entries into search results for all directories except the root one. |
VAULT_FF_RECURSIVE | 0x00002000 | Search recursively in all subdirectories. |
VAULT_FF_CASE_INSENSITIVE | 0x00004000 | Forces case-insensitive search, even if the vault is case-sensitive. |
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
FindNext Method (CBVaultDrive Class)
This method searches for the next vault item that matches an ongoing search operation.
Syntax
ANSI (Cross Platform) bool FindNext(int64 lSearchId); Unicode (Windows) bool FindNext(LONG64 lSearchId);
bool cbfsstorage_cbvaultdrive_findnext(void* lpObj, int64 lSearchId);
bool FindNext(qint64 lSearchId);
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 FindFirst or FindFirstByQuery. Please refer to the methods' documentation for more information about search operations.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
ForceUnmount Method (CBVaultDrive Class)
Forcefully unmounts the virtual drive associated with the specified vault (Windows only).
Syntax
ANSI (Cross Platform) int ForceUnmount(const char* lpszVaultFile); Unicode (Windows) INT ForceUnmount(LPCWSTR lpszVaultFile);
int cbfsstorage_cbvaultdrive_forceunmount(void* lpObj, const char* lpszVaultFile);
int ForceUnmount(const QString& qsVaultFile);
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.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
FormatVolume Method (CBVaultDrive Class)
Formats a storage volume or partition with the CBFS Storage filesystem (Windows only).
Syntax
ANSI (Cross Platform) int FormatVolume(const char* lpszVolumeName, int iFlags); Unicode (Windows) INT FormatVolume(LPCWSTR lpszVolumeName, INT iFlags);
int cbfsstorage_cbvaultdrive_formatvolume(void* lpObj, const char* lpszVolumeName, int iFlags);
int FormatVolume(const QString& qsVolumeName, int iFlags);
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 OpenVolume 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_FORMAT | 0x00000001 | Perform 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 it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
GetDriverStatus Method (CBVaultDrive Class)
Retrieves the status of the system driver.
Syntax
ANSI (Cross Platform) int GetDriverStatus(const char* lpszProductGUID, int iModule); Unicode (Windows) INT GetDriverStatus(LPCWSTR lpszProductGUID, INT iModule);
int cbfsstorage_cbvaultdrive_getdriverstatus(void* lpObj, const char* lpszProductGUID, int iModule);
int GetDriverStatus(const QString& qsProductGUID, int iModule);
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_PRESENT | 0x00000000 | The specified module is not present on the system.
Note: This functionality is only available in Windows. |
MODULE_STATUS_STOPPED | 0x00000001 | The specified module is in the Stopped state.
Note: This functionality is only available in Windows. |
MODULE_STATUS_RUNNING | 0x00000004 | The specified module is loaded and running.
Note: This functionality is only available in Windows. |
ProductGUID is used to distinguish between driver installations performed by different applications. Such information is necessary to guard against unexpected situations such as, e.g., the driver being uninstalled by one application despite other applications still needing it.
The GUID must be specified in so-called "Registry Format" (e.g., "{1FAD0EF2-9A03-4B87-B4BC-645B7035ED90}") with curly braces included.
To ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:
The Module parameter specifies which driver module to query the status of. Possible values are:
MODULE_DRIVER_PNP_BUS | 0x00000001 | PnP 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_BLOCK | 0x00000002 | Virtual 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_FS | 0x00000004 | Filesystem 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_DLL | 0x00010000 | Shell Helper DLL (CBVaultDriveShellHelper2024.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 GetDriverStatus 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.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileAttributes Method (CBVaultDrive Class)
This method retrieves the attributes of a vault item.
Syntax
ANSI (Cross Platform) int GetFileAttributes(const char* lpszFileName); Unicode (Windows) INT GetFileAttributes(LPCWSTR lpszFileName);
int cbfsstorage_cbvaultdrive_getfileattributes(void* lpObj, const char* lpszFileName);
int GetFileAttributes(const QString& qsFileName);
Remarks
This method retrieves the attributes of the vault item (e.g., 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_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileCompression Method (CBVaultDrive Class)
This method retrieves the compression mode of a file or alternate stream.
Syntax
ANSI (Cross Platform) int GetFileCompression(const char* lpszFileName); Unicode (Windows) INT GetFileCompression(LPCWSTR lpszFileName);
int cbfsstorage_cbvaultdrive_getfilecompression(void* lpObj, const char* lpszFileName);
int GetFileCompression(const QString& qsFileName);
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_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileCreationTime Method (CBVaultDrive Class)
This method retrieves the creation time of a vault item.
Syntax
ANSI (Cross Platform) int64 GetFileCreationTime(const char* lpszFileName); Unicode (Windows) LONG64 GetFileCreationTime(LPCWSTR lpszFileName);
int64 cbfsstorage_cbvaultdrive_getfilecreationtime(void* lpObj, const char* lpszFileName);
QDateTime GetFileCreationTime(const QString& qsFileName);
Remarks
This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileEncryption Method (CBVaultDrive Class)
This method retrieves the encryption mode of a file or alternate stream.
Syntax
ANSI (Cross Platform) int GetFileEncryption(const char* lpszFileName); Unicode (Windows) INT GetFileEncryption(LPCWSTR lpszFileName);
int cbfsstorage_cbvaultdrive_getfileencryption(void* lpObj, const char* lpszFileName);
int GetFileEncryption(const QString& qsFileName);
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_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileLastAccessTime Method (CBVaultDrive Class)
This method retrieves the last access time of a vault item.
Syntax
ANSI (Cross Platform) int64 GetFileLastAccessTime(const char* lpszFileName); Unicode (Windows) LONG64 GetFileLastAccessTime(LPCWSTR lpszFileName);
int64 cbfsstorage_cbvaultdrive_getfilelastaccesstime(void* lpObj, const char* lpszFileName);
QDateTime GetFileLastAccessTime(const QString& qsFileName);
Remarks
This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
Note: Vault items' last access times are updated only if the UseAccessTime property is enabled.
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileModificationTime Method (CBVaultDrive Class)
This method retrieves the modification time of a vault item.
Syntax
ANSI (Cross Platform) int64 GetFileModificationTime(const char* lpszFileName); Unicode (Windows) LONG64 GetFileModificationTime(LPCWSTR lpszFileName);
int64 cbfsstorage_cbvaultdrive_getfilemodificationtime(void* lpObj, const char* lpszFileName);
QDateTime GetFileModificationTime(const QString& qsFileName);
Remarks
This method retrieves the modification time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileSize Method (CBVaultDrive Class)
This method retrieves the size of a file or alternate stream.
Syntax
ANSI (Cross Platform) int64 GetFileSize(const char* lpszFileName); Unicode (Windows) LONG64 GetFileSize(LPCWSTR lpszFileName);
int64 cbfsstorage_cbvaultdrive_getfilesize(void* lpObj, const char* lpszFileName);
qint64 GetFileSize(const QString& qsFileName);
Remarks
This method retrieves the size, in bytes, of the file or alternate stream specified by FileName.
Note: For files, the returned value reflects only 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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTag Method (CBVaultDrive Class)
This method retrieves the binary data held by a raw file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) char* GetFileTag(const char* lpszFileName, int iTagId, int *lpSize = NULL); Unicode (Windows) LPSTR GetFileTag(LPCWSTR lpszFileName, INT iTagId, LPINT lpSize = NULL);
char* cbfsstorage_cbvaultdrive_getfiletag(void* lpObj, const char* lpszFileName, int iTagId, int *lpSize);
QByteArray GetFileTag(const QString& qsFileName, int iTagId);
Remarks
This method retrieves the binary data held by a raw file tag, identified by TagId, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a raw file tag with the specified TagId is not attached to the specified vault item, this method fails with an error.
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 be called only when Active is true.
Error Handling (C++)
This method returns a Byte Array value (with length lpSize); after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagAsAnsiString Method (CBVaultDrive Class)
This method retrieves the value of an AnsiString-typed file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) char* GetFileTagAsAnsiString(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) LPWSTR GetFileTagAsAnsiString(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
char* cbfsstorage_cbvaultdrive_getfiletagasansistring(void* lpObj, const char* lpszFileName, const char* lpszTagName);
QString GetFileTagAsAnsiString(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the value of an AnsiString-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If an AnsiString-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
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 SetFileTagAsAnsiString method. Typed file tags created with the SetFileTagAsString method must be retrieved using the GetFileTagAsString method.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagAsBoolean Method (CBVaultDrive Class)
This method retrieves the value of a Boolean-typed file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) bool GetFileTagAsBoolean(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) bool GetFileTagAsBoolean(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
bool cbfsstorage_cbvaultdrive_getfiletagasboolean(void* lpObj, const char* lpszFileName, const char* lpszTagName);
bool GetFileTagAsBoolean(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the value of a Boolean-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a Boolean-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
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 be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagAsDateTime Method (CBVaultDrive Class)
This method retrieves the value of a DateTime-typed file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) int64 GetFileTagAsDateTime(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) LONG64 GetFileTagAsDateTime(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
int64 cbfsstorage_cbvaultdrive_getfiletagasdatetime(void* lpObj, const char* lpszFileName, const char* lpszTagName);
QDateTime GetFileTagAsDateTime(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the value of a DateTime-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a DateTime-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagAsNumber Method (CBVaultDrive Class)
This method retrieves the value of a Number-typed file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) int64 GetFileTagAsNumber(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) LONG64 GetFileTagAsNumber(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
int64 cbfsstorage_cbvaultdrive_getfiletagasnumber(void* lpObj, const char* lpszFileName, const char* lpszTagName);
qint64 GetFileTagAsNumber(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the value of a Number-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a Number-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagAsString Method (CBVaultDrive Class)
This method retrieves the value of a String-typed file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) char* GetFileTagAsString(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) LPWSTR GetFileTagAsString(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
char* cbfsstorage_cbvaultdrive_getfiletagasstring(void* lpObj, const char* lpszFileName, const char* lpszTagName);
QString GetFileTagAsString(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the value of a String-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a String-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
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 SetFileTagAsString method. Typed file tags created with the SetFileTagAsAnsiString method must be retrieved using the GetFileTagAsAnsiString method.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagDataType Method (CBVaultDrive Class)
This method retrieves the data type of a typed file tag attached to a specific vault item.
Syntax
ANSI (Cross Platform) int GetFileTagDataType(const char* lpszFileName, const char* lpszTagName); Unicode (Windows) INT GetFileTagDataType(LPCWSTR lpszFileName, LPCWSTR lpszTagName);
int cbfsstorage_cbvaultdrive_getfiletagdatatype(void* lpObj, const char* lpszFileName, const char* lpszTagName);
int GetFileTagDataType(const QString& qsFileName, const QString& qsTagName);
Remarks
This method retrieves the data type of a typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.
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_RAWDATA | 0x0 | The tag is untyped and must be addressed by Id. |
VAULT_TDT_BOOLEAN | 0x1 | The tag contains Boolean data and must be addressed by name. |
VAULT_TDT_STRING | 0x2 | The tag contains String (UTF-16LE) data and must be addressed by name. |
VAULT_TDT_DATETIME | 0x3 | The tag contains DateTime data and must be addressed by name. |
VAULT_TDT_NUMBER | 0x4 | The tag contains numeric (signed 64-bit) data and must be addressed by name. |
VAULT_TDT_ANSISTRING | 0x5 | The 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 be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetFileTagSize Method (CBVaultDrive Class)
This method retrieves the size of a raw file tag attached to the specified vault item.
Syntax
ANSI (Cross Platform) int GetFileTagSize(const char* lpszFileName, int iTagId); Unicode (Windows) INT GetFileTagSize(LPCWSTR lpszFileName, INT iTagId);
int cbfsstorage_cbvaultdrive_getfiletagsize(void* lpObj, const char* lpszFileName, int iTagId);
int GetFileTagSize(const QString& qsFileName, int iTagId);
Remarks
This method retrieves the size of the binary data held by a raw file tag, identified by TagId, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a raw file tag with the specified TagId is not 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 be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetModuleVersion Method (CBVaultDrive Class)
Retrieves the version of a given product module.
Syntax
ANSI (Cross Platform) int64 GetModuleVersion(const char* lpszProductGUID, int iModule); Unicode (Windows) LONG64 GetModuleVersion(LPCWSTR lpszProductGUID, INT iModule);
int64 cbfsstorage_cbvaultdrive_getmoduleversion(void* lpObj, const char* lpszProductGUID, int iModule);
qint64 GetModuleVersion(const QString& qsProductGUID, int iModule);
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_BUS | 0x00000001 | PnP 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_BLOCK | 0x00000002 | Virtual 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_FS | 0x00000004 | Filesystem 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_DLL | 0x00010000 | Shell Helper DLL (CBVaultDriveShellHelper2024.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 GetDriverStatus 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.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetOriginatorProcessId Method (CBVaultDrive Class)
Retrieves the Id of the process (PID) that initiated the operation (Windows only).
Syntax
ANSI (Cross Platform) int GetOriginatorProcessId(); Unicode (Windows) INT GetOriginatorProcessId();
int cbfsstorage_cbvaultdrive_getoriginatorprocessid(void* lpObj);
int GetOriginatorProcessId();
Remarks
This method can be called within the FilePasswordNeeded and FileAccess 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.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetOriginatorProcessName Method (CBVaultDrive Class)
Retrieves the name of the process that initiated the operation (Windows only).
Syntax
ANSI (Cross Platform) char* GetOriginatorProcessName(); Unicode (Windows) LPWSTR GetOriginatorProcessName();
char* cbfsstorage_cbvaultdrive_getoriginatorprocessname(void* lpObj);
QString GetOriginatorProcessName();
Remarks
This method can be called within the FilePasswordNeeded and and FileAccess 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.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetOriginatorThreadId Method (CBVaultDrive Class)
Retrieves the Id of the thread that initiated the operation (Windows only).
Syntax
ANSI (Cross Platform) int GetOriginatorThreadId(); Unicode (Windows) INT GetOriginatorThreadId();
int cbfsstorage_cbvaultdrive_getoriginatorthreadid(void* lpObj);
int GetOriginatorThreadId();
Remarks
This method can be called within the FilePasswordNeeded and FileAccess events to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.
This method is available only in Windows.
Please note that thread Ids are not unique, and may be reused by different threads over time.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetOriginatorToken Method (CBVaultDrive Class)
Retrieves the security token associated with the process that initiated the operation (Windows only).
Syntax
ANSI (Cross Platform) int64 GetOriginatorToken(); Unicode (Windows) LONG64 GetOriginatorToken();
int64 cbfsstorage_cbvaultdrive_getoriginatortoken(void* lpObj);
qint64 GetOriginatorToken();
Remarks
This method can be called within the FilePasswordNeeded event to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE.
This method is available only in Windows.
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.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultAttributes Method (CBVaultDrive Class)
This method retrieves the attributes of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int GetSearchResultAttributes(int64 lSearchId); Unicode (Windows) INT GetSearchResultAttributes(LONG64 lSearchId);
int cbfsstorage_cbvaultdrive_getsearchresultattributes(void* lpObj, int64 lSearchId);
int GetSearchResultAttributes(qint64 lSearchId);
Remarks
This method retrieves the attributes of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
The vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
If, however, 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 FindFirst/FindFirstByQuery 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 be called only when Active is true.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultCreationTime Method (CBVaultDrive Class)
This method retrieves the creation time of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int64 GetSearchResultCreationTime(int64 lSearchId); Unicode (Windows) LONG64 GetSearchResultCreationTime(LONG64 lSearchId);
int64 cbfsstorage_cbvaultdrive_getsearchresultcreationtime(void* lpObj, int64 lSearchId);
QDateTime GetSearchResultCreationTime(qint64 lSearchId);
Remarks
This method retrieves the creation time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
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 FindFirst/FindFirstByQuery 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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultFullName Method (CBVaultDrive Class)
This method retrieves the fully qualified name of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) char* GetSearchResultFullName(int64 lSearchId); Unicode (Windows) LPWSTR GetSearchResultFullName(LONG64 lSearchId);
char* cbfsstorage_cbvaultdrive_getsearchresultfullname(void* lpObj, int64 lSearchId);
QString GetSearchResultFullName(qint64 lSearchId);
Remarks
This method retrieves the fully qualified name of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId (i.e., 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 FindFirst or FindFirstByQuery.
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 FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultLastAccessTime Method (CBVaultDrive Class)
This method retrieves the last access time of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int64 GetSearchResultLastAccessTime(int64 lSearchId); Unicode (Windows) LONG64 GetSearchResultLastAccessTime(LONG64 lSearchId);
int64 cbfsstorage_cbvaultdrive_getsearchresultlastaccesstime(void* lpObj, int64 lSearchId);
QDateTime GetSearchResultLastAccessTime(qint64 lSearchId);
Remarks
This method retrieves the creation time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
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 FindFirst/FindFirstByQuery method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.
Note: Vault items' last access times are updated only if the UseAccessTime property is enabled.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultLinkDestination Method (CBVaultDrive Class)
This method retrieves the destination of a symbolic link found during a search operation.
Syntax
ANSI (Cross Platform) char* GetSearchResultLinkDestination(int64 lSearchId); Unicode (Windows) LPWSTR GetSearchResultLinkDestination(LONG64 lSearchId);
char* cbfsstorage_cbvaultdrive_getsearchresultlinkdestination(void* lpObj, int64 lSearchId);
QString GetSearchResultLinkDestination(qint64 lSearchId);
Remarks
This method retrieves the fully qualified name of a symbolic link found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
If the most recently found vault item is not 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 FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultMetadataSize Method (CBVaultDrive Class)
This method retrieves the size of the metadata associated with a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int64 GetSearchResultMetadataSize(int64 lSearchId); Unicode (Windows) LONG64 GetSearchResultMetadataSize(LONG64 lSearchId);
int64 cbfsstorage_cbvaultdrive_getsearchresultmetadatasize(void* lpObj, int64 lSearchId);
qint64 GetSearchResultMetadataSize(qint64 lSearchId);
Remarks
This method retrieves the size of the metadata associated with a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 that 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 FindFirst or FindFirstByQuery.
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 FindFirst/FindFirstByQuery 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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultModificationTime Method (CBVaultDrive Class)
This method retrieves the modification time of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int64 GetSearchResultModificationTime(int64 lSearchId); Unicode (Windows) LONG64 GetSearchResultModificationTime(LONG64 lSearchId);
int64 cbfsstorage_cbvaultdrive_getsearchresultmodificationtime(void* lpObj, int64 lSearchId);
QDateTime GetSearchResultModificationTime(qint64 lSearchId);
Remarks
This method retrieves the modification time of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
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 FindFirst/FindFirstByQuery 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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultName Method (CBVaultDrive Class)
This method retrieves the name of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) char* GetSearchResultName(int64 lSearchId); Unicode (Windows) LPWSTR GetSearchResultName(LONG64 lSearchId);
char* cbfsstorage_cbvaultdrive_getsearchresultname(void* lpObj, int64 lSearchId);
QString GetSearchResultName(qint64 lSearchId);
Remarks
This method retrieves the name of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext 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 FindFirst or FindFirstByQuery.
The names returned by this method do not include a path; use GetSearchResultFullName 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 FindFirst/FindFirstByQuery method's Flags parameter), this method will always return an empty string. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
GetSearchResultSize Method (CBVaultDrive Class)
This method retrieves the size of a vault item found during a search operation.
Syntax
ANSI (Cross Platform) int64 GetSearchResultSize(int64 lSearchId); Unicode (Windows) LONG64 GetSearchResultSize(LONG64 lSearchId);
int64 cbfsstorage_cbvaultdrive_getsearchresultsize(void* lpObj, int64 lSearchId);
qint64 GetSearchResultSize(qint64 lSearchId);
Remarks
This method retrieves the size of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.
Note: For files, the returned value reflects only 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 FindFirst or FindFirstByQuery.
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 FindFirst/FindFirstByQuery 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 be called only when Active is true.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
Initialize Method (CBVaultDrive Class)
This method initializes the class.
Syntax
ANSI (Cross Platform) int Initialize(const char* lpszProductGUID); Unicode (Windows) INT Initialize(LPCWSTR lpszProductGUID);
int cbfsstorage_cbvaultdrive_initialize(void* lpObj, const char* lpszProductGUID);
int Initialize(const QString& qsProductGUID);
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).
If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the class can be used.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
Install Method (CBVaultDrive Class)
Installs (or upgrades) the product's system drivers and/or the helper DLL (Windows only).
Syntax
ANSI (Cross Platform) int Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iModulesToInstall, int iFlags); Unicode (Windows) INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, INT iModulesToInstall, INT iFlags);
int cbfsstorage_cbvaultdrive_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iModulesToInstall, int iFlags);
int Install(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsPathToInstall, int iModulesToInstall, int iFlags);
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_BUS | 0x00000001 | PnP 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_BLOCK | 0x00000002 | Virtual 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_FS | 0x00000004 | Filesystem 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_DLL | 0x00010000 | Shell Helper DLL (CBVaultDriveShellHelper2024.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 GetDriverStatus method. |
Flags specifies various installation options, and should contain zero or more of the following flags, OR'd together:
INSTALL_REMOVE_OLD_VERSIONS | 0x00000001 | Uninstall drivers and helper DLLs from previous class versions (e.g., 2017).
Note: This functionality is only available in Windows. This flag does not remove the old PnP driver (VPnpBus) from the system because that driver is not versioned. Use the installer DLL of the old version and its Uninstall() function if you need to uninstall the PnP driver. |
INSTALL_KEEP_START_TYPE | 0x00000002 | Keep the driver's current start type setting in the registry.
If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application itself) set it previously. Note: This functionality is only available in Windows. |
INSTALL_OVERWRITE_SAME_VERSION | 0x00000004 | Install files when their version is the same as the version of already installed files.
If this flag is not set (default), the installation logic will overwrite the existing file only if the version number of the file being installed is larger than the version of the file being overwritten. Setting this flag causes the installation logic to overwrite the file even when it has the same version. Note: This functionality is only available in Windows. |
This method is available in both the 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.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
IsDirectoryEmpty Method (CBVaultDrive Class)
This method checks whether a directory is empty.
Syntax
ANSI (Cross Platform) bool IsDirectoryEmpty(const char* lpszDirectory); Unicode (Windows) bool IsDirectoryEmpty(LPCWSTR lpszDirectory);
bool cbfsstorage_cbvaultdrive_isdirectoryempty(void* lpObj, const char* lpszDirectory);
bool IsDirectoryEmpty(const QString& qsDirectory);
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 be called only when Active is true.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
IsIconRegistered Method (CBVaultDrive Class)
Checks whether the specified icon is registered (Windows only).
Syntax
ANSI (Cross Platform) bool IsIconRegistered(const char* lpszIconId); Unicode (Windows) bool IsIconRegistered(LPCWSTR lpszIconId);
bool cbfsstorage_cbvaultdrive_isiconregistered(void* lpObj, const char* lpszIconId);
bool IsIconRegistered(const QString& qsIconId);
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 RegisterIcon 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 GetModuleVersion method, and install it using the Install method if necessary.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
IsValidVault Method (CBVaultDrive Class)
This method checks whether a local file is a CBFS Storage vault.
Syntax
ANSI (Cross Platform) bool IsValidVault(); Unicode (Windows) bool IsValidVault();
bool cbfsstorage_cbvaultdrive_isvalidvault(void* lpObj);
bool IsValidVault();
Remarks
This method checks whether the file specified by the VaultFile 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 CallbackMode property is enabled, the check will be performed by the appropriate Vault* events (and the value held by VaultFile is simply passed to such events for the application to use).
Note: This method uses a simple detection mechanism; it does not perform a full consistency check or attempt any repairs, so applications may still need to call CheckAndRepair even if this method returns true. If an error occurs during the detection process, this method fails with an error.
Note: This method cannot be called when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
IsValidVaultVolume Method (CBVaultDrive Class)
Checks whether a storage partition or volume is formatted with the CBFS Storage filesystem (Windows only).
Syntax
ANSI (Cross Platform) bool IsValidVaultVolume(const char* lpszVolumeName); Unicode (Windows) bool IsValidVaultVolume(LPCWSTR lpszVolumeName);
bool cbfsstorage_cbvaultdrive_isvalidvaultvolume(void* lpObj, const char* lpszVolumeName);
bool IsValidVaultVolume(const QString& qsVolumeName);
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 OpenVolume 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 CheckAndRepair even if this method returns true. If an error occurs during the detection process, this method fails with an error.
Note: This method cannot be called within events.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
MoveFile Method (CBVaultDrive Class)
This method renames or moves a vault item.
Syntax
ANSI (Cross Platform) int MoveFile(const char* lpszOldFileName, const char* lpszNewFileName, int bOverwrite); Unicode (Windows) INT MoveFile(LPCWSTR lpszOldFileName, LPCWSTR lpszNewFileName, BOOL bOverwrite);
int cbfsstorage_cbvaultdrive_movefile(void* lpObj, const char* lpszOldFileName, const char* lpszNewFileName, int bOverwrite);
int MoveFile(const QString& qsOldFileName, const QString& qsNewFileName, bool bOverwrite);
Remarks
This method renames or moves a vault item (e.g., 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 allowed only 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 fails with an error.
Note: The usual rules of deletion still apply for an item being overwritten. Notably, a nonempty directory cannot be overwritten.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
OpenFile Method (CBVaultDrive Class)
This method opens a new or existing file or alternate stream in the vault.
Syntax
ANSI (Cross Platform) CBFSStorageStream* OpenFile(const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, const char* lpszPassword); Unicode (Windows) CBFSStorageStream* OpenFile(LPCWSTR lpszFileName, INT iOpenMode, BOOL bReadEnabled, BOOL bWriteEnabled, LPCWSTR lpszPassword);
CBFSStorageStream* cbfsstorage_cbvaultdrive_openfile(void* lpObj, const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, const char* lpszPassword);
CBFSStorageStream* OpenFile(const QString& qsFileName, int iOpenMode, bool bReadEnabled, bool bWriteEnabled, const QString& qsPassword);
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.
Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly 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 as follows:
VAULT_FOM_CREATE_NEW | 0 | Creates a new file or alternate stream if possible, failing if one already exists. |
VAULT_FOM_CREATE_ALWAYS | 1 | Creates a new file or stream, overwriting an existing one if necessary. |
VAULT_FOM_OPEN_EXISTING | 2 | Opens a file or stream if it exists; fails otherwise. |
VAULT_FOM_OPEN_ALWAYS | 3 | Opens 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 ReadOnly 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 DefaultFileEncryption property is not VAULT_EM_NONE, the specified Password is used to encrypt it.
Internally, this method simply calls OpenFileEx, passing on all shared parameters' values and using the following defaults for the others:
- ShareDenyRead and ShareDenyWrite use true.
- Encryption uses the current DefaultFileEncryption value.
- Compression and CompressionLevel use the current DefaultFileCompression and DefaultFileCompressionLevel values, respectively.
- PagesPerBlock uses 16.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
OpenFileEx Method (CBVaultDrive Class)
This method opens a new or existing file or alternate stream in the vault.
Syntax
ANSI (Cross Platform) CBFSStorageStream* OpenFileEx(const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, int bShareDenyRead, int bShareDenyWrite, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock); Unicode (Windows) CBFSStorageStream* OpenFileEx(LPCWSTR lpszFileName, INT iOpenMode, BOOL bReadEnabled, BOOL bWriteEnabled, BOOL bShareDenyRead, BOOL bShareDenyWrite, INT iEncryption, LPCWSTR lpszPassword, INT iCompression, INT iCompressionLevel, INT iPagesPerBlock);
CBFSStorageStream* cbfsstorage_cbvaultdrive_openfileex(void* lpObj, const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, int bShareDenyRead, int bShareDenyWrite, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);
CBFSStorageStream* OpenFileEx(const QString& qsFileName, int iOpenMode, bool bReadEnabled, bool bWriteEnabled, bool bShareDenyRead, bool bShareDenyWrite, int iEncryption, const QString& qsPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);
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.
Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly 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 as follows:
VAULT_FOM_CREATE_NEW | 0 | Creates a new file or alternate stream if possible, failing if one already exists. |
VAULT_FOM_CREATE_ALWAYS | 1 | Creates a new file or stream, overwriting an existing one if necessary. |
VAULT_FOM_OPEN_EXISTING | 2 | Opens a file or stream if it exists; fails otherwise. |
VAULT_FOM_OPEN_ALWAYS | 3 | Opens 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 ReadOnly 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 as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive 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.
The Compression parameter specifies the compression mode to use when creating a file or alternate stream. Valid values are as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress 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 run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
OpenRootData Method (CBVaultDrive Class)
This method opens the vault's root data stream.
Syntax
ANSI (Cross Platform) CBFSStorageStream* OpenRootData(); Unicode (Windows) CBFSStorageStream* OpenRootData();
CBFSStorageStream* cbfsstorage_cbvaultdrive_openrootdata(void* lpObj);
CBFSStorageStream* OpenRootData();
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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
OpenVault Method (CBVaultDrive Class)
This method opens a new or existing vault.
Syntax
ANSI (Cross Platform) int OpenVault(int iOpenMode, int iJournalingMode); Unicode (Windows) INT OpenVault(INT iOpenMode, INT iJournalingMode);
int cbfsstorage_cbvaultdrive_openvault(void* lpObj, int iOpenMode, int iJournalingMode);
int OpenVault(int iOpenMode, int iJournalingMode);
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 as follows:
VAULT_OM_CREATE_NEW | 0 | Creates a new vault if possible, failing if one already exists. |
VAULT_OM_CREATE_ALWAYS | 1 | Creates a new vault, overwriting an existing one if necessary. |
VAULT_OM_OPEN_EXISTING | 2 | Opens a vault if it exists; fails otherwise. |
VAULT_OM_OPEN_ALWAYS | 3 | Opens 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 as follows:
VAULT_JM_NONE | 0 | No journaling is used.
This mode ensures the fastest operations, but if the application crashes, corruption of the vault is possible. |
VAULT_JM_METADATA | 1 | Journaling is used only for metadata (filesystem structure and directory contents).
This mode is a balance between speed and reliability. |
VAULT_JM_FULL | 2 | Journaling is used for both filesystem structure and file data and metadata.
This mode is the slowest but the most reliable option. |
When a vault is being created or opened, the VaultFile and/or CallbackMode properties are used to specify its location. If CallbackMode is disabled (default), the class creates or opens a file-based vault at the path specified by VaultFile.
If CallbackMode is enabled, then the application controls where the vault is located and how it is accessed by the Vault* events (and the value held by VaultFile 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.
- AutoCompactAt property
- AutoCompactDelay configuration setting
- CaseSensitive property
- Logo property
- MaxNonPagedNameLength configuration setting
- PageSize property
- PartSize configuration setting
- PathSeparator property
- ReadOnly property
- UseAccessTime property
- UseSystemCache property
If a file-based vault's storage file (or the storage device it is located on) is marked as read-only, then the ReadOnly 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 fails with an error.
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 to avoid a systemwide deadlock in Windows internals.
Note: This method cannot be called when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
OpenVolume Method (CBVaultDrive Class)
Opens a storage volume or partition formatted with the CBFS Storage filesystem as a vault (Windows only).
Syntax
ANSI (Cross Platform) int OpenVolume(const char* lpszVolumeName, int iJournalingMode); Unicode (Windows) INT OpenVolume(LPCWSTR lpszVolumeName, INT iJournalingMode);
int cbfsstorage_cbvaultdrive_openvolume(void* lpObj, const char* lpszVolumeName, int iJournalingMode);
int OpenVolume(const QString& qsVolumeName, int iJournalingMode);
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 fails with an error.
The JournalingMode parameter specifies whether any form of journaling should be used when working with the vault. Valid values are:
VAULT_JM_NONE | 0 | No journaling is used.
This mode ensures the fastest operations, but if the application crashes, corruption of the vault is possible. |
VAULT_JM_METADATA | 1 | Journaling is used only for metadata (filesystem structure and directory contents).
This mode is a balance between speed and reliability. |
VAULT_JM_FULL | 2 | Journaling is used for both filesystem structure and file data and metadata.
This mode 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 it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
RegisterIcon Method (CBVaultDrive Class)
Registers an icon that can be displayed as an overlay on the virtual drive in Windows File Explorer (Windows only).
Syntax
ANSI (Cross Platform) bool RegisterIcon(const char* lpszIconPath, const char* lpszProductGUID, const char* lpszIconId); Unicode (Windows) bool RegisterIcon(LPCWSTR lpszIconPath, LPCWSTR lpszProductGUID, LPCWSTR lpszIconId);
bool cbfsstorage_cbvaultdrive_registericon(void* lpObj, const char* lpszIconPath, const char* lpszProductGUID, const char* lpszIconId);
bool RegisterIcon(const QString& qsIconPath, const QString& qsProductGUID, const QString& qsIconId);
Remarks
This method registers an icon in the file specified by IconPath so that it can later be used to display an overlay on the virtual drive in Windows File Explorer. If the system must be rebooted before the icon can be used, this method returns true, otherwise it returns false.
Please note that this method only registers overlay icons; Applications should call the SetIcon and ResetIcon 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 UnregisterIcon.
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 SetIcon and UnregisterIcon 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 UnregisterIcon 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 GetModuleVersion 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.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
RemoveDeniedProcess Method (CBVaultDrive Class)
Removes a rule that prevents a process from accessing the virtual drive .
Syntax
ANSI (Cross Platform) int RemoveDeniedProcess(const char* lpszProcessFileName, int iProcessId); Unicode (Windows) INT RemoveDeniedProcess(LPCWSTR lpszProcessFileName, INT iProcessId);
int cbfsstorage_cbvaultdrive_removedeniedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId);
int RemoveDeniedProcess(const QString& qsProcessFileName, int iProcessId);
Remarks
When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddDeniedProcess method.
Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddDeniedProcess was called previously. Please refer to that method's documentation for more information.
Note: This method can be called only when Active is true, and it cannot be called within events.
The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
RemoveGrantedProcess Method (CBVaultDrive Class)
Removes a rule that allows a process to access the virtual drive .
Syntax
ANSI (Cross Platform) int RemoveGrantedProcess(const char* lpszProcessFileName, int iProcessId); Unicode (Windows) INT RemoveGrantedProcess(LPCWSTR lpszProcessFileName, INT iProcessId);
int cbfsstorage_cbvaultdrive_removegrantedprocess(void* lpObj, const char* lpszProcessFileName, int iProcessId);
int RemoveGrantedProcess(const QString& qsProcessFileName, int iProcessId);
Remarks
When the ProcessRestrictionsEnabled property is enabled, this method can be used to remove an access rule previously added with the AddGrantedProcess method.
Pass the same values for ProcessFileName and ProcessId as were used to add the rule when AddGrantedProcess was called previously. Please refer to that method's documentation for more information.
Note: This method can be called only when Active is true, and it cannot be called within events.
The methods and properties related to process access lists are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of process access information occurs in a thread-safe manner.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
RemoveMountingPoint Method (CBVaultDrive Class)
Removes a mounting point for the virtual drive.
Syntax
ANSI (Cross Platform) int RemoveMountingPoint(int iIndex, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId); Unicode (Windows) INT RemoveMountingPoint(INT iIndex, LPCWSTR lpszMountingPoint, INT iFlags, LONG64 lAuthenticationId);
int cbfsstorage_cbvaultdrive_removemountingpoint(void* lpObj, int iIndex, const char* lpszMountingPoint, int iFlags, int64 lAuthenticationId);
int RemoveMountingPoint(int iIndex, const QString& qsMountingPoint, int iFlags, qint64 lAuthenticationId);
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 AddMountingPoint 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.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
ResetIcon Method (CBVaultDrive Class)
Resets the virtual drive's icon back to default by deselecting the active overlay icon (Windows only).
Syntax
ANSI (Cross Platform) int ResetIcon(); Unicode (Windows) INT ResetIcon();
int cbfsstorage_cbvaultdrive_reseticon(void* lpObj);
int ResetIcon();
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 SetIcon 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 GetModuleVersion method, and install it using the Install method if necessary.
Note: This method can be called only after creating a virtual drive, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
ResolveLink Method (CBVaultDrive Class)
This method retrieves the destination of a symbolic link.
Syntax
ANSI (Cross Platform) char* ResolveLink(const char* lpszLinkName, int bNormalize); Unicode (Windows) LPWSTR ResolveLink(LPCWSTR lpszLinkName, BOOL bNormalize);
char* cbfsstorage_cbvaultdrive_resolvelink(void* lpObj, const char* lpszLinkName, int bNormalize);
QString ResolveLink(const QString& qsLinkName, bool bNormalize);
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 CreateLink 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 be called only when Active is true.
Error Handling (C++)
This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
SetFileAttributes Method (CBVaultDrive Class)
This method sets the attributes of a vault item.
Syntax
ANSI (Cross Platform) int SetFileAttributes(const char* lpszFileName, int iAttributes); Unicode (Windows) INT SetFileAttributes(LPCWSTR lpszFileName, INT iAttributes);
int cbfsstorage_cbvaultdrive_setfileattributes(void* lpObj, const char* lpszFileName, int iAttributes);
int SetFileAttributes(const QString& qsFileName, int iAttributes);
Remarks
This method sets the attributes of the vault item (e.g., 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 ORing together one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileCompression Method (CBVaultDrive Class)
This method compresses or decompresses a file or alternate stream.
Syntax
ANSI (Cross Platform) int SetFileCompression(const char* lpszFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const char* lpszPassword); Unicode (Windows) INT SetFileCompression(LPCWSTR lpszFileName, INT iCompression, INT iCompressionLevel, INT iPagesPerBlock, LPCWSTR lpszPassword);
int cbfsstorage_cbvaultdrive_setfilecompression(void* lpObj, const char* lpszFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const char* lpszPassword);
int SetFileCompression(const QString& qsFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const QString& qsPassword);
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 as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress 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 run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileCreationTime Method (CBVaultDrive Class)
This method sets the creation time of a vault item.
Syntax
ANSI (Cross Platform) int SetFileCreationTime(const char* lpszFileName, int64 lCreationTime); Unicode (Windows) INT SetFileCreationTime(LPCWSTR lpszFileName, LONG64 lCreationTime);
int cbfsstorage_cbvaultdrive_setfilecreationtime(void* lpObj, const char* lpszFileName, int64 lCreationTime);
int SetFileCreationTime(const QString& qsFileName, QDateTime qdtCreationTime);
Remarks
This method sets the creation time of the vault item (e.g., 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileEncryption Method (CBVaultDrive Class)
This method encrypts, decrypts, or changes the encryption password of a file or alternate stream.
Syntax
ANSI (Cross Platform) int SetFileEncryption(const char* lpszFileName, int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword); Unicode (Windows) INT SetFileEncryption(LPCWSTR lpszFileName, INT iEncryption, LPCWSTR lpszOldPassword, LPCWSTR lpszNewPassword);
int cbfsstorage_cbvaultdrive_setfileencryption(void* lpObj, const char* lpszFileName, int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword);
int SetFileEncryption(const QString& qsFileName, int iEncryption, const QString& qsOldPassword, const QString& qsNewPassword);
Remarks
This method changes the encryption mode 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 as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileLastAccessTime Method (CBVaultDrive Class)
This method sets the last access time of a vault item.
Syntax
ANSI (Cross Platform) int SetFileLastAccessTime(const char* lpszFileName, int64 lLastAccessTime); Unicode (Windows) INT SetFileLastAccessTime(LPCWSTR lpszFileName, LONG64 lLastAccessTime);
int cbfsstorage_cbvaultdrive_setfilelastaccesstime(void* lpObj, const char* lpszFileName, int64 lLastAccessTime);
int SetFileLastAccessTime(const QString& qsFileName, QDateTime qdtLastAccessTime);
Remarks
This method sets the last access time of the vault item (e.g., 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileModificationTime Method (CBVaultDrive Class)
This method sets the modification time of a vault item.
Syntax
ANSI (Cross Platform) int SetFileModificationTime(const char* lpszFileName, int64 lModificationTime); Unicode (Windows) INT SetFileModificationTime(LPCWSTR lpszFileName, LONG64 lModificationTime);
int cbfsstorage_cbvaultdrive_setfilemodificationtime(void* lpObj, const char* lpszFileName, int64 lModificationTime);
int SetFileModificationTime(const QString& qsFileName, QDateTime qdtModificationTime);
Remarks
This method sets the modification time of the vault item (e.g., 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileSize Method (CBVaultDrive Class)
This method sets the size of a file or alternate stream.
Syntax
ANSI (Cross Platform) int SetFileSize(const char* lpszFileName, int64 lSize, const char* lpszPassword); Unicode (Windows) INT SetFileSize(LPCWSTR lpszFileName, LONG64 lSize, LPCWSTR lpszPassword);
int cbfsstorage_cbvaultdrive_setfilesize(void* lpObj, const char* lpszFileName, int64 lSize, const char* lpszPassword);
int SetFileSize(const QString& qsFileName, qint64 lSize, const QString& qsPassword);
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 OpenFile and OpenFileEx methods.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTag Method (CBVaultDrive Class)
This method attaches a raw file tag with binary data to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTag(const char* lpszFileName, int iTagId, const char* lpData, int lenData); Unicode (Windows) INT SetFileTag(LPCWSTR lpszFileName, INT iTagId, LPCSTR lpData, INT lenData);
int cbfsstorage_cbvaultdrive_setfiletag(void* lpObj, const char* lpszFileName, int iTagId, const char* lpData, int lenData);
int SetFileTag(const QString& qsFileName, int iTagId, QByteArray qbaData);
Remarks
This method attaches a raw file tag with binary data to the vault item (e.g., 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTagAsAnsiString Method (CBVaultDrive Class)
This method attaches an AnsiString-typed file tag to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTagAsAnsiString(const char* lpszFileName, const char* lpszTagName, const char* lpszValue); Unicode (Windows) INT SetFileTagAsAnsiString(LPCWSTR lpszFileName, LPCWSTR lpszTagName, LPCWSTR lpszValue);
int cbfsstorage_cbvaultdrive_setfiletagasansistring(void* lpObj, const char* lpszFileName, const char* lpszTagName, const char* lpszValue);
int SetFileTagAsAnsiString(const QString& qsFileName, const QString& qsTagName, const QString& qsValue);
Remarks
This method attaches an AnsiString-typed file tag to the vault item (e.g., 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.
Note: AnsiString file tag values are converted to UTF-16LE when referenced in a search query string. To reduce 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 SetFileTagAsString) in all other cases.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTagAsBoolean Method (CBVaultDrive Class)
This method attaches a Boolean-typed file tag to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTagAsBoolean(const char* lpszFileName, const char* lpszTagName, int bValue); Unicode (Windows) INT SetFileTagAsBoolean(LPCWSTR lpszFileName, LPCWSTR lpszTagName, BOOL bValue);
int cbfsstorage_cbvaultdrive_setfiletagasboolean(void* lpObj, const char* lpszFileName, const char* lpszTagName, int bValue);
int SetFileTagAsBoolean(const QString& qsFileName, const QString& qsTagName, bool bValue);
Remarks
This method attaches a Boolean-typed file tag to the vault item (e.g., 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTagAsDateTime Method (CBVaultDrive Class)
This method attaches a DateTime-typed file tag to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTagAsDateTime(const char* lpszFileName, const char* lpszTagName, int64 lValue); Unicode (Windows) INT SetFileTagAsDateTime(LPCWSTR lpszFileName, LPCWSTR lpszTagName, LONG64 lValue);
int cbfsstorage_cbvaultdrive_setfiletagasdatetime(void* lpObj, const char* lpszFileName, const char* lpszTagName, int64 lValue);
int SetFileTagAsDateTime(const QString& qsFileName, const QString& qsTagName, QDateTime qdtValue);
Remarks
This method attaches a DateTime-typed file tag to the vault item (e.g., 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 as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as Windows FILETIME.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTagAsNumber Method (CBVaultDrive Class)
This method attaches a Number-typed file tag to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTagAsNumber(const char* lpszFileName, const char* lpszTagName, int64 lValue); Unicode (Windows) INT SetFileTagAsNumber(LPCWSTR lpszFileName, LPCWSTR lpszTagName, LONG64 lValue);
int cbfsstorage_cbvaultdrive_setfiletagasnumber(void* lpObj, const char* lpszFileName, const char* lpszTagName, int64 lValue);
int SetFileTagAsNumber(const QString& qsFileName, const QString& qsTagName, qint64 lValue);
Remarks
This method attaches a Number-typed file tag to the vault item (e.g., 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetFileTagAsString Method (CBVaultDrive Class)
This method attaches a String-typed file tag to the specified vault item.
Syntax
ANSI (Cross Platform) int SetFileTagAsString(const char* lpszFileName, const char* lpszTagName, const char* lpszValue); Unicode (Windows) INT SetFileTagAsString(LPCWSTR lpszFileName, LPCWSTR lpszTagName, LPCWSTR lpszValue);
int cbfsstorage_cbvaultdrive_setfiletagasstring(void* lpObj, const char* lpszFileName, const char* lpszTagName, const char* lpszValue);
int SetFileTagAsString(const QString& qsFileName, const QString& qsTagName, const QString& qsValue);
Remarks
This method attaches a String-typed file tag to the vault item (e.g., 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
SetIcon Method (CBVaultDrive Class)
Selects a registered overlay icon for display on the virtual drive in Windows File Explorer (Windows only).
Syntax
ANSI (Cross Platform) int SetIcon(const char* lpszIconId); Unicode (Windows) INT SetIcon(LPCWSTR lpszIconId);
int cbfsstorage_cbvaultdrive_seticon(void* lpObj, const char* lpszIconId);
int SetIcon(const QString& qsIconId);
Remarks
This method selects the overlay icon specified by IconId for display, causing it to be shown on the virtual drive in Windows File Explorer. The desired icon must have already been registered using the RegisterIcon method, and the value passed for IconId must match the one passed RegisterIcon 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 ResetIcon 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 GetModuleVersion method, and install it using the Install method if necessary.
Note: This method can be called only after creating a virtual drive, and it cannot be called within events. Also, note that the effects of this method only last until the virtual drive is destroyed; applications that always want to have some overlay icon displayed must call this method each time the virtual drive is created.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
ShutdownSystem Method (CBVaultDrive Class)
Shuts down or reboots the operating system.
Syntax
ANSI (Cross Platform) bool ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot); Unicode (Windows) bool ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);
bool cbfsstorage_cbvaultdrive_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);
bool ShutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);
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.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
Uninstall Method (CBVaultDrive Class)
Uninstalls the product's system drivers and/or helper DLL (Windows only).
Syntax
ANSI (Cross Platform) int Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags); Unicode (Windows) INT Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszInstalledPath, INT iFlags);
int cbfsstorage_cbvaultdrive_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);
int Uninstall(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsInstalledPath, int iFlags);
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_PREVIOUS | 0x00000001 | Uninstall modules from previous product versions.
Note: This functionality is only available in Windows. |
UNINSTALL_VERSION_CURRENT | 0x00000002 | Uninstall modules from the current product version.
Note: This functionality is only available in Windows. |
UNINSTALL_VERSION_ALL | 0x00000003 | Uninstall modules from all product versions.
Note: This functionality is only available in Windows. |
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.
Error Handling (C++)
This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
UnixTimeToFileTime Method (CBVaultDrive Class)
This method converts the date/time in Unix format to the Windows FileTime format.
Syntax
ANSI (Cross Platform) int64 UnixTimeToFileTime(int64 lUnixTime, int iNanoseconds); Unicode (Windows) LONG64 UnixTimeToFileTime(LONG64 lUnixTime, INT iNanoseconds);
int64 cbfsstorage_cbvaultdrive_unixtimetofiletime(void* lpObj, int64 lUnixTime, int iNanoseconds);
QDateTime UnixTimeToFileTime(qint64 lUnixTime, int iNanoseconds);
Remarks
Use this method to convert the date/time in Unix format to the 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.
Error Handling (C++)
This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
UnregisterIcon Method (CBVaultDrive Class)
Unregisters an existing overlay icon (Windows only).
Syntax
ANSI (Cross Platform) bool UnregisterIcon(const char* lpszProductGUID, const char* lpszIconId); Unicode (Windows) bool UnregisterIcon(LPCWSTR lpszProductGUID, LPCWSTR lpszIconId);
bool cbfsstorage_cbvaultdrive_unregistericon(void* lpObj, const char* lpszProductGUID, const char* lpszIconId);
bool UnregisterIcon(const QString& qsProductGUID, const QString& qsIconId);
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 RegisterIcon 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 GetModuleVersion 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.
Error Handling (C++)
This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
UpdateVaultEncryption Method (CBVaultDrive Class)
This method encrypts, decrypts, or changes the encryption password of the vault.
Syntax
ANSI (Cross Platform) int UpdateVaultEncryption(int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword); Unicode (Windows) INT UpdateVaultEncryption(INT iEncryption, LPCWSTR lpszOldPassword, LPCWSTR lpszNewPassword);
int cbfsstorage_cbvaultdrive_updatevaultencryption(void* lpObj, int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword);
int UpdateVaultEncryption(int iEncryption, const QString& qsOldPassword, const QString& qsNewPassword);
Remarks
This method changes the encryption mode or password used to encrypt the vault.
The Encryption parameter specifies the new encryption mode to use. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive 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 be called only when Active is true, and it cannot be called within events.
Error Handling (C++)
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)
DataCompress Event (CBVaultDrive Class)
This event fires to compress a block of data using a custom compression algorithm.
Syntax
ANSI (Cross Platform) virtual int FireDataCompress(CBVaultDriveDataCompressEventParams *e);
typedef struct {
const void *InData;
int InSize;
void *OutData;
int OutSize;
int CompressionLevel;
int ResultCode; int reserved; } CBVaultDriveDataCompressEventParams;
Unicode (Windows) virtual INT FireDataCompress(CBVaultDriveDataCompressEventParams *e);
typedef struct {
LPCVOID InData;
INT InSize;
LPVOID OutData;
INT OutSize;
INT CompressionLevel;
INT ResultCode; INT reserved; } CBVaultDriveDataCompressEventParams;
#define EID_CBVAULTDRIVE_DATACOMPRESS 1 virtual INT CBFSSTORAGE_CALL FireDataCompress(LPVOID &lpInData, INT &iInSize, LPVOID &lpOutData, INT &iOutSize, INT &iCompressionLevel, INT &iResultCode);
class CBVaultDriveDataCompressEventParams { public: const void *InData(); int InSize(); void *OutData(); int OutSize(); void SetOutSize(int iOutSize); int CompressionLevel(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void DataCompress(CBVaultDriveDataCompressEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireDataCompress(CBVaultDriveDataCompressEventParams *e) {...}
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: 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 see 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
DataDecompress Event (CBVaultDrive Class)
This event fires to decompress a block of data using a custom compression algorithm.
Syntax
ANSI (Cross Platform) virtual int FireDataDecompress(CBVaultDriveDataDecompressEventParams *e);
typedef struct {
const void *InData;
int InSize;
void *OutData;
int OutSize;
int ResultCode; int reserved; } CBVaultDriveDataDecompressEventParams;
Unicode (Windows) virtual INT FireDataDecompress(CBVaultDriveDataDecompressEventParams *e);
typedef struct {
LPCVOID InData;
INT InSize;
LPVOID OutData;
INT OutSize;
INT ResultCode; INT reserved; } CBVaultDriveDataDecompressEventParams;
#define EID_CBVAULTDRIVE_DATADECOMPRESS 2 virtual INT CBFSSTORAGE_CALL FireDataDecompress(LPVOID &lpInData, INT &iInSize, LPVOID &lpOutData, INT &iOutSize, INT &iResultCode);
class CBVaultDriveDataDecompressEventParams { public: const void *InData(); int InSize(); void *OutData(); int OutSize(); void SetOutSize(int iOutSize); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void DataDecompress(CBVaultDriveDataDecompressEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireDataDecompress(CBVaultDriveDataDecompressEventParams *e) {...}
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: 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 see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
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.
DataDecrypt Event (CBVaultDrive Class)
This event fires to decrypt a block of data using a custom encryption implementation.
Syntax
ANSI (Cross Platform) virtual int FireDataDecrypt(CBVaultDriveDataDecryptEventParams *e);
typedef struct {
const void *Key;
int KeyLength;
const void *Salt1;
int Salt1Size;
const void *Salt2;
int Salt2Size;
void *Data;
int DataSize;
int ResultCode; int reserved; } CBVaultDriveDataDecryptEventParams;
Unicode (Windows) virtual INT FireDataDecrypt(CBVaultDriveDataDecryptEventParams *e);
typedef struct {
LPCVOID Key;
INT KeyLength;
LPCVOID Salt1;
INT Salt1Size;
LPCVOID Salt2;
INT Salt2Size;
LPVOID Data;
INT DataSize;
INT ResultCode; INT reserved; } CBVaultDriveDataDecryptEventParams;
#define EID_CBVAULTDRIVE_DATADECRYPT 3 virtual INT CBFSSTORAGE_CALL FireDataDecrypt(LPVOID &lpKey, INT &iKeyLength, LPVOID &lpSalt1, INT &iSalt1Size, LPVOID &lpSalt2, INT &iSalt2Size, LPVOID &lpData, INT &iDataSize, INT &iResultCode);
class CBVaultDriveDataDecryptEventParams { public: const void *Key(); int KeyLength(); const void *Salt1(); int Salt1Size(); const void *Salt2(); int Salt2Size(); void *Data(); int DataSize(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void DataDecrypt(CBVaultDriveDataDecryptEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireDataDecrypt(CBVaultDriveDataDecryptEventParams *e) {...}
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 are 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 were encrypted in an earlier DataEncrypt event. The Salt1Size and Salt2Size parameters specify the length, in bytes, of Salt1 and Salt2.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
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.
DataEncrypt Event (CBVaultDrive Class)
This event fires to encrypt a block of data using a custom encryption implementation.
Syntax
ANSI (Cross Platform) virtual int FireDataEncrypt(CBVaultDriveDataEncryptEventParams *e);
typedef struct {
const void *Key;
int KeyLength;
const void *Salt1;
int Salt1Size;
const void *Salt2;
int Salt2Size;
void *Data;
int DataSize;
int ResultCode; int reserved; } CBVaultDriveDataEncryptEventParams;
Unicode (Windows) virtual INT FireDataEncrypt(CBVaultDriveDataEncryptEventParams *e);
typedef struct {
LPCVOID Key;
INT KeyLength;
LPCVOID Salt1;
INT Salt1Size;
LPCVOID Salt2;
INT Salt2Size;
LPVOID Data;
INT DataSize;
INT ResultCode; INT reserved; } CBVaultDriveDataEncryptEventParams;
#define EID_CBVAULTDRIVE_DATAENCRYPT 4 virtual INT CBFSSTORAGE_CALL FireDataEncrypt(LPVOID &lpKey, INT &iKeyLength, LPVOID &lpSalt1, INT &iSalt1Size, LPVOID &lpSalt2, INT &iSalt2Size, LPVOID &lpData, INT &iDataSize, INT &iResultCode);
class CBVaultDriveDataEncryptEventParams { public: const void *Key(); int KeyLength(); const void *Salt1(); int Salt1Size(); const void *Salt2(); int Salt2Size(); void *Data(); int DataSize(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void DataEncrypt(CBVaultDriveDataEncryptEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireDataEncrypt(CBVaultDriveDataEncryptEventParams *e) {...}
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 are 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 see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
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.
Ejected Event (CBVaultDrive Class)
Fires when the media and virtual drive have been ejected (Windows only).
Syntax
ANSI (Cross Platform) virtual int FireEjected(CBVaultDriveEjectedEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBVaultDriveEjectedEventParams;
Unicode (Windows) virtual INT FireEjected(CBVaultDriveEjectedEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBVaultDriveEjectedEventParams;
#define EID_CBVAULTDRIVE_EJECTED 5 virtual INT CBFSSTORAGE_CALL FireEjected(INT &iResultCode);
class CBVaultDriveEjectedEventParams { public: int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void Ejected(CBVaultDriveEjectedEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireEjected(CBVaultDriveEjectedEventParams *e) {...}
Remarks
This event fires when a user has ejected the media and virtual drive using the Eject command in Windows File Explorer.
For ejection via the system notification area (tray) to work correctly, the StorageType property must be set to STGT_DISK_PNP, and the StorageCharacteristics 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 CloseVault (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 Handling topic for more information.
Error Event (CBVaultDrive Class)
This event fires if an unhandled error occurs during an event.
Syntax
ANSI (Cross Platform) virtual int FireError(CBVaultDriveErrorEventParams *e);
typedef struct {
int ErrorCode;
const char *Description; int reserved; } CBVaultDriveErrorEventParams;
Unicode (Windows) virtual INT FireError(CBVaultDriveErrorEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR Description; INT reserved; } CBVaultDriveErrorEventParams;
#define EID_CBVAULTDRIVE_ERROR 6 virtual INT CBFSSTORAGE_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);
class CBVaultDriveErrorEventParams { public: int ErrorCode(); const QString &Description(); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void Error(CBVaultDriveErrorEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireError(CBVaultDriveErrorEventParams *e) {...}
Remarks
This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.
FileAccess Event (CBVaultDrive Class)
Fires when the OS wants to create or open a file or directory.
Syntax
ANSI (Cross Platform) virtual int FireFileAccess(CBVaultDriveFileAccessEventParams *e);
typedef struct {
const char *FileName;
int ExistingAttributes;
int DesiredAccess;
int Attributes;
int Options;
int ShareMode;
int ResultCode; int reserved; } CBVaultDriveFileAccessEventParams;
Unicode (Windows) virtual INT FireFileAccess(CBVaultDriveFileAccessEventParams *e);
typedef struct {
LPCWSTR FileName;
INT ExistingAttributes;
INT DesiredAccess;
INT Attributes;
INT Options;
INT ShareMode;
INT ResultCode; INT reserved; } CBVaultDriveFileAccessEventParams;
#define EID_CBVAULTDRIVE_FILEACCESS 7 virtual INT CBFSSTORAGE_CALL FireFileAccess(LPWSTR &lpszFileName, INT &iExistingAttributes, INT &iDesiredAccess, INT &iAttributes, INT &iOptions, INT &iShareMode, INT &iResultCode);
class CBVaultDriveFileAccessEventParams { public: const QString &FileName(); int ExistingAttributes(); int DesiredAccess(); int Attributes(); int Options(); int ShareMode(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void FileAccess(CBVaultDriveFileAccessEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireFileAccess(CBVaultDriveFileAccessEventParams *e) {...}
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_READ | 0x00000001 | Grant/deny read access. |
STG_DACCESS_WRITE | 0x00000002 | Grant/deny write access. |
STG_DACCESS_READWRITE | 0x00000003 | Grant/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_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that 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_READ | 0x00000001 | Enables 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_WRITE | 0x00000002 | Enables 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_DELETE | 0x00000004 | Enables 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 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.
FileAfterCopy Event (CBVaultDrive Class)
This event fires after the file has been copied during file export/import operations.
Syntax
ANSI (Cross Platform) virtual int FireFileAfterCopy(CBVaultDriveFileAfterCopyEventParams *e);
typedef struct {
const char *SourcePath;
const char *DestinationPath;
int Attributes;
int ResultCode; int reserved; } CBVaultDriveFileAfterCopyEventParams;
Unicode (Windows) virtual INT FireFileAfterCopy(CBVaultDriveFileAfterCopyEventParams *e);
typedef struct {
LPCWSTR SourcePath;
LPCWSTR DestinationPath;
INT Attributes;
INT ResultCode; INT reserved; } CBVaultDriveFileAfterCopyEventParams;
#define EID_CBVAULTDRIVE_FILEAFTERCOPY 8 virtual INT CBFSSTORAGE_CALL FireFileAfterCopy(LPWSTR &lpszSourcePath, LPWSTR &lpszDestinationPath, INT &iAttributes, INT &iResultCode);
class CBVaultDriveFileAfterCopyEventParams { public: const QString &SourcePath(); const QString &DestinationPath(); int Attributes(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void FileAfterCopy(CBVaultDriveFileAfterCopyEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireFileAfterCopy(CBVaultDriveFileAfterCopyEventParams *e) {...}
Remarks
This event fires when the class is executing the CopyToVault or CopyFromVault 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 CopyFromVault or CopyToVault method. Also, the event will not fire for the base directory that was passed to the CopyToVault or CopyFromVault 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_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
FileBeforeCopy Event (CBVaultDrive Class)
This event fires before the file is copied during file export/import operations.
Syntax
ANSI (Cross Platform) virtual int FireFileBeforeCopy(CBVaultDriveFileBeforeCopyEventParams *e);
typedef struct {
const char *SourcePath;
const char *DestinationPath;
int Attributes;
int DestinationExists;
int Skip;
int ResultCode; int reserved; } CBVaultDriveFileBeforeCopyEventParams;
Unicode (Windows) virtual INT FireFileBeforeCopy(CBVaultDriveFileBeforeCopyEventParams *e);
typedef struct {
LPCWSTR SourcePath;
LPCWSTR DestinationPath;
INT Attributes;
BOOL DestinationExists;
BOOL Skip;
INT ResultCode; INT reserved; } CBVaultDriveFileBeforeCopyEventParams;
#define EID_CBVAULTDRIVE_FILEBEFORECOPY 9 virtual INT CBFSSTORAGE_CALL FireFileBeforeCopy(LPWSTR &lpszSourcePath, LPWSTR &lpszDestinationPath, INT &iAttributes, BOOL &bDestinationExists, BOOL &bSkip, INT &iResultCode);
class CBVaultDriveFileBeforeCopyEventParams { public: const QString &SourcePath(); const QString &DestinationPath(); int Attributes(); void SetAttributes(int iAttributes); bool DestinationExists(); bool Skip(); void SetSkip(bool bSkip); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void FileBeforeCopy(CBVaultDriveFileBeforeCopyEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireFileBeforeCopy(CBVaultDriveFileBeforeCopyEventParams *e) {...}
Remarks
This event fires when the class is executing the CopyToVault or CopyFromVault 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.
This event will fire only if the VAULT_CFF_FIRE_COPY_EVENTS flag is included in the Flags parameter of the CopyFromVault or CopyToVault method. Also, the event will not fire for the base directory that was passed to the CopyToVault or CopyFromVault method.
A process may check whether it is a file or a 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_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Storage, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The 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_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that 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 imported to the vault, an event handler may set user-defined flags that match the VAULT_FATTR_USER_DEFINED mask.
The DestinationExists flag indicates the presence of the file or directory at the moment when the event is fired.
Note: When copying the files from the vault, it is possible 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, FileAfterCopy 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
FilePasswordNeeded Event (CBVaultDrive Class)
This event fires if a password is needed to open an encrypted file.
Syntax
ANSI (Cross Platform) virtual int FireFilePasswordNeeded(CBVaultDriveFilePasswordNeededEventParams *e);
typedef struct {
const char *FileName;
char *Password; int lenPassword;
int TTLInCache;
int ResultCode; int reserved; } CBVaultDriveFilePasswordNeededEventParams;
Unicode (Windows) virtual INT FireFilePasswordNeeded(CBVaultDriveFilePasswordNeededEventParams *e);
typedef struct {
LPCWSTR FileName;
LPWSTR Password; INT lenPassword;
INT TTLInCache;
INT ResultCode; INT reserved; } CBVaultDriveFilePasswordNeededEventParams;
#define EID_CBVAULTDRIVE_FILEPASSWORDNEEDED 10 virtual INT CBFSSTORAGE_CALL FireFilePasswordNeeded(LPWSTR &lpszFileName, LPWSTR &lpPassword, INT &lenPassword, INT &iTTLInCache, INT &iResultCode);
class CBVaultDriveFilePasswordNeededEventParams { public: const QString &FileName(); const QString &Password(); bool SetPassword(const QString &lpPassword); int TTLInCache(); void SetTTLInCache(int iTTLInCache); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void FilePasswordNeeded(CBVaultDriveFilePasswordNeededEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireFilePasswordNeeded(CBVaultDriveFilePasswordNeededEventParams *e) {...}
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 DefaultFileAccessPassword property or CacheFilePassword 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. Note that the value must be copied to Password; set lenPassword to the length of the copied string (measured in char/wchar_t, not including terminating nulls).
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: 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 DefaultFileAccessPassword property or can call the CacheFilePassword 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
HashCalculate Event (CBVaultDrive Class)
This event fires to calculate a password hash using a custom hashing implementation.
Syntax
ANSI (Cross Platform) virtual int FireHashCalculate(CBVaultDriveHashCalculateEventParams *e);
typedef struct {
const void *Password;
int PasswordSize;
const void *Salt;
int SaltSize;
void *Hash;
int HashSize;
int ResultCode; int reserved; } CBVaultDriveHashCalculateEventParams;
Unicode (Windows) virtual INT FireHashCalculate(CBVaultDriveHashCalculateEventParams *e);
typedef struct {
LPCVOID Password;
INT PasswordSize;
LPCVOID Salt;
INT SaltSize;
LPVOID Hash;
INT HashSize;
INT ResultCode; INT reserved; } CBVaultDriveHashCalculateEventParams;
#define EID_CBVAULTDRIVE_HASHCALCULATE 11 virtual INT CBFSSTORAGE_CALL FireHashCalculate(LPVOID &lpPassword, INT &iPasswordSize, LPVOID &lpSalt, INT &iSaltSize, LPVOID &lpHash, INT &iHashSize, INT &iResultCode);
class CBVaultDriveHashCalculateEventParams { public: const void *Password(); int PasswordSize(); const void *Salt(); int SaltSize(); void *Hash(); int HashSize(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void HashCalculate(CBVaultDriveHashCalculateEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireHashCalculate(CBVaultDriveHashCalculateEventParams *e) {...}
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 needs to be handled only 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 perform, if desired, 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 see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
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.
KeyDerive Event (CBVaultDrive Class)
This event fires to derive an encryption key using a custom key derivation implementation.
Syntax
ANSI (Cross Platform) virtual int FireKeyDerive(CBVaultDriveKeyDeriveEventParams *e);
typedef struct {
const void *Password;
int PasswordSize;
const void *Salt;
int SaltSize;
void *Key;
int KeySize;
int ResultCode; int reserved; } CBVaultDriveKeyDeriveEventParams;
Unicode (Windows) virtual INT FireKeyDerive(CBVaultDriveKeyDeriveEventParams *e);
typedef struct {
LPCVOID Password;
INT PasswordSize;
LPCVOID Salt;
INT SaltSize;
LPVOID Key;
INT KeySize;
INT ResultCode; INT reserved; } CBVaultDriveKeyDeriveEventParams;
#define EID_CBVAULTDRIVE_KEYDERIVE 12 virtual INT CBFSSTORAGE_CALL FireKeyDerive(LPVOID &lpPassword, INT &iPasswordSize, LPVOID &lpSalt, INT &iSaltSize, LPVOID &lpKey, INT &iKeySize, INT &iResultCode);
class CBVaultDriveKeyDeriveEventParams { public: const void *Password(); int PasswordSize(); const void *Salt(); int SaltSize(); void *Key(); int KeySize(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void KeyDerive(CBVaultDriveKeyDeriveEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireKeyDerive(CBVaultDriveKeyDeriveEventParams *e) {...}
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 needs to be handled only 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 see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
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.
Progress Event (CBVaultDrive Class)
This event fires to indicate the progress of long-running vault operations.
Syntax
ANSI (Cross Platform) virtual int FireProgress(CBVaultDriveProgressEventParams *e);
typedef struct {
int Operation;
const char *FileName;
int Progress;
int Total;
int CanStop;
int Stop; int reserved; } CBVaultDriveProgressEventParams;
Unicode (Windows) virtual INT FireProgress(CBVaultDriveProgressEventParams *e);
typedef struct {
INT Operation;
LPCWSTR FileName;
INT Progress;
INT Total;
BOOL CanStop;
BOOL Stop; INT reserved; } CBVaultDriveProgressEventParams;
#define EID_CBVAULTDRIVE_PROGRESS 13 virtual INT CBFSSTORAGE_CALL FireProgress(INT &iOperation, LPWSTR &lpszFileName, INT &iProgress, INT &iTotal, BOOL &bCanStop, BOOL &bStop);
class CBVaultDriveProgressEventParams { public: int Operation(); const QString &FileName(); int Progress(); int Total(); bool CanStop(); bool Stop(); void SetStop(bool bStop); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void Progress(CBVaultDriveProgressEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireProgress(CBVaultDriveProgressEventParams *e) {...}
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 as follows:
VAULT_PO_FORMATTING | 0 | Formatting a vault. |
VAULT_PO_CHECKING_1 | 1 | Checking a vault (stage 1). |
VAULT_PO_CHECKING_2 | 2 | Checking a vault (stage 2). |
VAULT_PO_CHECKING_3 | 3 | Checking a vault (stage 3). |
VAULT_PO_CHECKING_4 | 4 | Checking a vault (stage 4). |
VAULT_PO_CHECKING_5 | 5 | Checking a vault (stage 5). |
VAULT_PO_PAGE_CORRUPTED | 8 | Processing a corrupted vault page. |
VAULT_PO_PAGE_ORPHANED | 9 | Processing an orphaned vault page. |
VAULT_PO_COMPRESSING | 10 | Compressing a file or alternate stream. |
VAULT_PO_DECOMPRESSING | 11 | Decompressing a file or alternate stream. |
VAULT_PO_ENCRYPTING | 12 | Encrypting a vault, file, or alternate stream. |
VAULT_PO_DECRYPTING | 13 | Decrypting a vault, file, or alternate stream |
VAULT_PO_COMPACTING | 14 | Compacting a vault. |
VAULT_PO_RESIZING | 15 | Resizing a vault. |
VAULT_PO_CALCULATING_SIZE | 16 | Calculating a vault's size. |
VAULT_PO_COPYING_FILES_TO_VAULT | 17 | Copying files to a vault. |
VAULT_PO_COPYING_FILES_FROM_VAULT | 18 | Copying files from a vault. |
When the operation is copying 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: Some operations can be interrupted only 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.
VaultClose Event (CBVaultDrive Class)
This event fires to close a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultClose(CBVaultDriveVaultCloseEventParams *e);
typedef struct {
int64 VaultHandle;
int ResultCode; int reserved; } CBVaultDriveVaultCloseEventParams;
Unicode (Windows) virtual INT FireVaultClose(CBVaultDriveVaultCloseEventParams *e);
typedef struct {
LONG64 VaultHandle;
INT ResultCode; INT reserved; } CBVaultDriveVaultCloseEventParams;
#define EID_CBVAULTDRIVE_VAULTCLOSE 14 virtual INT CBFSSTORAGE_CALL FireVaultClose(LONG64 &lVaultHandle, INT &iResultCode);
class CBVaultDriveVaultCloseEventParams { public: qint64 VaultHandle(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultClose(CBVaultDriveVaultCloseEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultClose(CBVaultDriveVaultCloseEventParams *e) {...}
Remarks
This event fires when the class needs to close the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultDelete Event (CBVaultDrive Class)
This event fires to delete a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultDelete(CBVaultDriveVaultDeleteEventParams *e);
typedef struct {
const char *Vault;
int ResultCode; int reserved; } CBVaultDriveVaultDeleteEventParams;
Unicode (Windows) virtual INT FireVaultDelete(CBVaultDriveVaultDeleteEventParams *e);
typedef struct {
LPCWSTR Vault;
INT ResultCode; INT reserved; } CBVaultDriveVaultDeleteEventParams;
#define EID_CBVAULTDRIVE_VAULTDELETE 15 virtual INT CBFSSTORAGE_CALL FireVaultDelete(LPWSTR &lpszVault, INT &iResultCode);
class CBVaultDriveVaultDeleteEventParams { public: const QString &Vault(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultDelete(CBVaultDriveVaultDeleteEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultDelete(CBVaultDriveVaultDeleteEventParams *e) {...}
Remarks
This event fires when the class needs to delete the callback mode vault identified by Vault.
This event needs to be handled only if the CallbackMode 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 (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultFlush Event (CBVaultDrive Class)
This event fires to flush a callback mode vault's data out to storage.
Syntax
ANSI (Cross Platform) virtual int FireVaultFlush(CBVaultDriveVaultFlushEventParams *e);
typedef struct {
int64 VaultHandle;
int ResultCode; int reserved; } CBVaultDriveVaultFlushEventParams;
Unicode (Windows) virtual INT FireVaultFlush(CBVaultDriveVaultFlushEventParams *e);
typedef struct {
LONG64 VaultHandle;
INT ResultCode; INT reserved; } CBVaultDriveVaultFlushEventParams;
#define EID_CBVAULTDRIVE_VAULTFLUSH 16 virtual INT CBFSSTORAGE_CALL FireVaultFlush(LONG64 &lVaultHandle, INT &iResultCode);
class CBVaultDriveVaultFlushEventParams { public: qint64 VaultHandle(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultFlush(CBVaultDriveVaultFlushEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultFlush(CBVaultDriveVaultFlushEventParams *e) {...}
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 needs to be handled only if the CallbackMode 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultGetParentSize Event (CBVaultDrive Class)
This event fires to determine how much free space is available for growing a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultGetParentSize(CBVaultDriveVaultGetParentSizeEventParams *e);
typedef struct {
const char *Vault;
int64 VaultHandle;
int64 *pFreeSpace;
int ResultCode; int reserved; } CBVaultDriveVaultGetParentSizeEventParams;
Unicode (Windows) virtual INT FireVaultGetParentSize(CBVaultDriveVaultGetParentSizeEventParams *e);
typedef struct {
LPCWSTR Vault;
LONG64 VaultHandle;
LONG64 *pFreeSpace;
INT ResultCode; INT reserved; } CBVaultDriveVaultGetParentSizeEventParams;
#define EID_CBVAULTDRIVE_VAULTGETPARENTSIZE 17 virtual INT CBFSSTORAGE_CALL FireVaultGetParentSize(LPWSTR &lpszVault, LONG64 &lVaultHandle, LONG64 &lFreeSpace, INT &iResultCode);
class CBVaultDriveVaultGetParentSizeEventParams { public: const QString &Vault(); qint64 VaultHandle(); qint64 FreeSpace(); void SetFreeSpace(qint64 lFreeSpace); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultGetParentSize(CBVaultDriveVaultGetParentSizeEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultGetParentSize(CBVaultDriveVaultGetParentSizeEventParams *e) {...}
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 needs to be handled only if the CallbackMode 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 (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile property.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultGetSize Event (CBVaultDrive Class)
This event fires to determine the size of a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultGetSize(CBVaultDriveVaultGetSizeEventParams *e);
typedef struct {
int64 VaultHandle;
int64 *pSize;
int ResultCode; int reserved; } CBVaultDriveVaultGetSizeEventParams;
Unicode (Windows) virtual INT FireVaultGetSize(CBVaultDriveVaultGetSizeEventParams *e);
typedef struct {
LONG64 VaultHandle;
LONG64 *pSize;
INT ResultCode; INT reserved; } CBVaultDriveVaultGetSizeEventParams;
#define EID_CBVAULTDRIVE_VAULTGETSIZE 18 virtual INT CBFSSTORAGE_CALL FireVaultGetSize(LONG64 &lVaultHandle, LONG64 &lSize, INT &iResultCode);
class CBVaultDriveVaultGetSizeEventParams { public: qint64 VaultHandle(); qint64 Size(); void SetSize(qint64 lSize); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultGetSize(CBVaultDriveVaultGetSizeEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultGetSize(CBVaultDriveVaultGetSizeEventParams *e) {...}
Remarks
This event fires when the class needs to determine the size of the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultOpen Event (CBVaultDrive Class)
This event fires to open a new or existing callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultOpen(CBVaultDriveVaultOpenEventParams *e);
typedef struct {
const char *Vault;
int64 *pVaultHandle;
int OpenMode;
int ReadOnly;
int ResultCode; int reserved; } CBVaultDriveVaultOpenEventParams;
Unicode (Windows) virtual INT FireVaultOpen(CBVaultDriveVaultOpenEventParams *e);
typedef struct {
LPCWSTR Vault;
LONG64 *pVaultHandle;
INT OpenMode;
BOOL ReadOnly;
INT ResultCode; INT reserved; } CBVaultDriveVaultOpenEventParams;
#define EID_CBVAULTDRIVE_VAULTOPEN 19 virtual INT CBFSSTORAGE_CALL FireVaultOpen(LPWSTR &lpszVault, LONG64 &lVaultHandle, INT &iOpenMode, BOOL &bReadOnly, INT &iResultCode);
class CBVaultDriveVaultOpenEventParams { public: const QString &Vault(); qint64 VaultHandle(); void SetVaultHandle(qint64 lVaultHandle); int OpenMode(); bool ReadOnly(); void SetReadOnly(bool bReadOnly); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultOpen(CBVaultDriveVaultOpenEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultOpen(CBVaultDriveVaultOpenEventParams *e) {...}
Remarks
This event fires when the class wants to open the callback mode vault identified by Vault.
This event needs to be handled only if the CallbackMode 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 any 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. It 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 (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile 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 as follows:
VAULT_OM_CREATE_NEW | 0 | Creates a new vault if possible, failing if one already exists. |
VAULT_OM_CREATE_ALWAYS | 1 | Creates a new vault, overwriting an existing one if necessary. |
VAULT_OM_OPEN_EXISTING | 2 | Opens a vault if it exists; fails otherwise. |
VAULT_OM_OPEN_ALWAYS | 3 | Opens 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultRead Event (CBVaultDrive Class)
This event fires to read data from a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultRead(CBVaultDriveVaultReadEventParams *e);
typedef struct {
int64 VaultHandle;
int64 Offset;
void *Buffer;
int Count;
int ResultCode; int reserved; } CBVaultDriveVaultReadEventParams;
Unicode (Windows) virtual INT FireVaultRead(CBVaultDriveVaultReadEventParams *e);
typedef struct {
LONG64 VaultHandle;
LONG64 Offset;
LPVOID Buffer;
INT Count;
INT ResultCode; INT reserved; } CBVaultDriveVaultReadEventParams;
#define EID_CBVAULTDRIVE_VAULTREAD 20 virtual INT CBFSSTORAGE_CALL FireVaultRead(LONG64 &lVaultHandle, LONG64 &lOffset, LPVOID &lpBuffer, INT &iCount, INT &iResultCode);
class CBVaultDriveVaultReadEventParams { public: qint64 VaultHandle(); qint64 Offset(); void *Buffer(); int Count(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultRead(CBVaultDriveVaultReadEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultRead(CBVaultDriveVaultReadEventParams *e) {...}
Remarks
This event fires when the class needs to read data from the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode 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 PageSize. 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 see 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultSetSize Event (CBVaultDrive Class)
This event fires to resize a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultSetSize(CBVaultDriveVaultSetSizeEventParams *e);
typedef struct {
int64 VaultHandle;
int64 NewSize;
int ResultCode; int reserved; } CBVaultDriveVaultSetSizeEventParams;
Unicode (Windows) virtual INT FireVaultSetSize(CBVaultDriveVaultSetSizeEventParams *e);
typedef struct {
LONG64 VaultHandle;
LONG64 NewSize;
INT ResultCode; INT reserved; } CBVaultDriveVaultSetSizeEventParams;
#define EID_CBVAULTDRIVE_VAULTSETSIZE 21 virtual INT CBFSSTORAGE_CALL FireVaultSetSize(LONG64 &lVaultHandle, LONG64 &lNewSize, INT &iResultCode);
class CBVaultDriveVaultSetSizeEventParams { public: qint64 VaultHandle(); qint64 NewSize(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultSetSize(CBVaultDriveVaultSetSizeEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultSetSize(CBVaultDriveVaultSetSizeEventParams *e) {...}
Remarks
This event fires when the class needs to resize the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode 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 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
VaultWrite Event (CBVaultDrive Class)
This event fires to write data to a callback mode vault.
Syntax
ANSI (Cross Platform) virtual int FireVaultWrite(CBVaultDriveVaultWriteEventParams *e);
typedef struct {
int64 VaultHandle;
int64 Offset;
const void *Buffer;
int Count;
int ResultCode; int reserved; } CBVaultDriveVaultWriteEventParams;
Unicode (Windows) virtual INT FireVaultWrite(CBVaultDriveVaultWriteEventParams *e);
typedef struct {
LONG64 VaultHandle;
LONG64 Offset;
LPCVOID Buffer;
INT Count;
INT ResultCode; INT reserved; } CBVaultDriveVaultWriteEventParams;
#define EID_CBVAULTDRIVE_VAULTWRITE 22 virtual INT CBFSSTORAGE_CALL FireVaultWrite(LONG64 &lVaultHandle, LONG64 &lOffset, LPVOID &lpBuffer, INT &iCount, INT &iResultCode);
class CBVaultDriveVaultWriteEventParams { public: qint64 VaultHandle(); qint64 Offset(); const void *Buffer(); int Count(); int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void VaultWrite(CBVaultDriveVaultWriteEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireVaultWrite(CBVaultDriveVaultWriteEventParams *e) {...}
Remarks
This event fires when the class needs to write data to the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode 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 PageSize. 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 see 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 VaultOpen 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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: 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.
WorkerThreadCreation Event (CBVaultDrive Class)
Fires just after a new worker thread is created.
Syntax
ANSI (Cross Platform) virtual int FireWorkerThreadCreation(CBVaultDriveWorkerThreadCreationEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBVaultDriveWorkerThreadCreationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadCreation(CBVaultDriveWorkerThreadCreationEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBVaultDriveWorkerThreadCreationEventParams;
#define EID_CBVAULTDRIVE_WORKERTHREADCREATION 23 virtual INT CBFSSTORAGE_CALL FireWorkerThreadCreation(INT &iResultCode);
class CBVaultDriveWorkerThreadCreationEventParams { public: int ResultCode(); void SetResultCode(int iResultCode); int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void WorkerThreadCreation(CBVaultDriveWorkerThreadCreationEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireWorkerThreadCreation(CBVaultDriveWorkerThreadCreationEventParams *e) {...}
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 is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
WorkerThreadTermination Event (CBVaultDrive Class)
Fires just before a worker thread is terminated.
Syntax
ANSI (Cross Platform) virtual int FireWorkerThreadTermination(CBVaultDriveWorkerThreadTerminationEventParams *e);
typedef struct { int reserved; } CBVaultDriveWorkerThreadTerminationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadTermination(CBVaultDriveWorkerThreadTerminationEventParams *e);
typedef struct { INT reserved; } CBVaultDriveWorkerThreadTerminationEventParams;
#define EID_CBVAULTDRIVE_WORKERTHREADTERMINATION 24 virtual INT CBFSSTORAGE_CALL FireWorkerThreadTermination();
class CBVaultDriveWorkerThreadTerminationEventParams { public: int EventRetVal(); void SetEventRetVal(int iRetVal); };
// To handle, connect one or more slots to this signal. void WorkerThreadTermination(CBVaultDriveWorkerThreadTerminationEventParams *e);
// Or, subclass CBVaultDrive and override this emitter function. virtual int FireWorkerThreadTermination(CBVaultDriveWorkerThreadTerminationEventParams *e) {...}
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.
MountingPoint Type
Represents a mounting point for the virtual drive.
Syntax
CBFSStorageMountingPoint (declared in cbfsstorage.h)
Remarks
This type represents a mounting point for the virtual drive.
Fields
AuthenticationId
int64 (read-only)
Default Value: 0
The Authentication ID used when creating the mounting point, if applicable.
If the STGMP_LOCAL flag is included in the Flags value, this field 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.
Flags
int (read-only)
Default Value: 0
The flags used to create the mounting point.
This field reflects the flags used to create the mounting point. It is a combination of zero or more of the following:
STGMP_SIMPLE | 0x00010000 | Create 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_MANAGER | 0x00020000 | Create a mounting point that appears to the system as a physical device.
When the StorageType 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_NETWORK | 0x00040000 | Create a network mounting point.
Network mounting points can be further configured using the various STGMP_NETWORK_* flags described below. Applications that plan to make use of network mounting points must be sure to install the Helper DLL before doing so, otherwise Windows File Explorer will not correctly recognize the "network" drive. This flag cannot be combined with STGMP_SIMPLE or STGMP_MOUNT_MANAGER. |
STGMP_LOCAL | 0x10000000 | Specifies 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 AddMountingPoint 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_DRIVE | 0x00000001 | Indicates that users may assign a drive letter to the share (e.g., using the 'Map network drive...' context menu item in Windows File Explorer). |
STGMP_NETWORK_HIDDEN_SHARE | 0x00000002 | Indicates 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_ACCESS | 0x00000004 | Makes 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_ACCESS | 0x00000008 | Makes 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_NAME | 0x00000010 | Specifies 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_ASYNC | 0x20000000 | Causes the method to return immediately without waiting for mounting notifications to be sent to the system. |
STGMP_AUTOCREATE_DRIVE_LETTER | 0x40000000 | Tells 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. |
Name
char* (read-only)
Default Value: ""
The mounting point name.
This field reflects the name of the mounting point (i.e., the value passed to the AddMountingPoint method's MountingPoint parameter).
OpenFile Type
Represents an open filesystem object from the virtual drive.
Syntax
CBFSStorageOpenFile (declared in cbfsstorage.h)
Remarks
This type represents an open filesystem object (file, directory, etc.) from the virtual drive.
Fields
Name
char* (read-only)
Default Value: ""
The name of the open file.
This field reflects the name of the open file.
ProcessId
int (read-only)
Default Value: 0
The Id of the process that opened the file.
This field reflects the Id of the process (PID) that opened the file.
ProcessName
char* (read-only)
Default Value: ""
The name of the process that opened the file.
This field reflects the name of the process that opened the file.
ProcessAccessRule Type
Represents an access rule granting or denying some process a specific access right.
Syntax
CBFSStorageProcessAccessRule (declared in cbfsstorage.h)
Remarks
This type represents an access rule that grants or denies some process a specific access right.
Fields
DesiredAccess
int (read-only)
Default Value: 0
The kind of access granted or denied.
This field specifies what kind of access is granted or denied by the rule. Possible values are:
STG_DACCESS_READ | 0x00000001 | Grant/deny read access. |
STG_DACCESS_WRITE | 0x00000002 | Grant/deny write access. |
STG_DACCESS_READWRITE | 0x00000003 | Grant/deny read and write access. |
IncludeChildren
int (read-only)
Default Value: FALSE
Whether child processes are affected.
This field indicates whether the rule applies to children of the target process.
ProcessId
int (read-only)
Default Value: 0
The Id of the target process.
This field reflects the target process's Id (PID). Will be 0 if the target process was specified by ProcessName, or -1 if the rule applies to all processes.
ProcessName
char* (read-only)
Default Value: ""
The filename of the target process's executable.
This field reflects the full file name of the target process's executable. Will be empty if the target process was specified by ProcessId (or if the rule applies to all processes, in which case ProcessId will be -1).
CBFSStorageList Type
Syntax
CBFSStorageList<T> (declared in cbfsstorage.h)
Remarks
CBFSStorageList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the CBVaultDrive class.
Methods | |
GetCount |
This method returns the current size of the collection.
int GetCount() {}
|
SetCount |
This method sets the size of the collection. This method returns 0 if setting the size was successful; or -1 if the collection is ReadOnly. When adding additional objects to a collection call this method to specify the new size. Increasing the size of the collection preserves existing objects in the collection.
int SetCount(int count) {}
|
Get |
This method gets the item at the specified position. The index parameter specifies the index of the item in the collection. This method returns NULL if an invalid index is specified.
T* Get(int index) {}
|
Set |
This method sets the item at the specified position. The index parameter specifies the index of the item in the collection that is being set. This method returns -1 if an invalid index is specified. Note: Objects created using the new operator must be freed using the delete operator; they will not be automatically freed by the class.
T* Set(int index, T* value) {}
|
CBFSStorageStream Type
Syntax
CBFSStorageStream (declared in cbfsstorage.h)
Remarks
The CBFSStorageStream type is returned by some of the CBVaultDrive class's methods. All stream types in CBFS Storage share a common API, documented below.
Properties | |
Length |
Gets or sets the length of the stream, in bytes.
int64 GetLength(); |
Position |
Gets or sets the current position within the stream.
int64 GetPosition(); |
Methods | |
Close |
Closes the stream, releasing all resources currently allocated for it.
void Close(); This method is called automatically when a CBFSStorageStream object is deleted. |
Flush |
Forces all data held by the stream's buffers to be written out to storage.
void Flush(); |
GetLastError |
If the previous operation failed, returns the associated error message, if any.
char* GetLastError(); |
GetLastErrorCode |
If the previous operation failed, returns a non-zero error code; otherwise returns zero.
int GetLastErrorCode(); This method will always return -1 after Close has been called. |
Read |
Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read.
int Read(void* buffer, int count); Buffer specifies the buffer to populate with data from the stream. Count specifies the number of bytes that should be read from the stream. Returns the total number of bytes read into Buffer. This may be less than Count if that many bytes are not currently available, or may be 0 if the end of the stream has been reached. |
Seek |
Sets the current position within the stream based on a particular point of origin.
int64 Seek(int64 offset, SeekOrigin origin); Offset specifies the offset in the stream to seek to, relative to Origin. SeekOrigin is an enum declared alongside the CBFSStorageStream class as shown above. Returns the new position within 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.
int Write(void* buffer, int count); Buffer specifies the buffer with data to write to the stream. Count specifies the number of bytes that should be written to the stream. Returns the total number of bytes written to the stream. |
Config Settings (CBVaultDrive Class)
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
By default, this setting is disabled, and alternate streams can be renamed only within the same file, and cannot be moved between them.
Note: This setting cannot be changed within events.
By default, this setting is enabled, and the broadcast is sent asynchronously. This is typically sufficient, but applications may disable this setting if they find that Windows File Explorer is still presenting virtual drives as available after they've been deleted (which may occur if the application exits immediately after deleting a virtual drive).
By default, this setting is set to 0, and automatic compaction operations will start without delay.
Note: This setting cannot be changed within events.
By default, this setting is set to 0.
This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.
A vault's maximum nonpaged name length is permanent, and it cannot be changed after the vault is created. When a vault is open, this configuration setting cannot be changed, and it can be queried only 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 PageSize.
Note: This setting cannot be changed when Active is true, and it cannot be changed within events.
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.
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.
This configuration 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 eight pages, so this setting's minimum valid value is eight times the value of the PageSize property.
By default, this configuration setting is set to 16777216 (16 MB).
Note: This setting can be changed only when Active is true.
A multipart vault's part size is permanent, and it cannot be changed after the vault is created. When a vault is open, this configuration setting cannot be changed, and it can be queried only 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 it cannot be changed within events.
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.
By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).
Note: This setting cannot be changed when Active is true, and it cannot be changed within events.
Trappable Errors (CBVaultDrive Class)
Error Handling (C++)
Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.
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 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 CheckAndRepair. (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 | No other files, directories, symbolic links, or alternate streams 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 | Cannot 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 (possibly 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 | Cannot 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. |
191 | ERROR_INVALID_EXE_SIGNATURE: Reported by the Install method when the CAB file signature cannot be validated. |
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. |