CBVault Class

Properties   Methods   Events   Config Settings   Errors  

The CBVault class lets applications create a vault and manipulate its contents.

Syntax

CBVault

Remarks

The CBVault class allows applications to create a vault and interact with its contents directly. A vault can contain any number of files, directories, alternate streams, and symbolic links; as long as it has sufficient capacity to store them. For more information about using CBFS Vault's many features, please refer to the extensive General Information topics.

The CBVault class is available on all platforms supported by the CBFS Vault product.

Getting Started

Each CBVault class instance can control a single vault at once. Applications can use multiple instances of the CBVault class if their use-case requires multiple vaults.

Use the following steps to get up and running:

1. Create or open a vault by calling the OpenVault method.
2. Interact with the vault and its contents using the CBVault class's API methods.
3. When done, call the CloseVault method to close the vault.

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.

Active Property (CBVault Class)

This property reflects whether a vault has been opened.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int cbfsvault_cbvault_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class has opened a vault; it will be true once the OpenVault method has been called successfully.

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

Data Type

Boolean

AutoCompactAt Property (CBVault 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 cbfsvault_cbvault_getautocompactat(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getcallbackmode(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getcasesensitive(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_getdefaultfileaccesspassword(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getdefaultfilecompression(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_getdefaultfilecreatepassword(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getdefaultfileencryption(void* lpObj);
int cbfsvault_cbvault_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

IsCorrupted Property (CBVault Class)

This property specifies whether the vault is corrupted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetIsCorrupted();

Unicode (Windows)
BOOL GetIsCorrupted();

int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getlastwritetime(void* lpObj);

QDateTime GetLastWriteTime();

Default Value

0

Remarks

This property reflects the vault's last modification time, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

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

Data Type

Long64

Logo Property (CBVault 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* cbfsvault_cbvault_getlogo(void* lpObj);
int cbfsvault_cbvault_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

PageSize Property (CBVault 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 cbfsvault_cbvault_getpagesize(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getpathseparator(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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

ReadOnly Property (CBVault 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 cbfsvault_cbvault_getreadonly(void* lpObj);
int cbfsvault_cbvault_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

Tag Property (CBVault 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 cbfsvault_cbvault_gettag(void* lpObj);
int cbfsvault_cbvault_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

UseAccessTime Property (CBVault 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 cbfsvault_cbvault_getuseaccesstime(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getusesystemcache(void* lpObj);
int cbfsvault_cbvault_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.

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

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Boolean

VaultEncryption Property (CBVault 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 cbfsvault_cbvault_getvaultencryption(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_getvaultfile(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_getvaultpassword(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getvaultsize(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getvaultsizemax(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getvaultsizemin(void* lpObj);
int cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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

CacheFilePassword Method (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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.

CloseVault Method (CBVault Class)

This method closes the vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CloseVault();

Unicode (Windows)
INT CloseVault();

int cbfsvault_cbvault_closevault(void* lpObj);

int CloseVault();

Remarks

This method closes the currently open vault.

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 (CBVault Class)

This method compacts the vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CompactVault();

Unicode (Windows)
INT CompactVault();

int cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_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.

CopyFromVault Method (CBVault Class)

This method copies files and directories from the vault to a physical filesystem.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CopyFromVault(const char* lpszVaultPath, const char* lpszSystemPath, const char* lpszMask, int iFlags, const char* lpszPassword);

Unicode (Windows)
INT CopyFromVault(LPCWSTR lpszVaultPath, LPCWSTR lpszSystemPath, LPCWSTR lpszMask, INT iFlags, LPCWSTR lpszPassword);

int cbfsvault_cbvault_copyfromvault(void* lpObj, const char* lpszVaultPath, const char* lpszSystemPath, const char* lpszMask, int iFlags, const char* lpszPassword);

int CopyFromVault(const QString& qsVaultPath, const QString& qsSystemPath, const QString& qsMask, int iFlags, const QString& qsPassword);

Remarks

This method copies the files and directories at the specified VaultPath to a physical filesystem location, specified by SystemPath. Only the files and directories whose names match the specified Mask are copied.

The values passed for VaultPath and SystemPath must be vault-local and system-local absolute paths, respectively. The value passed for Mask may contain wildcard characters.

The Flags parameter is used to control recursion and overwrite behavior. It should be set by ORing together zero or more of the following flags:

The Password parameter specifies the password to use to access files' data, if they are encrypted.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

CopyToVault Method (CBVault Class)

This method copies files and directories from a physical filesystem to the vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int CopyToVault(const char* lpszSystemPath, const char* lpszVaultPath, const char* lpszMask, int iFlags, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

Unicode (Windows)
INT CopyToVault(LPCWSTR lpszSystemPath, LPCWSTR lpszVaultPath, LPCWSTR lpszMask, INT iFlags, INT iEncryption, LPCWSTR lpszPassword, INT iCompression, INT iCompressionLevel, INT iPagesPerBlock);

int cbfsvault_cbvault_copytovault(void* lpObj, const char* lpszSystemPath, const char* lpszVaultPath, const char* lpszMask, int iFlags, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

int CopyToVault(const QString& qsSystemPath, const QString& qsVaultPath, const QString& qsMask, int iFlags, int iEncryption, const QString& qsPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

Remarks

This method copies the files and directories from a physical filesystem location, specified by SystemPath, to the specified VaultPath. Only the files and directories whose names match the specified Mask are copied.

The values passed for SystemPath and VaultPath must be system-local and vault-local absolute paths, respectively. The value passed for Mask may contain wildcard characters.

The Flags parameter is used to control recursion and overwrite behavior. It should be set by ORing together zero or more of the following flags:

The Encryption parameter specifies Encryption behavior for files created (or overwritten) during the copy operation. 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.

The Password parameter specifies the password to use for encryption, if applicable.

The Compression parameter specifies the Compression behavior for files created (or overwritten) during the copy operation. Valid values are:

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a 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.)

CreateDirectory Method (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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.)

DeleteFile Method (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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.)

FileExists Method (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 Vault 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 (CBVault 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 cbfsvault_cbvault_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.

GetFileAttributes Method (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getfilecreationtime(void* lpObj, const char* lpszFileName);

QDateTime GetFileCreationTime(const QString& qsFileName);

Remarks

This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as 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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getfilelastaccesstime(void* lpObj, const char* lpszFileName);

QDateTime GetFileLastAccessTime(const QString& qsFileName);

Remarks

This method retrieves the creation time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as 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.

GetFileMetadataSize Method (CBVault Class)

This method retrieves the size of the metadata associated with a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFileMetadataSize(const char* lpszFileName);

Unicode (Windows)
LONG64 GetFileMetadataSize(LPCWSTR lpszFileName);

int64 cbfsvault_cbvault_getfilemetadatasize(void* lpObj, const char* lpszFileName);

qint64 GetFileMetadataSize(const QString& qsFileName);

Remarks

This method retrieves the size of the metadata associated with the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.

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

The value passed for 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 (CBVault 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 cbfsvault_cbvault_getfilemodificationtime(void* lpObj, const char* lpszFileName);

QDateTime GetFileModificationTime(const QString& qsFileName);

Remarks

This method retrieves the modification time of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName. The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as 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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getfiletagasdatetime(void* lpObj, const char* lpszFileName, const char* lpszTagName);

QDateTime GetFileTagAsDateTime(const QString& qsFileName, const QString& qsTagName);

Remarks

This method retrieves the value of a DateTime-typed file tag, identified by TagName, attached to the vault item (e.g., file, directory, or alternate stream) specified by FileName. If a DateTime-typed file tag with the specified TagName is not attached to the specified vault item, this method fails with an error.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as 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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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* cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_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 (CBVault 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 cbfsvault_cbvault_getfiletagsize(void* lpObj, const char* lpszFileName, int iTagId);

int GetFileTagSize(const QString& qsFileName, int iTagId);

Remarks

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

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

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultAttributes Method (CBVault Class)

This method retrieves the attributes of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT GetSearchResultAttributes(LONG64 lSearchId);

int cbfsvault_cbvault_getsearchresultattributes(void* lpObj, int64 lSearchId);

int GetSearchResultAttributes(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultCreationTime Method (CBVault Class)

This method retrieves the creation time of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSearchResultCreationTime(int64 lSearchId);

Unicode (Windows)
LONG64 GetSearchResultCreationTime(LONG64 lSearchId);

int64 cbfsvault_cbvault_getsearchresultcreationtime(void* lpObj, int64 lSearchId);

QDateTime GetSearchResultCreationTime(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultFullName Method (CBVault Class)

This method retrieves the fully qualified name of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSearchResultFullName(int64 lSearchId);

Unicode (Windows)
LPWSTR GetSearchResultFullName(LONG64 lSearchId);

char* cbfsvault_cbvault_getsearchresultfullname(void* lpObj, int64 lSearchId);

QString GetSearchResultFullName(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultLastAccessTime Method (CBVault Class)

This method retrieves the last access time of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSearchResultLastAccessTime(int64 lSearchId);

Unicode (Windows)
LONG64 GetSearchResultLastAccessTime(LONG64 lSearchId);

int64 cbfsvault_cbvault_getsearchresultlastaccesstime(void* lpObj, int64 lSearchId);

QDateTime GetSearchResultLastAccessTime(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

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

Note: Vault items' last access times are updated only if the UseAccessTime property is enabled.

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultLinkDestination Method (CBVault Class)

This method retrieves the destination of a symbolic link found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSearchResultLinkDestination(int64 lSearchId);

Unicode (Windows)
LPWSTR GetSearchResultLinkDestination(LONG64 lSearchId);

char* cbfsvault_cbvault_getsearchresultlinkdestination(void* lpObj, int64 lSearchId);

QString GetSearchResultLinkDestination(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultMetadataSize Method (CBVault Class)

This method retrieves the size of the metadata associated with a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSearchResultMetadataSize(int64 lSearchId);

Unicode (Windows)
LONG64 GetSearchResultMetadataSize(LONG64 lSearchId);

int64 cbfsvault_cbvault_getsearchresultmetadatasize(void* lpObj, int64 lSearchId);

qint64 GetSearchResultMetadataSize(qint64 lSearchId);

Remarks

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

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultModificationTime Method (CBVault Class)

This method retrieves the modification time of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSearchResultModificationTime(int64 lSearchId);

Unicode (Windows)
LONG64 GetSearchResultModificationTime(LONG64 lSearchId);

int64 cbfsvault_cbvault_getsearchresultmodificationtime(void* lpObj, int64 lSearchId);

QDateTime GetSearchResultModificationTime(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResultName Method (CBVault Class)

This method retrieves the name of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetSearchResultName(int64 lSearchId);

Unicode (Windows)
LPWSTR GetSearchResultName(LONG64 lSearchId);

char* cbfsvault_cbvault_getsearchresultname(void* lpObj, int64 lSearchId);

QString GetSearchResultName(qint64 lSearchId);

Remarks

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

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetSearchResults Method (CBVault Class)

This method retrieves all information about a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSearchResults(int64 lSearchId, char** lpszName, char** lpszFullName, int* iAttributes, int64* lSize, int64* lCreationTime, int64* lModificationTime, int64* lLastAccessTime, char** lpszLinkDestination, int64* lMetadataSize);

Unicode (Windows)
INT GetSearchResults(LONG64 lSearchId, LPWSTR* lpszName, LPWSTR* lpszFullName, INT*  iAttributes, LONG64*  lSize, LONG64*  lCreationTime, LONG64*  lModificationTime, LONG64*  lLastAccessTime, LPWSTR* lpszLinkDestination, LONG64*  lMetadataSize);

int cbfsvault_cbvault_getsearchresults(void* lpObj, int64 lSearchId, char** lpszName, char** lpszFullName, int* iAttributes, int64* lSize, int64* lCreationTime, int64* lModificationTime, int64* lLastAccessTime, char** lpszLinkDestination, int64* lMetadataSize);

int GetSearchResults(qint64 lSearchId, QString& qsName, QString& qsFullName, int* iAttributes, qint64* lSize, QDateTime& qdtCreationTime, QDateTime& qdtModificationTime, QDateTime& qdtLastAccessTime, QString& qsLinkDestination, qint64* lMetadataSize);

Remarks

This method retrieves all available information about a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a 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.)

GetSearchResultSize Method (CBVault Class)

This method retrieves the size of a vault item found during a search operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetSearchResultSize(int64 lSearchId);

Unicode (Windows)
LONG64 GetSearchResultSize(LONG64 lSearchId);

int64 cbfsvault_cbvault_getsearchresultsize(void* lpObj, int64 lSearchId);

qint64 GetSearchResultSize(qint64 lSearchId);

Remarks

This method retrieves the size of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.

Note: For files, the returned value reflects only the size of the file's immediate contents; it does not account for any alternate streams the file may or may not contain.

The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

IsDirectoryEmpty Method (CBVault Class)

This method checks whether a directory is empty.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int IsDirectoryEmpty(const char* lpszDirectory);

Unicode (Windows)
INT IsDirectoryEmpty(LPCWSTR lpszDirectory);

int cbfsvault_cbvault_isdirectoryempty(void* lpObj, const char* lpszDirectory);

bool IsDirectoryEmpty(const QString& qsDirectory);

Remarks

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

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

IsValidVault Method (CBVault Class)

This method checks whether a local file is a CBFS Vault vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int IsValidVault();

Unicode (Windows)
INT IsValidVault();

int cbfsvault_cbvault_isvalidvault(void* lpObj);

bool IsValidVault();

Remarks

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

If the specified file is a CBFS Vault vault, this method returns true; otherwise, it returns false.

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

Note: This method uses a simple detection mechanism; it does not perform a full consistency check or attempt any repairs, so applications may still need to call CheckAndRepair even if this method returns true. If an error occurs during the detection process, this method fails with an error.

Note: This method cannot be called when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

MoveFile Method (CBVault Class)

This method renames or moves a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int MoveFile(const char* lpszOldFileName, const char* lpszNewFileName, int bOverwrite);

Unicode (Windows)
INT MoveFile(LPCWSTR lpszOldFileName, LPCWSTR lpszNewFileName, BOOL bOverwrite);

int cbfsvault_cbvault_movefile(void* lpObj, const char* lpszOldFileName, const char* lpszNewFileName, int bOverwrite);

int MoveFile(const QString& qsOldFileName, const QString& qsNewFileName, bool bOverwrite);

Remarks

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

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

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

Note: The usual rules of deletion still apply for an item being overwritten. Notably, a nonempty directory cannot be overwritten.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

OpenFile Method (CBVault Class)

This method opens a new or existing file or alternate stream in the vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSVaultStream* OpenFile(const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, const char* lpszPassword);

Unicode (Windows)
CBFSVaultStream* OpenFile(LPCWSTR lpszFileName, INT iOpenMode, BOOL bReadEnabled, BOOL bWriteEnabled, LPCWSTR lpszPassword);

CBFSVaultStream* cbfsvault_cbvault_openfile(void* lpObj, const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, const char* lpszPassword);

CBFSVaultStream* OpenFile(const QString& qsFileName, int iOpenMode, bool bReadEnabled, bool bWriteEnabled, const QString& qsPassword);

Remarks

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

Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.

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

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

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.

Note: WriteEnabled is ignored if ReadOnly is true.

The Password parameter works as follows:

• If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
• If a new file or alternate stream is created, and the DefaultFileEncryption property is not VAULT_EM_NONE, the specified Password is used to encrypt it.

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

• ShareDenyRead and ShareDenyWrite use true.
• Encryption uses the current DefaultFileEncryption value.
• Compression and CompressionLevel use the current DefaultFileCompression and DefaultFileCompressionLevel values, respectively.
• PagesPerBlock uses 16.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenFileEx Method (CBVault Class)

This method opens a new or existing file or alternate stream in the vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSVaultStream* OpenFileEx(const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, int bShareDenyRead, int bShareDenyWrite, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

Unicode (Windows)
CBFSVaultStream* OpenFileEx(LPCWSTR lpszFileName, INT iOpenMode, BOOL bReadEnabled, BOOL bWriteEnabled, BOOL bShareDenyRead, BOOL bShareDenyWrite, INT iEncryption, LPCWSTR lpszPassword, INT iCompression, INT iCompressionLevel, INT iPagesPerBlock);

CBFSVaultStream* cbfsvault_cbvault_openfileex(void* lpObj, const char* lpszFileName, int iOpenMode, int bReadEnabled, int bWriteEnabled, int bShareDenyRead, int bShareDenyWrite, int iEncryption, const char* lpszPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

CBFSVaultStream* OpenFileEx(const QString& qsFileName, int iOpenMode, bool bReadEnabled, bool bWriteEnabled, bool bShareDenyRead, bool bShareDenyWrite, int iEncryption, const QString& qsPassword, int iCompression, int iCompressionLevel, int iPagesPerBlock);

Remarks

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

Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.

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

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

The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.

Note: WriteEnabled is ignored if ReadOnly is true.

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

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

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

The Password parameter works as follows:

• If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
• If a file or alternate stream is created, and Encryption is not VAULT_EM_NONE, the specified Password is used to encrypt it.

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

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenRootData Method (CBVault Class)

This method opens the vault's root data stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
CBFSVaultStream* OpenRootData();

Unicode (Windows)
CBFSVaultStream* OpenRootData();

CBFSVaultStream* cbfsvault_cbvault_openrootdata(void* lpObj);

CBFSVaultStream* OpenRootData();

Remarks

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

Please refer to the Using RootData topic for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

OpenVault Method (CBVault Class)

This method opens a new or existing vault.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int OpenVault(int iOpenMode, int iJournalingMode);

Unicode (Windows)
INT OpenVault(INT iOpenMode, INT iJournalingMode);

int cbfsvault_cbvault_openvault(void* lpObj, int iOpenMode, int iJournalingMode);

int OpenVault(int iOpenMode, int iJournalingMode);

Remarks

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

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

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

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

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

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

• AutoCompactAt property
• AutoCompactDelay configuration setting
• CaseSensitive property
• Logo property
• MaxNonPagedNameLength configuration setting
• PageSize property
• PartSize configuration setting
• PathSeparator property
• ReadOnly property
• UseAccessTime property
• UseSystemCache property

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

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

ResolveLink Method (CBVault Class)

This method retrieves the destination of a symbolic link.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* ResolveLink(const char* lpszLinkName, int bNormalize);

Unicode (Windows)
LPWSTR ResolveLink(LPCWSTR lpszLinkName, BOOL bNormalize);

char* cbfsvault_cbvault_resolvelink(void* lpObj, const char* lpszLinkName, int bNormalize);

QString ResolveLink(const QString& qsLinkName, bool bNormalize);

Remarks

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

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

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

Note: This method can be called only when Active is true.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

SetFileAttributes Method (CBVault Class)

This method sets the attributes of a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileAttributes(const char* lpszFileName, int iAttributes);

Unicode (Windows)
INT SetFileAttributes(LPCWSTR lpszFileName, INT iAttributes);

int cbfsvault_cbvault_setfileattributes(void* lpObj, const char* lpszFileName, int iAttributes);

int SetFileAttributes(const QString& qsFileName, int iAttributes);

Remarks

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

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileCompression Method (CBVault Class)

This method compresses or decompresses a file or alternate stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileCompression(const char* lpszFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const char* lpszPassword);

Unicode (Windows)
INT SetFileCompression(LPCWSTR lpszFileName, INT iCompression, INT iCompressionLevel, INT iPagesPerBlock, LPCWSTR lpszPassword);

int cbfsvault_cbvault_setfilecompression(void* lpObj, const char* lpszFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const char* lpszPassword);

int SetFileCompression(const QString& qsFileName, int iCompression, int iCompressionLevel, int iPagesPerBlock, const QString& qsPassword);

Remarks

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

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

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

Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.

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

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileCreationTime Method (CBVault Class)

This method sets the creation time of a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileCreationTime(const char* lpszFileName, int64 lCreationTime);

Unicode (Windows)
INT SetFileCreationTime(LPCWSTR lpszFileName, LONG64 lCreationTime);

int cbfsvault_cbvault_setfilecreationtime(void* lpObj, const char* lpszFileName, int64 lCreationTime);

int SetFileCreationTime(const QString& qsFileName, QDateTime qdtCreationTime);

Remarks

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

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

The CreationTime parameter specifies the new creation time for the vault item, which must be specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileEncryption Method (CBVault Class)

This method encrypts, decrypts, or changes the encryption password of a file or alternate stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileEncryption(const char* lpszFileName, int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword);

Unicode (Windows)
INT SetFileEncryption(LPCWSTR lpszFileName, INT iEncryption, LPCWSTR lpszOldPassword, LPCWSTR lpszNewPassword);

int cbfsvault_cbvault_setfileencryption(void* lpObj, const char* lpszFileName, int iEncryption, const char* lpszOldPassword, const char* lpszNewPassword);

int SetFileEncryption(const QString& qsFileName, int iEncryption, const QString& qsOldPassword, const QString& qsNewPassword);

Remarks

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

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

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

Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileLastAccessTime Method (CBVault Class)

This method sets the last access time of a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileLastAccessTime(const char* lpszFileName, int64 lLastAccessTime);

Unicode (Windows)
INT SetFileLastAccessTime(LPCWSTR lpszFileName, LONG64 lLastAccessTime);

int cbfsvault_cbvault_setfilelastaccesstime(void* lpObj, const char* lpszFileName, int64 lLastAccessTime);

int SetFileLastAccessTime(const QString& qsFileName, QDateTime qdtLastAccessTime);

Remarks

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

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

The LastAccessTime parameter specifies the new last access time for the vault item, which must be specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileModificationTime Method (CBVault Class)

This method sets the modification time of a vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileModificationTime(const char* lpszFileName, int64 lModificationTime);

Unicode (Windows)
INT SetFileModificationTime(LPCWSTR lpszFileName, LONG64 lModificationTime);

int cbfsvault_cbvault_setfilemodificationtime(void* lpObj, const char* lpszFileName, int64 lModificationTime);

int SetFileModificationTime(const QString& qsFileName, QDateTime qdtModificationTime);

Remarks

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

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

The ModificationTime parameter specifies the new modification time for the vault item, which must be specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC(on all supported platforms!), i.e., as FILETIME.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileSize Method (CBVault Class)

This method sets the size of a file or alternate stream.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileSize(const char* lpszFileName, int64 lSize, const char* lpszPassword);

Unicode (Windows)
INT SetFileSize(LPCWSTR lpszFileName, LONG64 lSize, LPCWSTR lpszPassword);

int cbfsvault_cbvault_setfilesize(void* lpObj, const char* lpszFileName, int64 lSize, const char* lpszPassword);

int SetFileSize(const QString& qsFileName, qint64 lSize, const QString& qsPassword);

Remarks

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

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

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

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileTag Method (CBVault Class)

This method attaches a raw file tag with binary data to the specified vault item.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int SetFileTag(const char* lpszFileName, int iTagId, const char* lpData, int lenData);

Unicode (Windows)
INT SetFileTag(LPCWSTR lpszFileName, INT iTagId, LPCSTR lpData, INT lenData);

int cbfsvault_cbvault_setfiletag(void* lpObj, const char* lpszFileName, int iTagId, const char* lpData, int lenData);

int SetFileTag(const QString& qsFileName, int iTagId, QByteArray qbaData);

Remarks

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

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

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

Please refer to the File Tags topic for more information.

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileTagAsAnsiString Method (CBVault Class)

This method attaches an AnsiString-typed file tag to the specified vault item.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT SetFileTagAsAnsiString(LPCWSTR lpszFileName, LPCWSTR lpszTagName, LPCWSTR lpszValue);

int cbfsvault_cbvault_setfiletagasansistring(void* lpObj, const char* lpszFileName, const char* lpszTagName, const char* lpszValue);

int SetFileTagAsAnsiString(const QString& qsFileName, const QString& qsTagName, const QString& qsValue);

Remarks

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

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

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

Please refer to the File Tags topic for more information.

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

Note: This method can be called only when Active is true, and it cannot be called within events.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

SetFileTagAsBoolean Method (CBVault Class)

This method attaches a Boolean-typed file tag to the specified vault item.

Syntax

• C++
• C
• Qt

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

Unicode (Windows)
INT SetFileTagAsBoolean(LPCWSTR lpszFileName, LPCWSTR lpszTagName, BOOL bValue);