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 CBVAULT class. In addition to allowing applications to create and interact with a vault directly, the CBVaultDrive class can mount a vault as a virtual drive, allowing its contents to be accessed by the system and third-party applications.

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

Getting Started

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

Here's how to get up and running:

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

Property List

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

Method List

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

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.

Config Settings

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

AccessDeniedProcessCount Property (CBVaultDrive Class)

The number of records in the AccessDeniedProcess arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessCount();

Unicode (Windows)
INT GetAccessDeniedProcessCount();

int cbfsstorage_cbvaultdrive_getaccessdeniedprocesscount(void* lpObj);

int GetAccessDeniedProcessCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• AccessDeniedProcessDesiredAccess
• AccessDeniedProcessId
• AccessDeniedProcessIncludeChildren
• AccessDeniedProcessName

The array indices start at 0 and end at AccessDeniedProcessCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

AccessDeniedProcessDesiredAccess Property (CBVaultDrive Class)

The kind of access granted or denied.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessDesiredAccess(int iAccessDeniedProcessIndex);

Unicode (Windows)
INT GetAccessDeniedProcessDesiredAccess(INT iAccessDeniedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessdeniedprocessdesiredaccess(void* lpObj, int accessdeniedprocessindex);

int GetAccessDeniedProcessDesiredAccess(int iAccessDeniedProcessIndex);

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only and not available at design time.

Data Type

Integer

AccessDeniedProcessIncludeChildren Property (CBVaultDrive Class)

Whether child processes are affected.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessIncludeChildren(int iAccessDeniedProcessIndex);

Unicode (Windows)
BOOL GetAccessDeniedProcessIncludeChildren(INT iAccessDeniedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessdeniedprocessincludechildren(void* lpObj, int accessdeniedprocessindex);

bool GetAccessDeniedProcessIncludeChildren(int iAccessDeniedProcessIndex);

Default Value

FALSE

Remarks

Whether child processes are affected.

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

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only and not available at design time.

Data Type

Boolean

AccessDeniedProcessId Property (CBVaultDrive Class)

The Id of the target process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessDeniedProcessId(int iAccessDeniedProcessIndex);

Unicode (Windows)
INT GetAccessDeniedProcessId(INT iAccessDeniedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessdeniedprocessid(void* lpObj, int accessdeniedprocessindex);

int GetAccessDeniedProcessId(int iAccessDeniedProcessIndex);

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by AccessDeniedProcessProcessName, or -1 if the rule applies to all processes.

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only and not available at design time.

Data Type

Integer

AccessDeniedProcessName Property (CBVaultDrive Class)

The filename of the target process's executable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessDeniedProcessName(int iAccessDeniedProcessIndex);

Unicode (Windows)
LPWSTR GetAccessDeniedProcessName(INT iAccessDeniedProcessIndex);

char* cbfsstorage_cbvaultdrive_getaccessdeniedprocessname(void* lpObj, int accessdeniedprocessindex);

QString GetAccessDeniedProcessName(int iAccessDeniedProcessIndex);

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename of the target process's executable. Will be empty if the target process was specified by AccessDeniedProcessProcessId (or if the rule applies to all processes, in which case AccessDeniedProcessProcessId will be -1).

The AccessDeniedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessDeniedProcessCount property.

This property is read-only and not available at design time.

Data Type

String

AccessGrantedProcessCount Property (CBVaultDrive Class)

The number of records in the AccessGrantedProcess arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessCount();

Unicode (Windows)
INT GetAccessGrantedProcessCount();

int cbfsstorage_cbvaultdrive_getaccessgrantedprocesscount(void* lpObj);

int GetAccessGrantedProcessCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• AccessGrantedProcessDesiredAccess
• AccessGrantedProcessId
• AccessGrantedProcessIncludeChildren
• AccessGrantedProcessName

The array indices start at 0 and end at AccessGrantedProcessCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

AccessGrantedProcessDesiredAccess Property (CBVaultDrive Class)

The kind of access granted or denied.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessDesiredAccess(int iAccessGrantedProcessIndex);

Unicode (Windows)
INT GetAccessGrantedProcessDesiredAccess(INT iAccessGrantedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessgrantedprocessdesiredaccess(void* lpObj, int accessgrantedprocessindex);

int GetAccessGrantedProcessDesiredAccess(int iAccessGrantedProcessIndex);

Default Value

0

Remarks

The kind of access granted or denied.

This property specifies what kind of access is granted or denied by the rule. Possible values are:

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only and not available at design time.

Data Type

Integer

AccessGrantedProcessIncludeChildren Property (CBVaultDrive Class)

Whether child processes are affected.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessIncludeChildren(int iAccessGrantedProcessIndex);

Unicode (Windows)
BOOL GetAccessGrantedProcessIncludeChildren(INT iAccessGrantedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessgrantedprocessincludechildren(void* lpObj, int accessgrantedprocessindex);

bool GetAccessGrantedProcessIncludeChildren(int iAccessGrantedProcessIndex);

Default Value

FALSE

Remarks

Whether child processes are affected.

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

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only and not available at design time.

Data Type

Boolean

AccessGrantedProcessId Property (CBVaultDrive Class)

The Id of the target process.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetAccessGrantedProcessId(int iAccessGrantedProcessIndex);

Unicode (Windows)
INT GetAccessGrantedProcessId(INT iAccessGrantedProcessIndex);

int cbfsstorage_cbvaultdrive_getaccessgrantedprocessid(void* lpObj, int accessgrantedprocessindex);

int GetAccessGrantedProcessId(int iAccessGrantedProcessIndex);

Default Value

0

Remarks

The Id of the target process.

This property reflects the target process's Id (PID). Will be 0 if the target process was specified by AccessGrantedProcessProcessName, or -1 if the rule applies to all processes.

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only and not available at design time.

Data Type

Integer

AccessGrantedProcessName Property (CBVaultDrive Class)

The filename of the target process's executable.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAccessGrantedProcessName(int iAccessGrantedProcessIndex);

Unicode (Windows)
LPWSTR GetAccessGrantedProcessName(INT iAccessGrantedProcessIndex);

char* cbfsstorage_cbvaultdrive_getaccessgrantedprocessname(void* lpObj, int accessgrantedprocessindex);

QString GetAccessGrantedProcessName(int iAccessGrantedProcessIndex);

Default Value

""

Remarks

The filename of the target process's executable.

This property reflects the full filename of the target process's executable. Will be empty if the target process was specified by AccessGrantedProcessProcessId (or if the rule applies to all processes, in which case AccessGrantedProcessProcessId will be -1).

The AccessGrantedProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the AccessGrantedProcessCount property.

This property is read-only and not available at design time.

Data Type

String

Active Property (CBVaultDrive Class)

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

Syntax

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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, i.e., as 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

• C++
• C
• Qt

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

MountingPointCount Property (CBVaultDrive Class)

The number of records in the MountingPoint arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMountingPointCount();

Unicode (Windows)
INT GetMountingPointCount();

int cbfsstorage_cbvaultdrive_getmountingpointcount(void* lpObj);

int GetMountingPointCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• MountingPointAuthenticationId
• MountingPointFlags
• MountingPointName

The array indices start at 0 and end at MountingPointCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

MountingPointAuthenticationId Property (CBVaultDrive Class)

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

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetMountingPointAuthenticationId(int iMountingPointIndex);

Unicode (Windows)
LONG64 GetMountingPointAuthenticationId(INT iMountingPointIndex);

int64 cbfsstorage_cbvaultdrive_getmountingpointauthenticationid(void* lpObj, int mountingpointindex);

qint64 GetMountingPointAuthenticationId(int iMountingPointIndex);

Default Value

0

Remarks

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

If the STGMP_LOCAL flag is included in the MountingPointFlags value, this property reflects the Authentication ID of the user session in which the mounting point was added. Will be 0 if the mounting point was added in the current user session or globally.

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only and not available at design time.

Data Type

Long64

MountingPointFlags Property (CBVaultDrive Class)

The flags used to create the mounting point.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetMountingPointFlags(int iMountingPointIndex);

Unicode (Windows)
INT GetMountingPointFlags(INT iMountingPointIndex);

int cbfsstorage_cbvaultdrive_getmountingpointflags(void* lpObj, int mountingpointindex);

int GetMountingPointFlags(int iMountingPointIndex);

Default Value

0

Remarks

The flags used to create the mounting point.

This property reflects the flags used to create the mounting point. It is a combination of zero or more of the following:

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only and not available at design time.

Data Type

Integer

MountingPointName Property (CBVaultDrive Class)

The mounting point name.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetMountingPointName(int iMountingPointIndex);

Unicode (Windows)
LPWSTR GetMountingPointName(INT iMountingPointIndex);

char* cbfsstorage_cbvaultdrive_getmountingpointname(void* lpObj, int mountingpointindex);

QString GetMountingPointName(int iMountingPointIndex);

Default Value

""

Remarks

The mounting point name.

This property reflects the name of the mounting point (i.e., the value passed to the AddMountingPoint method's MountingPoint parameter).

The MountingPointIndex parameter specifies the index of the item in the array. The size of the array is controlled by the MountingPointCount property.

This property is read-only and not available at design time.

Data Type

String

OpenFilesCount Property (CBVaultDrive Class)

The number of records in the OpenFile arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenFilesCount();

Unicode (Windows)
INT GetOpenFilesCount();

int cbfsstorage_cbvaultdrive_getopenfilescount(void* lpObj);

int GetOpenFilesCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• OpenFileName
• OpenFileProcessId
• OpenFileProcessName

The array indices start at 0 and end at OpenFilesCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

OpenFileName Property (CBVaultDrive Class)

The name of the open file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOpenFileName(int iOpenFileIndex);

Unicode (Windows)
LPWSTR GetOpenFileName(INT iOpenFileIndex);

char* cbfsstorage_cbvaultdrive_getopenfilename(void* lpObj, int openfileindex);

QString GetOpenFileName(int iOpenFileIndex);

Default Value

""

Remarks

The name of the open file.

This property reflects the name of the open file.

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only and not available at design time.

Data Type

String

OpenFileProcessId Property (CBVaultDrive Class)

The Id of the process that opened the file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOpenFileProcessId(int iOpenFileIndex);

Unicode (Windows)
INT GetOpenFileProcessId(INT iOpenFileIndex);

int cbfsstorage_cbvaultdrive_getopenfileprocessid(void* lpObj, int openfileindex);

int GetOpenFileProcessId(int iOpenFileIndex);

Default Value

0

Remarks

The Id of the process that opened the file.

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

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only and not available at design time.

Data Type

Integer

OpenFileProcessName Property (CBVaultDrive Class)

The name of the process that opened the file.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOpenFileProcessName(int iOpenFileIndex);

Unicode (Windows)
LPWSTR GetOpenFileProcessName(INT iOpenFileIndex);

char* cbfsstorage_cbvaultdrive_getopenfileprocessname(void* lpObj, int openfileindex);

QString GetOpenFileProcessName(int iOpenFileIndex);

Default Value

""

Remarks

The name of the process that opened the file.

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

The OpenFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the OpenFilesCount property.

This property is read-only and not available at design time.

Data Type

String

PageSize Property (CBVaultDrive Class)

This property specifies the vault's page size.

Syntax

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Unicode (Windows)
INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);

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:

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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

When the StorageType property is set to STGT_DISK_PNP, this property is used to specify a GUID for the virtual drive, and must be set to GUID-formatted string (e.g., {676D0357-A23A-49c3-B433-65AAD72DD282}). Otherwise, this property 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.

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

• C++
• C
• Qt

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 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:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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 filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to deny; valid values are:

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

• C++
• C
• Qt

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 filename of the process's executable file for ProcessFileName (in which case ProcessId should be set to 0). If ProcessName is empty, and ProcessId is -1, the new rule will apply to all processes. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

ChildProcesses controls whether the rule also applies to children of the target process.

DesiredAccess specifies the access right to grant; valid values are:

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

• C++
• C
• Qt

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:

Linux and macOS:

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

ANSI (Cross Platform)
int CheckFilePassword(const char* lpszFileName, const char* lpszPassword);

Unicode (Windows)
INT CheckFilePassword(LPCWSTR lpszFileName, LPCWSTR lpszPassword);

int 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

• C++
• C
• Qt

ANSI (Cross Platform)
int CheckVaultPassword(const char* lpszPassword);

Unicode (Windows)
INT CheckVaultPassword(LPCWSTR lpszPassword);

int 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

ANSI (Cross Platform)
int CompactVault();

Unicode (Windows)
INT CompactVault();

int 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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 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

• C++
• C
• Qt

ANSI (Cross Platform)
int FileExists(const char* lpszFileName);

Unicode (Windows)
INT FileExists(LPCWSTR lpszFileName);

int 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

• C++
• C
• Qt

ANSI (Cross Platform)
int FileMatchesMask(const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

Unicode (Windows)
INT FileMatchesMask(LPCWSTR lpszMask, LPCWSTR lpszFileName, BOOL bCaseSensitive);

int 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

• C++
• C
• Qt

ANSI (Cross Platform)
int FileTagExists(const char* lpszFileName, int iTagId, const char* lpszTagName);

Unicode (Windows)
INT FileTagExists(LPCWSTR lpszFileName, INT iTagId, LPCWSTR lpszTagName);

int 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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 filename 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.

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:

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

ANSI (Cross Platform)
int FindNext(int64 lSearchId);

Unicode (Windows)
INT FindNext(LONG64 lSearchId);

int 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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:

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:

• Install
• Uninstall
• GetDriverStatus
• GetModuleVersion
• RegisterIcon
• UnregisterIcon
• Initialize

The Module parameter specifies which driver module to query the status of. Possible values are:

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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, i.e., as 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

• C++
• C
• Qt

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:

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

• C++
• C
• Qt

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, i.e., as 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

• C++
• C
• Qt

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, i.e., as 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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 Binary String 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

• C++
• C
• Qt

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

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFileTagAsBoolean(const char* lpszFileName, const char* lpszTagName);

Unicode (Windows)
INT GetFileTagAsBoolean(LPCWSTR lpszFileName, LPCWSTR lpszTagName);

int 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

• C++
• C
• Qt

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, i.e., as 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

• C++
• C
• Qt

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

• C++
• C
• Qt

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

• C++
• C
• Qt

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):

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

• C++
• C
• Qt

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.