CBVault Module
Properties Methods Events Config Settings Errors
The CBVault module lets applications create a vault and manipulate its contents.
Syntax
CBFSVault.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:
- Create or open a vault by calling the OpenVault method.
- Interact with the vault and its contents using the CBVault class's API methods.
- When done, call the CloseVault method to close the vault.
Property List
The following is the full list of the properties of the module with short descriptions. Click on the links for further details.
Active | This property reflects whether a vault has been opened. |
AutoCompactAt | This property specifies the free space percentage threshold a vault must reach to be eligible for automatic compaction. |
CallbackMode | This property specifies whether the module should operate in callback mode. |
CaseSensitive | This property specifies whether the module should open a vault in case-sensitive mode. |
DefaultFileAccessPassword | This property specifies the default encryption password to use when opening files and alternate streams. |
DefaultFileCompression | This property specifies the default compression mode to use when creating files and alternate streams. |
DefaultFileCreatePassword | This property specifies the default encryption password to use when creating new files and alternate streams. |
DefaultFileEncryption | This property specifies the default encryption mode to use when creating files and alternate streams. |
IsCorrupted | This property specifies whether the vault is corrupted. |
LastWriteTime | This property specifies the last modification time of the vault. |
Logo | This property specifies an application-defined text-based logo stored in the second page of a vault. |
PageSize | This property specifies the vault's page size. |
PathSeparator | This property specifies the path separator character to use when returning vault paths. |
PossibleFreeSpace | This property specifies the maximum amount of free space the vault could possibly have available. |
PossibleSize | This property specifies the maximum size the vault could possibly be. |
ReadOnly | This property specifies whether the module should open a vault in read-only mode. |
Tag | This property stores application-defined data specific to a particular instance of the module. |
UseAccessTime | This property specifies whether the module should keep track of last access times for vault items. |
UseSystemCache | This property specifies whether the operating system's cache is used. |
VaultEncryption | This property specifies the whole-vault encryption mode. |
VaultFile | This property specifies the vault to create or open. |
VaultFreeSpace | This property reflects the actual amount of free space the vault has available. |
VaultPassword | This property specifies the whole-vault encryption password. |
VaultSize | This property specifies the actual size of the vault. |
VaultSizeMax | This property specifies the maximum size a vault can be. |
VaultSizeMin | This property specifies the minimum size a vault can be. |
VaultState | This property specifies information about the state of the vault. |
Method List
The following is the full list of the methods of the module with short descriptions. Click on the links for further details.
CacheFilePassword | This method caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password. |
CheckAndRepair | This method checks a vault's consistency and repairs it as necessary. |
CheckFilePassword | This method verifies whether a particular file password is correct. |
CheckVaultPassword | This method verifies whether a particular vault password is correct. |
CloseVault | This method closes the vault. |
CompactVault | This method compacts the vault. |
Config | Sets or retrieves a configuration setting. |
CopyFromVault | This method copies files and directories from the vault to a physical filesystem. |
CopyToVault | This method copies files and directories from a physical filesystem to the vault. |
CreateDirectory | This method creates a new directory in the vault. |
CreateLink | This method creates a symbolic link to another file in the vault. |
DeleteFile | This method deletes a vault item. |
DeleteFileTag | This method deletes a file tag. |
FileExists | This method checks whether a vault item exists. |
FileMatchesMask | This method checks whether a particular file or directory name matches the specified mask. |
FileTagExists | This method checks whether a file tag exists. |
FileTimeToNanoseconds | This method returns the subsecond part of the time expressed in nanoseconds. |
FileTimeToUnixTime | This method converts FileTime to Unix time format. |
FindClose | This method closes a search operation and releases any associated resources. |
FindFirst | This method searches for the first vault item that matches the specified name and attributes. |
FindFirstByQuery | This method searches for the first file or directory whose file tags match the specified query. |
FindNext | This method searches for the next vault item that matches an ongoing search operation. |
GetFileAttributes | This method retrieves the attributes of a vault item. |
GetFileCompression | This method retrieves the compression mode of a file or alternate stream. |
GetFileCreationTime | This method retrieves the creation time of a vault item. |
GetFileEncryption | This method retrieves the encryption mode of a file or alternate stream. |
GetFileLastAccessTime | This method retrieves the last access time of a vault item. |
GetFileMetadataSize | This method retrieves the size of the metadata associated with a vault item. |
GetFileModificationTime | This method retrieves the modification time of a vault item. |
GetFileSize | This method retrieves the size of a file or alternate stream. |
GetFileTag | This method retrieves the binary data held by a raw file tag attached to the specified vault item. |
GetFileTagAsAnsiString | This method retrieves the value of an AnsiString-typed file tag attached to the specified vault item. |
GetFileTagAsBoolean | This method retrieves the value of a Boolean-typed file tag attached to the specified vault item. |
GetFileTagAsDateTime | This method retrieves the value of a DateTime-typed file tag attached to the specified vault item. |
GetFileTagAsNumber | This method retrieves the value of a Number-typed file tag attached to the specified vault item. |
GetFileTagAsString | This method retrieves the value of a String-typed file tag attached to the specified vault item. |
GetFileTagDataType | This method retrieves the data type of a typed file tag attached to a specific vault item. |
GetFileTagSize | This method retrieves the size of a raw file tag attached to the specified vault item. |
GetSearchResultAttributes | This method retrieves the attributes of a vault item found during a search operation. |
GetSearchResultCreationTime | This method retrieves the creation time of a vault item found during a search operation. |
GetSearchResultFullName | This method retrieves the fully qualified name of a vault item found during a search operation. |
GetSearchResultLastAccessTime | This method retrieves the last access time of a vault item found during a search operation. |
GetSearchResultLinkDestination | This method retrieves the destination of a symbolic link found during a search operation. |
GetSearchResultMetadataSize | This method retrieves the size of the metadata associated with a vault item found during a search operation. |
GetSearchResultModificationTime | This method retrieves the modification time of a vault item found during a search operation. |
GetSearchResultName | This method retrieves the name of a vault item found during a search operation. |
GetSearchResults | This method retrieves all information about a vault item found during a search operation. |
GetSearchResultSize | This method retrieves the size of a vault item found during a search operation. |
IsDirectoryEmpty | This method checks whether a directory is empty. |
IsValidVault | This method checks whether a local file is a CBFS Vault vault. |
MoveFile | This method renames or moves a vault item. |
OpenFile | This method opens a new or existing file or alternate stream in the vault. |
OpenFileEx | This method opens a new or existing file or alternate stream in the vault. |
OpenRootData | This method opens the vault's root data stream. |
OpenVault | This method opens a new or existing vault. |
ResolveLink | This method retrieves the destination of a symbolic link. |
SetFileAttributes | This method sets the attributes of a vault item. |
SetFileCompression | This method compresses or decompresses a file or alternate stream. |
SetFileCreationTime | This method sets the creation time of a vault item. |
SetFileEncryption | This method encrypts, decrypts, or changes the encryption password of a file or alternate stream. |
SetFileLastAccessTime | This method sets the last access time of a vault item. |
SetFileModificationTime | This method sets the modification time of a vault item. |
SetFileSize | This method sets the size of a file or alternate stream. |
SetFileTag | This method attaches a raw file tag with binary data to the specified vault item. |
SetFileTagAsAnsiString | This method attaches an AnsiString-typed file tag to the specified vault item. |
SetFileTagAsBoolean | This method attaches a Boolean-typed file tag to the specified vault item. |
SetFileTagAsDateTime | This method attaches a DateTime-typed file tag to the specified vault item. |
SetFileTagAsNumber | This method attaches a Number-typed file tag to the specified vault item. |
SetFileTagAsString | This method attaches a String-typed file tag to the specified vault item. |
UnixTimeToFileTime | This method converts the date/time in Unix format to the Windows FileTime format. |
UpdateVaultEncryption | This method encrypts, decrypts, or changes the encryption password of the vault. |
Event List
The following is the full list of the events fired by the module with short descriptions. Click on the links for further details.
DataCompress | This event fires to compress a block of data using a custom compression algorithm. |
DataDecompress | This event fires to decompress a block of data using a custom compression algorithm. |
DataDecrypt | This event fires to decrypt a block of data using a custom encryption implementation. |
DataEncrypt | This event fires to encrypt a block of data using a custom encryption implementation. |
Error | This event fires if an unhandled error occurs during an event. |
FileAfterCopy | This event fires after the file has been copied during file export/import operations. |
FileBeforeCopy | This event fires before the file is copied during file export/import operations. |
FilePasswordNeeded | This event fires if a password is needed to open an encrypted file. |
HashCalculate | This event fires to calculate a password hash using a custom hashing implementation. |
KeyDerive | This event fires to derive an encryption key using a custom key derivation implementation. |
Progress | This event fires to indicate the progress of long-running vault operations. |
VaultClose | This event fires to close a callback mode vault. |
VaultDelete | This event fires to delete a callback mode vault. |
VaultFlush | This event fires to flush a callback mode vault's data out to storage. |
VaultGetParentSize | This event fires to determine how much free space is available for growing a callback mode vault. |
VaultGetSize | This event fires to determine the size of a callback mode vault. |
VaultOpen | This event fires to open a new or existing callback mode vault. |
VaultRead | This event fires to read data from a callback mode vault. |
VaultSetSize | This event fires to resize a callback mode vault. |
VaultWrite | This event fires to write data to a callback mode vault. |
Config Settings
The following is a list of config settings for the module with short descriptions. Click on the links for further details.
AllowMoveStreamsBetweenFiles | Whether alternate streams may be moved from one file to another. |
AutoCompactDelay | How long a vault must remain idle before starting automatic compaction. |
DefaultFileCompressionLevel | The default compression level to use when creating files and alternate streams. |
MaxNonPagedNameLength | The maximum number of name characters to store directly within a vault item. |
PageCacheSize | The size of the in-memory vault page cache. |
PartSize | The part size used by a multipart vault. |
Active Property (CBVault Module)
This property reflects whether a vault has been opened.
Syntax
public var active: Bool { get {...} }
@property (nonatomic,readonly,assign,getter=active) BOOL active; - (BOOL)active;
Default Value
False
Remarks
This property reflects whether the class has opened a vault; it will be once the OpenVault method has been called successfully.
This property is read-only.
AutoCompactAt Property (CBVault Module)
This property specifies the free space percentage threshold a vault must reach to be eligible for automatic compaction.
Syntax
public var autoCompactAt: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=autoCompactAt,setter=setAutoCompactAt:) int autoCompactAt; - (int)autoCompactAt; - (void)setAutoCompactAt :(int)newAutoCompactAt;
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.
CallbackMode Property (CBVault Module)
This property specifies whether the module should operate in callback mode.
Syntax
public var callbackMode: Bool { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=callbackMode,setter=setCallbackMode:) BOOL callbackMode; - (BOOL)callbackMode; - (void)setCallbackMode :(BOOL)newCallbackMode;
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 , and it cannot be changed within events.
CaseSensitive Property (CBVault Module)
This property specifies whether the module should open a vault in case-sensitive mode.
Syntax
public var caseSensitive: Bool { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=caseSensitive,setter=setCaseSensitive:) BOOL caseSensitive; - (BOOL)caseSensitive; - (void)setCaseSensitive :(BOOL)newCaseSensitive;
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 , and it cannot be changed within events.
DefaultFileAccessPassword Property (CBVault Module)
This property specifies the default encryption password to use when opening files and alternate streams.
Syntax
public var defaultFileAccessPassword: String { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=defaultFileAccessPassword,setter=setDefaultFileAccessPassword:) NSString* defaultFileAccessPassword; - (NSString*)defaultFileAccessPassword; - (void)setDefaultFileAccessPassword :(NSString*)newDefaultFileAccessPassword;
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.
DefaultFileCompression Property (CBVault Module)
This property specifies the default compression mode to use when creating files and alternate streams.
Syntax
public var defaultFileCompression: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=defaultFileCompression,setter=setDefaultFileCompression:) int defaultFileCompression; - (int)defaultFileCompression; - (void)setDefaultFileCompression :(int)newDefaultFileCompression;
Default Value
0
Remarks
This property specifies the default compression mode that the class should use when creating files and alternate streams. Valid values are as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
Applications can also specify a default compression level using the DefaultFileCompressionLevel configuration setting, if desired.
DefaultFileCreatePassword Property (CBVault Module)
This property specifies the default encryption password to use when creating new files and alternate streams.
Syntax
public var defaultFileCreatePassword: String { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=defaultFileCreatePassword,setter=setDefaultFileCreatePassword:) NSString* defaultFileCreatePassword; - (NSString*)defaultFileCreatePassword; - (void)setDefaultFileCreatePassword :(NSString*)newDefaultFileCreatePassword;
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.
DefaultFileEncryption Property (CBVault Module)
This property specifies the default encryption mode to use when creating files and alternate streams.
Syntax
public var defaultFileEncryption: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=defaultFileEncryption,setter=setDefaultFileEncryption:) int defaultFileEncryption; - (int)defaultFileEncryption; - (void)setDefaultFileEncryption :(int)newDefaultFileEncryption;
Default Value
0
Remarks
This property specifies the default encryption mode that the class should use when creating files and alternate streams. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
Applications that set this property to a value other than VAULT_EM_NONE (the default) should also specify a default encryption password using the DefaultFileCreatePassword property.
IsCorrupted Property (CBVault Module)
This property specifies whether the vault is corrupted.
Syntax
public var isCorrupted: Bool { get {...} }
@property (nonatomic,readonly,assign,getter=isCorrupted) BOOL isCorrupted; - (BOOL)isCorrupted;
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.
LastWriteTime Property (CBVault Module)
This property specifies the last modification time of the vault.
Syntax
public var lastWriteTime: Date { get {...} }
@property (nonatomic,readonly,assign,getter=lastWriteTime) NSDate* lastWriteTime; - (NSDate*)lastWriteTime;
Default Value
0
Remarks
This property reflects the vault's last modification time, specified .
This property is read-only.
Logo Property (CBVault Module)
This property specifies an application-defined text-based logo stored in the second page of a vault.
Syntax
public var logo: String { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=logo,setter=setLogo:) NSString* logo; - (NSString*)logo; - (void)setLogo :(NSString*)newLogo;
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.
PageSize Property (CBVault Module)
This property specifies the vault's page size.
Syntax
public var pageSize: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=pageSize,setter=setPageSize:) int pageSize; - (int)pageSize; - (void)setPageSize :(int)newPageSize;
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 , and it cannot be changed within events.
PathSeparator Property (CBVault Module)
This property specifies the path separator character to use when returning vault paths.
Syntax
public var pathSeparator: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=pathSeparator,setter=setPathSeparator:) int pathSeparator; - (int)pathSeparator; - (void)setPathSeparator :(int)newPathSeparator;
Default Value
92
Remarks
This property specifies the path separator character that the class APIs should use when returning a vault path. Valid values are as follows:
VAULT_PSC_BACKSLASH | 92 | Backslash ('\').
This character is the Windows path separator. |
VAULT_PSC_SLASH | 47 | Forward slash ('/').
This character is the Unix-style path separator. |
Note: This property is just a convenience; applications are free to use either of the above characters as path separators when passing path strings to the class's APIs.
Note: This property cannot be changed when Active is , and it cannot be changed within events.
PossibleFreeSpace Property (CBVault Module)
This property specifies the maximum amount of free space the vault could possibly have available.
Syntax
public var possibleFreeSpace: Int64 { get {...} }
@property (nonatomic,readonly,assign,getter=possibleFreeSpace) long long possibleFreeSpace; - (long long)possibleFreeSpace;
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.
PossibleSize Property (CBVault Module)
This property specifies the maximum size the vault could possibly be.
Syntax
public var possibleSize: Int64 { get {...} }
@property (nonatomic,readonly,assign,getter=possibleSize) long long possibleSize; - (long long)possibleSize;
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.
ReadOnly Property (CBVault Module)
This property specifies whether the module should open a vault in read-only mode.
Syntax
public var readOnly: Bool { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=readOnly,setter=setReadOnly:) BOOL readOnly; - (BOOL)readOnly; - (void)setReadOnly :(BOOL)newReadOnly;
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 , and it cannot be changed within events.
Tag Property (CBVault Module)
This property stores application-defined data specific to a particular instance of the module.
Syntax
public var tag: Int64 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=tag,setter=setTag:) long long tag; - (long long)tag; - (void)setTag :(long long)newTag;
Default Value
0
Remarks
This property can be used to store data specific to a particular instance of the class.
UseAccessTime Property (CBVault Module)
This property specifies whether the module should keep track of last access times for vault items.
Syntax
public var useAccessTime: Bool { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=useAccessTime,setter=setUseAccessTime:) BOOL useAccessTime; - (BOOL)useAccessTime; - (void)setUseAccessTime :(BOOL)newUseAccessTime;
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 , and it cannot be changed within events.
UseSystemCache Property (CBVault Module)
This property specifies whether the operating system's cache is used.
Syntax
public var useSystemCache: Bool { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=useSystemCache,setter=setUseSystemCache:) BOOL useSystemCache; - (BOOL)useSystemCache; - (void)setUseSystemCache :(BOOL)newUseSystemCache;
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 , and it cannot be changed within events.
VaultEncryption Property (CBVault Module)
This property specifies the whole-vault encryption mode.
Syntax
public var vaultEncryption: Int32 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultEncryption,setter=setVaultEncryption:) int vaultEncryption; - (int)vaultEncryption; - (void)setVaultEncryption :(int)newVaultEncryption;
Default Value
0
Remarks
This property controls the whole-vault encryption mode used when creating new vaults and reflects the whole-vault encryption mode of the currently open vault. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
To create a new vault with whole-vault encryption enabled, the VaultPassword property must be set as well.
When an existing vault is opened, the class updates VaultEncryption automatically based on the detected whole-vault encryption mode. If the vault is encrypted, the class will attempt to access it using the password specified by VaultPassword. If VaultPassword is incorrect, the attempt will fail and the vault will not be opened.
The VaultEncryption and VaultPassword properties cannot be used to change an open vault's whole-vault encryption mode or password; use the UpdateVaultEncryption method.
Please refer to the Encryption topic for more information.
Note: This property cannot be changed when Active is , and it cannot be changed within events.
VaultFile Property (CBVault Module)
This property specifies the vault to create or open.
Syntax
public var vaultFile: String { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultFile,setter=setVaultFile:) NSString* vaultFile; - (NSString*)vaultFile; - (void)setVaultFile :(NSString*)newVaultFile;
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 , and it cannot be changed within events.
VaultFreeSpace Property (CBVault Module)
This property reflects the actual amount of free space the vault has available.
Syntax
public var vaultFreeSpace: Int64 { get {...} }
@property (nonatomic,readonly,assign,getter=vaultFreeSpace) long long vaultFreeSpace; - (long long)vaultFreeSpace;
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.
VaultPassword Property (CBVault Module)
This property specifies the whole-vault encryption password.
Syntax
public var vaultPassword: String { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultPassword,setter=setVaultPassword:) NSString* vaultPassword; - (NSString*)vaultPassword; - (void)setVaultPassword :(NSString*)newVaultPassword;
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 , and it cannot be changed within events.
VaultSize Property (CBVault Module)
This property specifies the actual size of the vault.
Syntax
public var vaultSize: Int64 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultSize,setter=setVaultSize:) long long vaultSize; - (long long)vaultSize; - (void)setVaultSize :(long long)newVaultSize;
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 , and it cannot be changed within events.
VaultSizeMax Property (CBVault Module)
This property specifies the maximum size a vault can be.
Syntax
public var vaultSizeMax: Int64 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultSizeMax,setter=setVaultSizeMax:) long long vaultSizeMax; - (long long)vaultSizeMax; - (void)setVaultSizeMax :(long long)newVaultSizeMax;
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.
VaultSizeMin Property (CBVault Module)
This property specifies the minimum size a vault can be.
Syntax
public var vaultSizeMin: Int64 { get {...} set {...} }
@property (nonatomic,readwrite,assign,getter=vaultSizeMin,setter=setVaultSizeMin:) long long vaultSizeMin; - (long long)vaultSizeMin; - (void)setVaultSizeMin :(long long)newVaultSizeMin;
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.
VaultState Property (CBVault Module)
This property specifies information about the state of the vault.
Syntax
public var vaultState: Int32 { get {...} }
@property (nonatomic,readonly,assign,getter=vaultState) int vaultState; - (int)vaultState;
Default Value
0
Remarks
This property reflects the current state of the vault; its value consists of one or more of the following flags, ORed together:
VAULT_ST_FIXED_SIZE | 0x00000001 | The vault is a fixed size. |
VAULT_ST_READ_ONLY | 0x00000002 | The vault was opened in read-only mode.
Please refer to the ReadOnly property for more information. |
VAULT_ST_CORRUPTED | 0x00000004 | The vault is corrupted.
Applications can use the CheckAndRepair method to try to repair vault corruption. Please refer to the Vault Corruption topic for more information. |
VAULT_ST_TRANSACTIONS_USED | 0x00000008 | The vault was opened in journaling mode.
Please refer to the UseJournaling property for more information. |
VAULT_ST_ACCESS_TIME_USED | 0x00000010 | Last access times are being tracked.
Please refer to the UseAccessTime property for more information. |
VAULT_ST_ENCRYPTED | 0x00000020 | The vault is encrypted with whole-vault encryption.
Please refer to the Encryption topic for more information. |
VAULT_ST_VALID_PASSWORD_SET | 0x00000040 | The correct whole-vault encryption password has been provided.
Please refer to the Encryption topic for more information. |
VAULT_ST_PHYSICAL_VOLUME | 0x00000080 | The vault is backed by a storage volume or partition formatted with the CBFS Vault filesystem.
This flag is not used. |
VAULT_ST_PARTED | 0x00000100 | The vault's contents are split across multiple files on disk.
Please refer to the Multipart Vaults topic for more information. |
This property is read-only.
CacheFilePassword Method (CBVault Module)
This method caches an encryption password to use the next time a file or alternate stream is accessed or removes the cached password.
Syntax
public func cacheFilePassword(fileName: String, password: String, ttlInCache: Int32, removeFromCache: Bool) throws -> Void
- (void)cacheFilePassword:(NSString*)fileName :(NSString*)password :(int)TTLInCache :(BOOL)removeFromCache;
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 .
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 . 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 .
CheckAndRepair Method (CBVault Module)
This method checks a vault's consistency and repairs it as necessary.
Syntax
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 , or if a vault operation fails with a "Vault Corrupted" error). Be sure to make a vault backup before calling this method, because its repair efforts may cause data loss in cases of severe corruption. Please refer to the Vault Corruption topic for more information.
The Flags parameter is used to specify additional options, and it should be set by ORing together zero or more of the following flags:
VAULT_CR_CHECK_ONLY | 0x00000001 | Check only, do not attempt any repairs. |
VAULT_CR_CHECK_ALL_PAGES | 0x00000002 | Check all vault pages, including empty ones.
When this flag is not present, only the vault pages that are marked as occupied are checked. |
Note: This method cannot be called when Active is , and it cannot be called within events.
CheckFilePassword Method (CBVault Module)
This method verifies whether a particular file password is correct.
Syntax
- (BOOL)checkFilePassword:(NSString*)fileName :(NSString*)password;
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 ; otherwise, it returns .
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 .
CheckVaultPassword Method (CBVault Module)
This method verifies whether a particular vault password is correct.
Syntax
- (BOOL)checkVaultPassword:(NSString*)password;
Remarks
This method verifies whether the specified Password matches the one used to encrypt the vault. If the password is correct, this method returns ; otherwise, it returns .
Please refer to the Encryption topic for more information.
Note: This method can be called only when Active is .
CloseVault Method (CBVault Module)
This method closes the vault.
Syntax
public func closeVault() throws -> Void
- (void)closeVault;
Remarks
This method closes the currently open vault.
Note: This method can be called only when Active is .
CompactVault Method (CBVault Module)
This method compacts the vault.
Syntax
public func compactVault() throws -> Bool
- (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 ; otherwise, it returns .
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 , and it cannot be called within events.
Config Method (CBVault Module)
Sets or retrieves a configuration setting.
Syntax
- (NSString*)config:(NSString*)configurationString;
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.
CopyFromVault Method (CBVault Module)
This method copies files and directories from the vault to a physical filesystem.
Syntax
public func copyFromVault(vaultPath: String, systemPath: String, mask: String, flags: Int32, password: String) throws -> Void
- (void)copyFromVault:(NSString*)vaultPath :(NSString*)systemPath :(NSString*)mask :(int)flags :(NSString*)password;
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. When copying files recursively, files that match the mask are picked from any subdirectories (i.e., the mask is not applied to directory names when files are collected for copying).
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:
VAULT_CFF_OVERWRITE_NONE | 0x00000000 | Never overwrite destination files. |
VAULT_CFF_OVERWRITE_IF_NEWER | 0x00000001 | Overwrite a destination file only if the source file is newer. |
VAULT_CFF_OVERWRITE_ALL | 0x00000002 | Always overwrite destination files. |
VAULT_CFF_INCLUDE_SUBDIRS_WITH_CONTENTS | 0x00010000 | Include all subdirectories in source directory, and their contents, recursively. |
VAULT_CFF_INCLUDE_SUBDIRS_NO_CONTENTS | 0x00020000 | Include all subdirectories in the source directory, without their contents. |
VAULT_CFF_COPY_DIRS_STRUCTURE | 0x00040000 | Include all subdirectories in the source directory, without their contents.
Only the directory structure is copied, recursively. |
VAULT_CFF_COPY_STRUCTURE | 0x00080000 | Include all subdirectories in source directory, and their contents, recursively, but without file content.
For files, empty placeholders are created without any original file data. |
VAULT_CFF_FIRE_COPY_EVENTS | 0x40000000 | Fire events related to file copying.
When the flag is set, the class fires the FileBeforeCopy and FileAfterCopy events. |
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 , and it cannot be called within events.
CopyToVault Method (CBVault Module)
This method copies files and directories from a physical filesystem to the vault.
Syntax
public func copyToVault(systemPath: String, vaultPath: String, mask: String, flags: Int32, encryption: Int32, password: String, compression: Int32, compressionLevel: Int32, pagesPerBlock: Int32) throws -> Void
- (void)copyToVault:(NSString*)systemPath :(NSString*)vaultPath :(NSString*)mask :(int)flags :(int)encryption :(NSString*)password :(int)compression :(int)compressionLevel :(int)pagesPerBlock;
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. When copying files recursively, files that match the mask are picked from any subdirectories (i.e., the mask is not applied to directory names when files are collected for copying).
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:
VAULT_CFF_OVERWRITE_NONE | 0x00000000 | Never overwrite destination files. |
VAULT_CFF_OVERWRITE_IF_NEWER | 0x00000001 | Overwrite a destination file only if the source file is newer. |
VAULT_CFF_OVERWRITE_ALL | 0x00000002 | Always overwrite destination files. |
VAULT_CFF_INCLUDE_SUBDIRS_WITH_CONTENTS | 0x00010000 | Include all subdirectories in source directory, and their contents, recursively. |
VAULT_CFF_INCLUDE_SUBDIRS_NO_CONTENTS | 0x00020000 | Include all subdirectories in the source directory, without their contents. |
VAULT_CFF_COPY_DIRS_STRUCTURE | 0x00040000 | Include all subdirectories in the source directory, without their contents.
Only the directory structure is copied, recursively. |
VAULT_CFF_COPY_STRUCTURE | 0x00080000 | Include all subdirectories in source directory, and their contents, recursively, but without file content.
For files, empty placeholders are created without any original file data. |
VAULT_CFF_FIRE_COPY_EVENTS | 0x40000000 | Fire events related to file copying.
When the flag is set, the class fires the FileBeforeCopy and FileAfterCopy events. |
The Encryption parameter specifies Encryption behavior for files created (or overwritten) during the copy operation. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
The Password parameter 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:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
The CompressionLevel parameter specifies the compression level to use, if applicable.
The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128), or 0, which is interpreted as "default" (currently 16 for both zlib and run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.
Note: This method can be called only when Active is , and it cannot be called within events.
CreateDirectory Method (CBVault Module)
This method creates a new directory in the vault.
Syntax
- (void)createDirectory:(NSString*)directory :(BOOL)createParents;
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 , and one or more parent directories are missing, this method .
Note: This method can be called only when Active is , and it cannot be called within events.
CreateLink Method (CBVault Module)
This method creates a symbolic link to another file in the vault.
Syntax
- (void)createLink:(NSString*)linkName :(NSString*)destinationName;
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 , and it cannot be called within events.
DeleteFile Method (CBVault Module)
This method deletes a vault item.
Syntax
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 . 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 , and it cannot be called within events.
DeleteFileTag Method (CBVault Module)
This method deletes a file tag.
Syntax
- (void)deleteFileTag:(NSString*)fileName :(int)tagId :(NSString*)tagName;
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 .
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is , and it cannot be called within events.
FileExists Method (CBVault Module)
This method checks whether a vault item exists.
Syntax
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 ; otherwise, it returns .
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is .
FileMatchesMask Method (CBVault Module)
This method checks whether a particular file or directory name matches the specified mask.
Syntax
- (BOOL)fileMatchesMask:(NSString*)mask :(NSString*)fileName :(BOOL)caseSensitive;
Remarks
This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns . 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."
FileTagExists Method (CBVault Module)
This method checks whether a file tag exists.
Syntax
- (BOOL)fileTagExists:(NSString*)fileName :(int)tagId :(NSString*)tagName;
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 ; otherwise, it returns .
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 .
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is .
FileTimeToNanoseconds Method (CBVault Module)
This method returns the subsecond part of the time expressed in nanoseconds.
Syntax
- (int)fileTimeToNanoseconds:(NSDate*)fileTime;
Remarks
Use this method to obtain the subsecond part of the FileTime value, expressed in nanoseconds.
FileTimeToUnixTime Method (CBVault Module)
This method converts FileTime to Unix time format.
Syntax
- (long long)fileTimeToUnixTime:(NSDate*)fileTime;
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.
FindClose Method (CBVault Module)
This method closes a search operation and releases any associated resources.
Syntax
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 .
FindFirst Method (CBVault Module)
This method searches for the first vault item that matches the specified name and attributes.
Syntax
- (long long)findFirst:(NSString*)fileMask :(int)attributes :(int)flags;
Remarks
This method initiates a search operation based on the specified FileMask, Attributes, and Flags. If there are any matching vault items (files, directories, symbolic links, or alternate streams), then a search operation Id is returned. If there are no matching vault items, then -1 is returned.
To obtain information about a search result, pass the returned search handle to the following methods:
- GetSearchResultAttributes
- GetSearchResultCreationTime
- GetSearchResultFullName
- GetSearchResultLastAccessTime
- GetSearchResultLinkDestination
- GetSearchResultMetadataSize
- GetSearchResultModificationTime
- GetSearchResultName
- GetSearchResultSize
To retrieve the next search result, pass the returned search handle to the FindNext method. When an application is finished with (or wants to abandon) a search operation, it must pass the associated search handle to the FindClose method to release the resources associated with it.
Because each search operation is identified by the search handle associated with it, applications may initiate additional search operations at any time and may process each operation's search results in any manner it desires (e.g., sequentially, round robin).
The FileMask parameter specifies both the directory path to search within and the file name mask to match against (e.g., \directory\to\search\*.txt). Or, when searching a file's alternate streams, it specifies the file path and stream name mask (e.g., \path\to\file:*). Only the mask may contain wildcards. The path must be specified in vault-local absolute format. Also note that files without an extension will match *, but not *.*.
The Attributes parameter specifies the attributes to match against; items will match only if they have one or more of the specified attributes. The value passed for this parameter should be constructed by ORing together zero or more of the following values. Passing 0 will allow any file in a directory (or, any alternate stream in a file) to match; it is equivalent to VAULT_FATTR_FILE | VAULT_FATTR_DATA_STREAM.
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
The Flags parameter controls search behavior. Among other things, it can be used to request that only specific pieces of information be returned, which can greatly improve performance. The value passed for this parameter should be constructed by ORing together zero or more of the following values:
VAULT_FF_NEED_NAME | 0x00000001 | Include entry names (without paths) when returning search results. |
VAULT_FF_NEED_FULL_NAME | 0x00000002 | Include fully qualified entry names when returning search results. |
VAULT_FF_NEED_ATTRIBUTES | 0x00000004 | Include entry attributes when returning search results. |
VAULT_FF_NEED_SIZE | 0x00000008 | Include entry sizes when returning search results. |
VAULT_FF_NEED_METADATA_SIZE | 0x00000010 | Include entry metadata sizes when returning search results. |
VAULT_FF_NEED_TIMES | 0x00000020 | Include entry times when returning search results. |
VAULT_FF_NEED_LINK_DEST | 0x00000040 | Include symbolic link destinations when returning search results. |
VAULT_FF_EMULATE_FAT | 0x00001000 | Inserts . and .. pseudo-entries into search results for all directories except the root one. |
VAULT_FF_RECURSIVE | 0x00002000 | Search recursively in all subdirectories. |
VAULT_FF_CASE_INSENSITIVE | 0x00004000 | Forces case-insensitive search, even if the vault is case-sensitive. |
Note: This method can be called only when Active is , and it cannot be called within events.
FindFirstByQuery Method (CBVault Module)
This method searches for the first file or directory whose file tags match the specified query.
Syntax
- (long long)findFirstByQuery:(NSString*)directory :(NSString*)query :(int)flags;
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:
VAULT_FF_NEED_NAME | 0x00000001 | Include entry names (without paths) when returning search results. |
VAULT_FF_NEED_FULL_NAME | 0x00000002 | Include fully qualified entry names when returning search results. |
VAULT_FF_NEED_ATTRIBUTES | 0x00000004 | Include entry attributes when returning search results. |
VAULT_FF_NEED_SIZE | 0x00000008 | Include entry sizes when returning search results. |
VAULT_FF_NEED_METADATA_SIZE | 0x00000010 | Include entry metadata sizes when returning search results. |
VAULT_FF_NEED_TIMES | 0x00000020 | Include entry times when returning search results. |
VAULT_FF_NEED_LINK_DEST | 0x00000040 | Include symbolic link destinations when returning search results. |
VAULT_FF_EMULATE_FAT | 0x00001000 | Inserts . and .. pseudo-entries into search results for all directories except the root one. |
VAULT_FF_RECURSIVE | 0x00002000 | Search recursively in all subdirectories. |
VAULT_FF_CASE_INSENSITIVE | 0x00004000 | Forces case-insensitive search, even if the vault is case-sensitive. |
Note: This method can be called only when Active is , and it cannot be called within events.
FindNext Method (CBVault Module)
This method searches for the next vault item that matches an ongoing search operation.
Syntax
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 ; otherwise, it returns .
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 , and it cannot be called within events.
GetFileAttributes Method (CBVault Module)
This method retrieves the attributes of a vault item.
Syntax
- (int)getFileAttributes:(NSString*)fileName;
Remarks
This method retrieves the attributes of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The specified vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
Note: This method can be called only when Active is .
GetFileCompression Method (CBVault Module)
This method retrieves the compression mode of a file or alternate stream.
Syntax
- (int)getFileCompression:(NSString*)fileName;
Remarks
This method retrieves the compression mode of the file or alternate stream specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The returned compression mode will be one of the following values:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
Note: This method can be called only when Active is .
GetFileCreationTime Method (CBVault Module)
This method retrieves the creation time of a vault item.
Syntax
- (NSDate*)getFileCreationTime:(NSString*)fileName;
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 .
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is .
GetFileEncryption Method (CBVault Module)
This method retrieves the encryption mode of a file or alternate stream.
Syntax
- (int)getFileEncryption:(NSString*)fileName;
Remarks
This method retrieves the encryption mode of the file or alternate stream specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The returned encryption mode will be one of the following values:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
Note: This method can be called only when Active is .
GetFileLastAccessTime Method (CBVault Module)
This method retrieves the last access time of a vault item.
Syntax
- (NSDate*)getFileLastAccessTime:(NSString*)fileName;
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 .
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 .
GetFileMetadataSize Method (CBVault Module)
This method retrieves the size of the metadata associated with a vault item.
Syntax
- (long long)getFileMetadataSize:(NSString*)fileName;
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 .
GetFileModificationTime Method (CBVault Module)
This method retrieves the modification time of a vault item.
Syntax
- (NSDate*)getFileModificationTime:(NSString*)fileName;
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 .
The value passed for FileName must be a vault-local absolute path.
Note: This method can be called only when Active is .
GetFileSize Method (CBVault Module)
This method retrieves the size of a file or alternate stream.
Syntax
- (long long)getFileSize:(NSString*)fileName;
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 .
GetFileTag Method (CBVault Module)
This method retrieves the binary data held by a raw file tag attached to the specified vault item.
Syntax
- (NSData*)getFileTag:(NSString*)fileName :(int)tagId;
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 .
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 .
GetFileTagAsAnsiString Method (CBVault Module)
This method retrieves the value of an AnsiString-typed file tag attached to the specified vault item.
Syntax
- (NSString*)getFileTagAsAnsiString:(NSString*)fileName :(NSString*)tagName;
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 .
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 .
GetFileTagAsBoolean Method (CBVault Module)
This method retrieves the value of a Boolean-typed file tag attached to the specified vault item.
Syntax
- (BOOL)getFileTagAsBoolean:(NSString*)fileName :(NSString*)tagName;
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 .
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 .
GetFileTagAsDateTime Method (CBVault Module)
This method retrieves the value of a DateTime-typed file tag attached to the specified vault item.
Syntax
- (NSDate*)getFileTagAsDateTime:(NSString*)fileName :(NSString*)tagName;
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 .
The timestamps returned by this method are specified .
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 .
GetFileTagAsNumber Method (CBVault Module)
This method retrieves the value of a Number-typed file tag attached to the specified vault item.
Syntax
- (long long)getFileTagAsNumber:(NSString*)fileName :(NSString*)tagName;
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 .
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 .
GetFileTagAsString Method (CBVault Module)
This method retrieves the value of a String-typed file tag attached to the specified vault item.
Syntax
- (NSString*)getFileTagAsString:(NSString*)fileName :(NSString*)tagName;
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 .
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 .
GetFileTagDataType Method (CBVault Module)
This method retrieves the data type of a typed file tag attached to a specific vault item.
Syntax
- (int)getFileTagDataType:(NSString*)fileName :(NSString*)tagName;
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 .
The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).
The value returned by this method will be one of the following (except VAULT_TDT_RAWDATA, which is not applicable):
VAULT_TDT_RAWDATA | 0x0 | The tag is untyped and must be addressed by Id. |
VAULT_TDT_BOOLEAN | 0x1 | The tag contains Boolean data and must be addressed by name. |
VAULT_TDT_STRING | 0x2 | The tag contains String (UTF-16LE) data and must be addressed by name. |
VAULT_TDT_DATETIME | 0x3 | The tag contains DateTime data and must be addressed by name. |
VAULT_TDT_NUMBER | 0x4 | The tag contains numeric (signed 64-bit) data and must be addressed by name. |
VAULT_TDT_ANSISTRING | 0x5 | The tag contains AnsiString (8-bit string) data and must be addressed by name. |
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is .
GetFileTagSize Method (CBVault Module)
This method retrieves the size of a raw file tag attached to the specified vault item.
Syntax
- (int)getFileTagSize:(NSString*)fileName :(int)tagId;
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 .
GetSearchResultAttributes Method (CBVault Module)
This method retrieves the attributes of a vault item found during a search operation.
Syntax
- (int)getSearchResultAttributes:(long long)searchId;
Remarks
This method retrieves the attributes of a vault item (e.g., file, directory, symbolic link, or alternate stream) found via FindFirst/FindFirstByQuery/FindNext as part of the search operation identified by SearchId. Please refer to those methods' documentation for more information.
The value passed for SearchId must be a search operation Id returned by FindFirst or FindFirstByQuery.
The vault item's attributes are returned as a 32-bit integer composed of one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
If, however, attributes were not requested as part of the specified search operation (by passing either 0 or a value including VAULT_FF_NEED_ATTRIBUTES for the FindFirst/FindFirstByQuery method's Flags parameter), this method will always return 0. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is .
GetSearchResultCreationTime Method (CBVault Module)
This method retrieves the creation time of a vault item found during a search operation.
Syntax
- (NSDate*)getSearchResultCreationTime:(long long)searchId;
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 .
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 January 1, 1601 00:00:00 UTC. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is .
GetSearchResultFullName Method (CBVault Module)
This method retrieves the fully qualified name of a vault item found during a search operation.
Syntax
- (NSString*)getSearchResultFullName:(long long)searchId;
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 .
GetSearchResultLastAccessTime Method (CBVault Module)
This method retrieves the last access time of a vault item found during a search operation.
Syntax
- (NSDate*)getSearchResultLastAccessTime:(long long)searchId;
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 .
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 January 1, 1601 00:00:00 UTC. 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 .
GetSearchResultLinkDestination Method (CBVault Module)
This method retrieves the destination of a symbolic link found during a search operation.
Syntax
- (NSString*)getSearchResultLinkDestination:(long long)searchId;
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 .
GetSearchResultMetadataSize Method (CBVault Module)
This method retrieves the size of the metadata associated with a vault item found during a search operation.
Syntax
- (long long)getSearchResultMetadataSize:(long long)searchId;
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 .
GetSearchResultModificationTime Method (CBVault Module)
This method retrieves the modification time of a vault item found during a search operation.
Syntax
- (NSDate*)getSearchResultModificationTime:(long long)searchId;
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 .
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 January 1, 1601 00:00:00 UTC. Please refer to the documentation for these methods for more information.
Note: This method can be called only when Active is .
GetSearchResultName Method (CBVault Module)
This method retrieves the name of a vault item found during a search operation.
Syntax
- (NSString*)getSearchResultName:(long long)searchId;
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 .
GetSearchResults Method (CBVault Module)
This method retrieves all information about a vault item found during a search operation.
Syntax
public func getSearchResults(searchId: Int64, name: inout NSString?, fullName: inout NSString?, attributes: inout Int32, size: inout Int64, creationTime: inout NSDate?, modificationTime: inout NSDate?, lastAccessTime: inout NSDate?, linkDestination: inout NSString?, metadataSize: inout Int64) throws -> Void
- (void)getSearchResults:(long long)searchId :(NSString**)name :(NSString**)fullName :(int*)attributes :(long long*)size :(NSDate**)creationTime :(NSDate**)modificationTime :(NSDate**)lastAccessTime :(NSString**)linkDestination :(long long*)metadataSize;
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 .
GetSearchResultSize Method (CBVault Module)
This method retrieves the size of a vault item found during a search operation.
Syntax
- (long long)getSearchResultSize:(long long)searchId;
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 .
IsDirectoryEmpty Method (CBVault Module)
This method checks whether a directory is empty.
Syntax
- (BOOL)isDirectoryEmpty:(NSString*)directory;
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 ; otherwise, it returns .
The value passed for Directory must be a vault-local absolute path.
Note: This method can be called only when Active is .
IsValidVault Method (CBVault Module)
This method checks whether a local file is a CBFS Vault vault.
Syntax
public func isValidVault() throws -> Bool
- (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 ; otherwise, it returns .
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 . If an error occurs during the detection process, this method .
Note: This method cannot be called when Active is , and it cannot be called within events.
MoveFile Method (CBVault Module)
This method renames or moves a vault item.
Syntax
- (void)moveFile:(NSString*)oldFileName :(NSString*)newFileName :(BOOL)overwrite;
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 , and such an item exists, it will be overwritten by the item specified by OldFileName. But if such an item exists, and Overwrite is , this method .
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 , and it cannot be called within events.
OpenFile Method (CBVault Module)
This method opens a new or existing file or alternate stream in the vault.
Syntax
public func openFile(fileName: String, openMode: Int32, readEnabled: Bool, writeEnabled: Bool, password: String) throws -> CBFSVaultStream
- (CBFSVaultStream*)openFile:(NSString*)fileName :(int)openMode :(BOOL)readEnabled :(BOOL)writeEnabled :(NSString*)password;
Remarks
This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.
Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.
The value passed for FileName must be a vault-local absolute path.
The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are as follows:
VAULT_FOM_CREATE_NEW | 0 | Creates a new file or alternate stream if possible, failing if one already exists. |
VAULT_FOM_CREATE_ALWAYS | 1 | Creates a new file or stream, overwriting an existing one if necessary. |
VAULT_FOM_OPEN_EXISTING | 2 | Opens a file or stream if it exists; fails otherwise. |
VAULT_FOM_OPEN_ALWAYS | 3 | Opens a file or stream if it exists; creates a new one otherwise. |
The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.
Note: WriteEnabled is ignored if ReadOnly is .
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 .
- 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 , and it cannot be called within events.
OpenFileEx Method (CBVault Module)
This method opens a new or existing file or alternate stream in the vault.
Syntax
public func openFileEx(fileName: String, openMode: Int32, readEnabled: Bool, writeEnabled: Bool, shareDenyRead: Bool, shareDenyWrite: Bool, encryption: Int32, password: String, compression: Int32, compressionLevel: Int32, pagesPerBlock: Int32) throws -> CBFSVaultStream
- (CBFSVaultStream*)openFileEx:(NSString*)fileName :(int)openMode :(BOOL)readEnabled :(BOOL)writeEnabled :(BOOL)shareDenyRead :(BOOL)shareDenyWrite :(int)encryption :(NSString*)password :(int)compression :(int)compressionLevel :(int)pagesPerBlock;
Remarks
This method opens the file or alternate stream specified by FileName, creating it if necessary based on the specified OpenMode, and returns a stream object that provides access to its data.
Note: Files and alternate streams cannot be created or written to if the vault is open in ReadOnly mode.
The value passed for FileName must be a vault-local absolute path.
The OpenMode parameter specifies what behavior to use when opening a file or alternate stream. Valid values are as follows:
VAULT_FOM_CREATE_NEW | 0 | Creates a new file or alternate stream if possible, failing if one already exists. |
VAULT_FOM_CREATE_ALWAYS | 1 | Creates a new file or stream, overwriting an existing one if necessary. |
VAULT_FOM_OPEN_EXISTING | 2 | Opens a file or stream if it exists; fails otherwise. |
VAULT_FOM_OPEN_ALWAYS | 3 | Opens a file or stream if it exists; creates a new one otherwise. |
The ReadEnabled and WriteEnabled parameters specify which kinds of access the returned stream object should permit.
Note: WriteEnabled is ignored if ReadOnly is .
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 ; to allow it, pass .
The Encryption parameter specifies the encryption mode to use when creating a file or alternate stream. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
The Password parameter works as follows:
- If the specified file or alternate stream already exists and is encrypted, the specified Password is used to decrypt and access its data.
- If a file or alternate stream is created, and Encryption is not VAULT_EM_NONE, the specified Password is used to encrypt it.
The Compression parameter specifies the compression mode to use when creating a file or alternate stream. Valid values are as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
The CompressionLevel parameter specifies the compression level to use, if applicable.
The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128), or 0, which is interpreted as "default" (currently 16 for both zlib and run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.
Note: This method can be called only when Active is , and it cannot be called within events.
OpenRootData Method (CBVault Module)
This method opens the vault's root data stream.
Syntax
public func openRootData() throws -> CBFSVaultStream
- (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 , and it cannot be called within events.
OpenVault Method (CBVault Module)
This method opens a new or existing vault.
Syntax
- (void)openVault:(int)openMode :(int)journalingMode;
Remarks
This method opens a vault, creating it if necessary based on the specified OpenMode.
The OpenMode parameter specifies what behavior to use when opening a vault. Valid values are as follows:
VAULT_OM_CREATE_NEW | 0 | Creates a new vault if possible, failing if one already exists. |
VAULT_OM_CREATE_ALWAYS | 1 | Creates a new vault, overwriting an existing one if necessary. |
VAULT_OM_OPEN_EXISTING | 2 | Opens a vault if it exists; fails otherwise. |
VAULT_OM_OPEN_ALWAYS | 3 | Opens a vault if it exists; creates a new one otherwise. |
The JournalingMode parameter specifies whether any form of journaling should be used when working with the vault. Valid values are as follows:
VAULT_JM_NONE | 0 | No journaling is used.
This mode ensures the fastest operations, but if the application crashes, corruption of the vault is possible. |
VAULT_JM_METADATA | 1 | Journaling is used only for metadata (filesystem structure and directory contents).
This mode is a balance between speed and reliability. |
VAULT_JM_FULL | 2 | Journaling is used for both filesystem structure and file data and metadata.
This mode is the slowest but the most reliable option. |
When a vault is being created or opened, the VaultFile and/or CallbackMode properties are used to specify its location. If CallbackMode is disabled (default), the class creates or opens a file-based vault at the path specified by VaultFile.
If CallbackMode is enabled, then the application controls where the vault is located and how it is accessed by the Vault* events (and the value held by VaultFile is simply passed to said events for the application to use). For brevity, vaults created and accessed using callback mode are referred to as "callback mode vaults"; please refer to the Callback Mode topic for more information.
The class also has a number of other properties and configuration settings used when creating or opening a vault, all of which are listed below. Please refer to each one's documentation for more information, including usage restrictions.
- AutoCompactAt property
- AutoCompactDelay configuration setting
- CaseSensitive property
- Logo property
- MaxNonPagedNameLength configuration setting
- PageSize property
- PartSize configuration setting
- PathSeparator property
- ReadOnly property
- UseAccessTime property
- UseSystemCache property
If a file-based vault's storage file (or the storage device it is located on) is marked as read-only, then the ReadOnly property must be enabled before this method is called. If an application attempts to open a vault with a read-only storage file in read-write mode, this method .
Note: This method cannot be called when Active is , and it cannot be called within events.
ResolveLink Method (CBVault Module)
This method retrieves the destination of a symbolic link.
Syntax
- (NSString*)resolveLink:(NSString*)linkName :(BOOL)normalize;
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 will ensure a vault-local absolute path is always returned; passing will cause the original destination path to be returned.
Note: This method can be called only when Active is .
SetFileAttributes Method (CBVault Module)
This method sets the attributes of a vault item.
Syntax
- (void)setFileAttributes:(NSString*)fileName :(int)attributes;
Remarks
This method sets the attributes of the vault item (e.g., file, directory, symbolic link, or alternate stream) specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The Attributes parameter specifies the new attributes for the vault item, which should be constructed by ORing together one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileCompression Method (CBVault Module)
This method compresses or decompresses a file or alternate stream.
Syntax
public func setFileCompression(fileName: String, compression: Int32, compressionLevel: Int32, pagesPerBlock: Int32, password: String) throws -> Void
- (void)setFileCompression:(NSString*)fileName :(int)compression :(int)compressionLevel :(int)pagesPerBlock :(NSString*)password;
Remarks
This method changes the compression mode used to compress the file or alternate stream specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The Compression parameter specifies the new compression mode to use. Valid values are as follows:
VAULT_CM_NONE | 0 | Do not use compression. |
VAULT_CM_DEFAULT | 1 | Use default compression (zlib). |
VAULT_CM_CUSTOM | 2 | Use event-based custom compression.
This compression level is not used. |
VAULT_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
VAULT_CM_RLE | 4 | Use RLE compression.
This compression level is not used. |
Applications that use custom compression must implement the DataCompress and DataDecompress events. Please refer to the Compression topic for more information.
The CompressionLevel parameter specifies the compression level to use, if applicable.
The PagesPerBlock parameter specifies how many pages should be compressed as a single block, if applicable. Valid values are powers of 2 up to and including 128 (i.e., 2, 4, 8, 16, 32, 64, or 128), or 0, which is interpreted as "default" (currently 16 for both zlib and run-length encoding [RLE]). Larger values allow for more efficient compression; however, because a block must be decompressed (and, for writes, recompressed) anytime its data are accessed, larger values can also cause excessive slowdown, especially for random access.
The Password parameter specifies the password to use to access the file's data, if it is encrypted.
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileCreationTime Method (CBVault Module)
This method sets the creation time of a vault item.
Syntax
- (void)setFileCreationTime:(NSString*)fileName :(NSDate*)creationTime;
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 .
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileEncryption Method (CBVault Module)
This method encrypts, decrypts, or changes the encryption password of a file or alternate stream.
Syntax
public func setFileEncryption(fileName: String, encryption: Int32, oldPassword: String, newPassword: String) throws -> Void
- (void)setFileEncryption:(NSString*)fileName :(int)encryption :(NSString*)oldPassword :(NSString*)newPassword;
Remarks
This method changes the encryption mode or password used to encrypt the file or alternate stream specified by FileName.
The value passed for FileName must be a vault-local absolute path.
The Encryption parameter specifies the new encryption mode to use. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
The OldPassword parameter specifies the current encryption password, if applicable.
The NewPassword parameter specifies the new encryption password to use, if applicable.
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileLastAccessTime Method (CBVault Module)
This method sets the last access time of a vault item.
Syntax
- (void)setFileLastAccessTime:(NSString*)fileName :(NSDate*)lastAccessTime;
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 .
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileModificationTime Method (CBVault Module)
This method sets the modification time of a vault item.
Syntax
- (void)setFileModificationTime:(NSString*)fileName :(NSDate*)modificationTime;
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 .
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileSize Method (CBVault Module)
This method sets the size of a file or alternate stream.
Syntax
- (void)setFileSize:(NSString*)fileName :(long long)size :(NSString*)password;
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 , and it cannot be called within events.
SetFileTag Method (CBVault Module)
This method attaches a raw file tag with binary data to the specified vault item.
Syntax
- (void)setFileTag:(NSString*)fileName :(int)tagId :(NSData*)data;
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 , and it cannot be called within events.
SetFileTagAsAnsiString Method (CBVault Module)
This method attaches an AnsiString-typed file tag to the specified vault item.
Syntax
- (void)setFileTagAsAnsiString:(NSString*)fileName :(NSString*)tagName :(NSString*)value;
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 , and it cannot be called within events.
SetFileTagAsBoolean Method (CBVault Module)
This method attaches a Boolean-typed file tag to the specified vault item.
Syntax
- (void)setFileTagAsBoolean:(NSString*)fileName :(NSString*)tagName :(BOOL)value;
Remarks
This method attaches a Boolean-typed file tag to the vault item (e.g., file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.
The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).
The Value parameter specifies the Boolean value to store in the file tag.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileTagAsDateTime Method (CBVault Module)
This method attaches a DateTime-typed file tag to the specified vault item.
Syntax
- (void)setFileTagAsDateTime:(NSString*)fileName :(NSString*)tagName :(NSDate*)value;
Remarks
This method attaches a DateTime-typed file tag to the vault item (e.g., file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.
The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).
The Value parameter specifies the DateTime value to store in the file tag, which must be specified .
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileTagAsNumber Method (CBVault Module)
This method attaches a Number-typed file tag to the specified vault item.
Syntax
- (void)setFileTagAsNumber:(NSString*)fileName :(NSString*)tagName :(long long)value;
Remarks
This method attaches a Number-typed file tag to the vault item (e.g., file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.
The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).
The Value parameter specifies the Number value to store in the file tag.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is , and it cannot be called within events.
SetFileTagAsString Method (CBVault Module)
This method attaches a String-typed file tag to the specified vault item.
Syntax
- (void)setFileTagAsString:(NSString*)fileName :(NSString*)tagName :(NSString*)value;
Remarks
This method attaches a String-typed file tag to the vault item (e.g., file, directory, or alternate stream) specified by FileTag using the specified TagName. If a typed file tag with the specified TagName is already attached to the specified vault item, it is replaced.
The value passed for FileName must be a vault-local absolute path. The value passed for TagName may be up to 4095 characters in length (not including the null terminator).
The Value parameter specifies the UTF-16LE String value to store in the file tag; it may be up to 65529 - (name_length * 2) bytes in length (where name_length is measured in characters), including null terminators for both the String value and the name.
Please refer to the File Tags topic for more information.
Note: This method can be called only when Active is , and it cannot be called within events.
UnixTimeToFileTime Method (CBVault Module)
This method converts the date/time in Unix format to the Windows FileTime format.
Syntax
- (NSDate*)unixTimeToFileTime:(long long)unixTime :(int)nanoseconds;
Remarks
Use this method to convert the date/time in Unix format to the Windows FileTime format.
Pass the Unix time value to UnixTime and optionally pass the subsecond part of the time, expressed in nanoseconds, to the Nanoseconds parameter. If the subsecond part of the time is not available, set Nanoseconds to zero (0) value.
UpdateVaultEncryption Method (CBVault Module)
This method encrypts, decrypts, or changes the encryption password of the vault.
Syntax
public func updateVaultEncryption(encryption: Int32, oldPassword: String, newPassword: String) throws -> Void
- (void)updateVaultEncryption:(int)encryption :(NSString*)oldPassword :(NSString*)newPassword;
Remarks
This method changes the encryption mode or password used to encrypt the vault.
The Encryption parameter specifies the new encryption mode to use. Valid values are as follows:
VAULT_EM_NONE | 0x0 | Do not use encryption. |
VAULT_EM_DEFAULT | 0x1 | Use default encryption (VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
VAULT_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
VAULT_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. |
VAULT_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
A 256-bit (32-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
A 512-bit (64-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
A 1024-bit (128-byte) block size is used with this encryption mode. This mode is useful for cases in which the password is an identifier for an external key and should not be used for key derivation. |
VAULT_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataEncrypt and DataDecrypt events. Certain custom encryption modes may require that the HashCalculate or KeyDerive event be implemented as well. Please refer to the Encryption topic for more information.
The OldPassword parameter specifies the current encryption password, if applicable.
The NewPassword parameter specifies the new encryption password to use, if applicable.
Note: This method can be called only when Active is , and it cannot be called within events.
DataCompress Event (CBVault Module)
This event fires to compress a block of data using a custom compression algorithm.
Syntax
func onDataCompress(inData: Data, inSize: Int32, outData: NSMutableData, outSize: inout Int32, compressionLevel: Int32, resultCode: inout Int32)
- (void)onDataCompress:(NSMutableData*)inData :(int)inSize :(NSMutableData*)outData :(int*)outSize :(int)compressionLevel :(int*)resultCode;
Remarks
This event fires when the class needs to compress a block of data using an application-defined compression algorithm. Please refer to the Compression topic for more information.
This event only needs to be handled by applications that use the VAULT_CM_CUSTOM compression mode. To handle this event properly, applications must compress all InSize bytes of data in the InData buffer, write the compressed data to the OutData buffer, and set OutSize to reflect the total number of bytes written to OutData.
Note: OutSize is initially set to the capacity of the OutData buffer. If the OutData buffer is not large enough to accommodate all of the data after compression (which, while uncommon, may occur with some compression algorithms), do not write any data to OutData. Instead, set ResultCode to VAULT_ERR_BUFFER_TOO_SMALL to inform the class that the current block of data should remain uncompressed.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The CompressionLevel specifies the requested compression level. Possible values are 0 through 9; where 0 means "use the default compression level". Applications may ignore this value if it is not needed by their compression algorithm.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
DataDecompress Event (CBVault Module)
This event fires to decompress a block of data using a custom compression algorithm.
Syntax
func onDataDecompress(inData: Data, inSize: Int32, outData: NSMutableData, outSize: inout Int32, resultCode: inout Int32)
- (void)onDataDecompress:(NSMutableData*)inData :(int)inSize :(NSMutableData*)outData :(int*)outSize :(int*)resultCode;
Remarks
This event fires when the class needs to decompress a block of data using an application-defined compression algorithm. Please refer to the Compression topic for more information.
This event only needs to be handled by applications that use the VAULT_CM_CUSTOM compression mode. To handle this event properly, applications must decompress all InSize bytes of data in the InData buffer, write the decompressed data to the OutData buffer, and set OutSize to reflect the total number of bytes written to OutData.
Note: OutSize is initially set to the capacity of the OutData buffer, which (under normal circumstances) should be large enough to accommodate all of the decompressed data. Only if the vault is corrupted should the OutData buffer ever be too small to hold the decompressed data; so if this occurs, do not write any data to OutData. Instead, set ResultCode to VAULT_ERR_VAULT_CORRUPTED.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
DataDecrypt Event (CBVault Module)
This event fires to decrypt a block of data using a custom encryption implementation.
Syntax
func onDataDecrypt(key: Data, keyLength: Int32, salt1: Data, salt1Size: Int32, salt2: Data, salt2Size: Int32, data: NSMutableData, dataSize: Int32, resultCode: inout Int32)
- (void)onDataDecrypt:(NSMutableData*)key :(int)keyLength :(NSMutableData*)salt1 :(int)salt1Size :(NSMutableData*)salt2 :(int)salt2Size :(NSMutableData*)data :(int)dataSize :(int*)resultCode;
Remarks
This event fires when the class needs to decrypt a block of data using an application-defined encryption implementation. Please refer to the Encryption topic for more information.
This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM* encryption modes. To handle this event properly, applications must decrypt all DataSize bytes of data in the Data buffer. After decrypting the data, applications must write it back to the Data buffer. The size of the decrypted data must match DataSize, which is always a multiple of 32.
The Key buffer contains the encryption key (e.g., password) specified for the file, alternate stream, or vault whose data are being decrypted. The KeyLength parameter specifies the length, in bytes, of Key.
The Salt1 and Salt2 buffers contain the same salt values provided when the data were encrypted in an earlier DataEncrypt event. The Salt1Size and Salt2Size parameters specify the length, in bytes, of Salt1 and Salt2.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
DataEncrypt Event (CBVault Module)
This event fires to encrypt a block of data using a custom encryption implementation.
Syntax
func onDataEncrypt(key: Data, keyLength: Int32, salt1: Data, salt1Size: Int32, salt2: Data, salt2Size: Int32, data: NSMutableData, dataSize: Int32, resultCode: inout Int32)
- (void)onDataEncrypt:(NSMutableData*)key :(int)keyLength :(NSMutableData*)salt1 :(int)salt1Size :(NSMutableData*)salt2 :(int)salt2Size :(NSMutableData*)data :(int)dataSize :(int*)resultCode;
Remarks
This event fires when the class needs to encrypt a block of data using an application-defined encryption implementation. Please refer to the Encryption topic for more information.
This event only needs to be handled by applications that use one of the VAULT_EM_CUSTOM* encryption modes. To handle this event properly, applications must encrypt all DataSize bytes of data in the Data buffer. After encrypting the data, applications must write it back to the Data buffer. The size of the encrypted data must match DataSize, which is always a multiple of 32.
The Key buffer contains the encryption key (e.g., password) specified for the file, alternate stream, or vault whose data are being decrypted. The KeyLength parameter specifies the length, in bytes, of Key.
The Salt1 and Salt2 buffers contain salt values that can be used to strengthen encryption, if desired. The Salt1Size and Salt2Size parameters specify the length, in bytes, of Salt1 and Salt2.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
Error Event (CBVault Module)
This event fires if an unhandled error occurs during an event.
Syntax
- (void)onError:(int)errorCode :(NSString*)description;
Remarks
This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.
FileAfterCopy Event (CBVault Module)
This event fires after the file has been copied during file export/import operations.
Syntax
func onFileAfterCopy(sourcePath: String, destinationPath: String, attributes: Int32, resultCode: inout Int32)
- (void)onFileAfterCopy:(NSString*)sourcePath :(NSString*)destinationPath :(int)attributes :(int*)resultCode;
Remarks
This event fires when the class is executing the CopyToVault or CopyFromVault method after the file specified by SourcePath has been copied to a file identified by DestinationPath.
For a directory, the event fires after the directory identified by SourcePath has been created as DestinationPath and all of the source directory's contents have been processed.
The event will fire only if the VAULT_CFF_FIRE_COPY_EVENTS flag is included in the Flags parameter of the CopyFromVault or CopyToVault method. Also, the event will not fire for the base directory that was passed to the CopyToVault or CopyFromVault method.
A process may check whether it was a file or directory copied by inspecting the value of the Attributes parameter, which contains the attributes of the file as a 32-bit integer. The attributes are composed of one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
To cancel further copying, return the VAULT_ERR_INTERRUPTED_BY_USER error code via ResultCode.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
FileBeforeCopy Event (CBVault Module)
This event fires before the file is copied during file export/import operations.
Syntax
func onFileBeforeCopy(sourcePath: String, destinationPath: String, attributes: inout Int32, destinationExists: Bool, skip: inout Bool, resultCode: inout Int32)
- (void)onFileBeforeCopy:(NSString*)sourcePath :(NSString*)destinationPath :(int*)attributes :(BOOL)destinationExists :(int*)skip :(int*)resultCode;
Remarks
This event fires when the class is executing the CopyToVault or CopyFromVault method before the file specified by SourcePath is copied to a file identified by DestinationPath or before the directory identified by SourcePath is about to be created as DestinationPath.
This event will fire only if the VAULT_CFF_FIRE_COPY_EVENTS flag is included in the Flags parameter of the CopyFromVault or CopyToVault method. Also, the event will not fire for the base directory that was passed to the CopyToVault or CopyFromVault method.
A process may check whether it is a file or a directory being copied by inspecting the value of the Attributes parameter, which contains the attributes of the file as a 32-bit integer. The attributes are composed of one or more of the following values:
VAULT_FATTR_FILE | 0x00000001 | The entry is a file. |
VAULT_FATTR_DIRECTORY | 0x00000002 | The entry is a directory. |
VAULT_FATTR_DATA_STREAM | 0x00000004 | The entry is an alternate data stream. |
VAULT_FATTR_COMPRESSED | 0x00000008 | The file or stream is compressed. |
VAULT_FATTR_ENCRYPTED | 0x00000010 | The file or stream is encrypted. |
VAULT_FATTR_SYMLINK | 0x00000020 | The entry is a symbolic link. |
VAULT_FATTR_READONLY | 0x00000040 | The file is read-only.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_ARCHIVE | 0x00000080 | The file requires archiving.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_HIDDEN | 0x00000100 | The file is hidden.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_SYSTEM | 0x00000200 | The file is a system file.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_TEMPORARY | 0x00000400 | The file is temporary.
This attribute is not used by CBFS Vault, but it can be set and retrieved. |
VAULT_FATTR_DELETE_ON_CLOSE | 0x00000800 | The file should be deleted when the last handle to the file is closed.
This attribute is currently not supported by CBFS Vault. |
VAULT_FATTR_RESERVED_0 | 0x00001000 | Reserved. |
VAULT_FATTR_RESERVED_1 | 0x00002000 | Reserved. |
VAULT_FATTR_RESERVED_2 | 0x00004000 | Reserved. |
VAULT_FATTR_RESERVED_3 | 0x00008000 | Reserved. |
VAULT_FATTR_NO_USER_CHANGE | 0x0000F03F | A mask that includes all attributes that cannot be changed.
Applications cannot use the SetFileAttributes method to directly change any of the following attributes: FILE, DIRECTORY, DATA_STREAM, COMPRESSED, ENCRYPTED, SYMLINK, RESERVED_0, RESERVED_1, RESERVED_2, or RESERVED_3. |
VAULT_FATTR_USER_DEFINED | 0x7FF00000 | A mask for application-defined attributes.
Applications can use the SetFileAttributes method to set custom attributes, as long as their values are covered by this mask. |
VAULT_FATTR_ANY_FILE | 0x7FFFFFFF | A mask that includes any and all attributes. |
An event handler may change the following attributes: VAULT_FATTR_READONLY, VAULT_FATTR_ARCHIVE, VAULT_FATTR_HIDDEN, VAULT_FATTR_SYSTEM, VAULT_FATTR_TEMPORARY. When files are imported to the vault, an event handler may set user-defined flags that match the VAULT_FATTR_USER_DEFINED mask.
The DestinationExists flag indicates the presence of the file or directory at the moment when the event is fired.
Note: When copying the files from the vault, it is possible that a file gets created or deleted outside of the class; the value of this parameter may become inaccurate.
To skip the file, set the Skip parameter to true. When the file is skipped, FileAfterCopy does not fire.
To cancel copying, return the VAULT_ERR_INTERRUPTED_BY_USER error code via ResultCode.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
FilePasswordNeeded Event (CBVault Module)
This event fires if a password is needed to open an encrypted file.
Syntax
func onFilePasswordNeeded(fileName: String, password: inout NSString?, ttlInCache: inout Int32, resultCode: inout Int32)
- (void)onFilePasswordNeeded:(NSString*)fileName :(NSString**)password :(int*)TTLInCache :(int*)resultCode;
Remarks
This event fires when the encrypted file specified by FileName is being opened if a valid password has not been provided (either directly, or via the DefaultFileAccessPassword property or CacheFilePassword method). This event will not fire if a valid password has already been provided, or if the file specified by FileName does not exist in the vault.
To allow access to the specified file, set the Password parameter to the correct password.
If an invalid password is provided by the event handler, the event will fire again.
To prevent access to the specified file or to stop being asked for a password in a loop, return the VAULT_ERR_INVALID_PASSWORD error code via ResultCode.
The TTLInCache parameter specifies time to seconds that the class keeps the password in the internal cache to reduce the number of requests for a password. The value of 0 tells the class to discard the password after the first use.
Note: This event can be fired on different threads, and possibly even on several threads concurrently. As an alternative to handling this event, applications can provide a default file encryption password using the DefaultFileAccessPassword property or can call the CacheFilePassword method (before a file is opened) to specify a one-time-use password.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
HashCalculate Event (CBVault Module)
This event fires to calculate a password hash using a custom hashing implementation.
Syntax
func onHashCalculate(password: Data, passwordSize: Int32, salt: Data, saltSize: Int32, hash: NSMutableData, hashSize: Int32, resultCode: inout Int32)
- (void)onHashCalculate:(NSMutableData*)password :(int)passwordSize :(NSMutableData*)salt :(int)saltSize :(NSMutableData*)hash :(int)hashSize :(int*)resultCode;
Remarks
This event fires when the class needs to calculate a password hash using an application-defined hashing implementation. The calculated hash is used to check the password's validity before using it for encryption. Please refer to the Encryption topic for more information.
This event needs to be handled only by applications that use one of the VAULT_EM_CUSTOM*_DIRECT_KEY encryption modes. To handle this event property, applications must calculate a hash of the data in the Password buffer (whose length, in bytes, is specified by PasswordSize). The calculated hash must be written to the Hash buffer. The size of the calculated hash must not exceed HashSize.
Applications may perform, if desired, their own password validation and return a predefined value for the hash. Applications should not use the same process for key derivation and hash calculation (or should, at the very least, ensure that Salt is used in both operations).
The Salt buffer contains a salt value that can be used (if desired) to strengthen security by increasing the uniqueness of the hash. The SaltSize parameter specifies the length, in bytes, of Salt.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
KeyDerive Event (CBVault Module)
This event fires to derive an encryption key using a custom key derivation implementation.
Syntax
func onKeyDerive(password: Data, passwordSize: Int32, salt: Data, saltSize: Int32, key: NSMutableData, keySize: Int32, resultCode: inout Int32)
- (void)onKeyDerive:(NSMutableData*)password :(int)passwordSize :(NSMutableData*)salt :(int)saltSize :(NSMutableData*)key :(int)keySize :(int*)resultCode;
Remarks
This event fires when the class needs to derive an encryption key using an application-defined key derivation implementation. Please refer to the Encryption topic for more information.
This event needs to be handled only by applications that use one of the VAULT_EM_CUSTOM*_CUSTOM_KEY_DERIVE encryption modes. To handle this event properly, applications must derive an encryption key from the data in the Password buffer (whose length, in bytes, is specified by PasswordSize). The derived encryption key must be written to the Key buffer. The size of the derived encryption key must not exceed KeySize.
Applications should not use the same process for key derivation and hash calculation (or should, at the very least, ensure that Salt is used in both operations).
The Salt buffer contains a salt value that can be used (if desired) to strengthen security by increasing the uniqueness of the derived key. The SaltSize parameter specifies the length, in bytes, of Salt.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
Progress Event (CBVault Module)
This event fires to indicate the progress of long-running vault operations.
Syntax
func onProgress(operation: Int32, fileName: String, progress: Int32, total: Int32, canStop: Bool, stop: inout Bool)
- (void)onProgress:(int)operation :(NSString*)fileName :(int)progress :(int)total :(BOOL)canStop :(int*)stop;
Remarks
This event fires anytime the class needs to report the progress of a long-running vault operation. Certain operations may cause this event to fire repeatedly.
The Operation parameter specifies which long-running operation caused this event to fire. Possible values are as follows:
VAULT_PO_FORMATTING | 0 | Formatting a vault. |
VAULT_PO_CHECKING_1 | 1 | Checking a vault (stage 1). |
VAULT_PO_CHECKING_2 | 2 | Checking a vault (stage 2). |
VAULT_PO_CHECKING_3 | 3 | Checking a vault (stage 3). |
VAULT_PO_CHECKING_4 | 4 | Checking a vault (stage 4). |
VAULT_PO_CHECKING_5 | 5 | Checking a vault (stage 5). |
VAULT_PO_PAGE_CORRUPTED | 8 | Processing a corrupted vault page. |
VAULT_PO_PAGE_ORPHANED | 9 | Processing an orphaned vault page. |
VAULT_PO_COMPRESSING | 10 | Compressing a file or alternate stream. |
VAULT_PO_DECOMPRESSING | 11 | Decompressing a file or alternate stream. |
VAULT_PO_ENCRYPTING | 12 | Encrypting a vault, file, or alternate stream. |
VAULT_PO_DECRYPTING | 13 | Decrypting a vault, file, or alternate stream |
VAULT_PO_COMPACTING | 14 | Compacting a vault. |
VAULT_PO_RESIZING | 15 | Resizing a vault. |
VAULT_PO_CALCULATING_SIZE | 16 | Calculating a vault's size. |
VAULT_PO_COPYING_FILES_TO_VAULT | 17 | Copying files to a vault. |
VAULT_PO_COPYING_FILES_FROM_VAULT | 18 | Copying files from a vault. |
When the operation is copying files from or to the vault, FileName contains the path of the source file being copied.
The Progress and Total parameters reflect the current and maximum progress values. Both will be 0 if the operation's progression cannot be determined.
The CanStop parameter indicates whether the application may interrupt the operation by setting the Stop parameter to .
Note: Some operations can be interrupted only at certain points over the course of their lifetime.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultClose Event (CBVault Module)
This event fires to close a callback mode vault.
Syntax
func onVaultClose(vaultHandle: Int64, resultCode: inout Int32)
- (void)onVaultClose:(long long)vaultHandle :(int*)resultCode;
Remarks
This event fires when the class needs to close the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must close the vault specified by VaultHandle and invalidate the handle itself.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultDelete Event (CBVault Module)
This event fires to delete a callback mode vault.
Syntax
func onVaultDelete(vault: String, resultCode: inout Int32)
- (void)onVaultDelete:(NSString*)vault :(int*)resultCode;
Remarks
This event fires when the class needs to delete the callback mode vault identified by Vault.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must delete the vault identified by Vault.
The Vault parameter contains an application-defined vault identifier (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile property.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultFlush Event (CBVault Module)
This event fires to flush a callback mode vault's data out to storage.
Syntax
func onVaultFlush(vaultHandle: Int64, resultCode: inout Int32)
- (void)onVaultFlush:(long long)vaultHandle :(int*)resultCode;
Remarks
This event fires when the class needs to flush the data of the callback mode vault specified by VaultHandle out to storage.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must flush all data currently buffered for the vault specified by VaultHandle out to storage. For example, if the application is storing vault data in a file on disk, it could call FlushFileBuffers() on Windows.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultGetParentSize Event (CBVault Module)
This event fires to determine how much free space is available for growing a callback mode vault.
Syntax
func onVaultGetParentSize(vault: String, vaultHandle: Int64, freeSpace: inout Int64, resultCode: inout Int32)
- (void)onVaultGetParentSize:(NSString*)vault :(long long)vaultHandle :(long long*)freeSpace :(int*)resultCode;
Remarks
This event fires when the class needs to determine how much free space is available for growing the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must set FreeSpace to indicate how many bytes of free space are available in the "parent storage" of the vault specified by VaultHandle. For example:
- If the vault is stored in a file, return the amount of free space on the associated disk.
- If the vault is stored in memory, return the amount of memory available to the application (keeping in mind any other memory needs the application may have).
- If the vault is stored on some remote system, query it to determine how much free space is available.
The Vault parameter contains an application-defined vault identifier (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile property.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultGetSize Event (CBVault Module)
This event fires to determine the size of a callback mode vault.
Syntax
func onVaultGetSize(vaultHandle: Int64, size: inout Int64, resultCode: inout Int32)
- (void)onVaultGetSize:(long long)vaultHandle :(long long*)size :(int*)resultCode;
Remarks
This event fires when the class needs to determine the size of the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must set Size to indicate the size, in bytes, of the vault specified by VaultHandle.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultOpen Event (CBVault Module)
This event fires to open a new or existing callback mode vault.
Syntax
func onVaultOpen(vault: String, vaultHandle: inout Int64, openMode: Int32, readOnly: inout Bool, resultCode: inout Int32)
- (void)onVaultOpen:(NSString*)vault :(long long*)vaultHandle :(int)openMode :(int*)readOnly :(int*)resultCode;
Remarks
This event fires when the class wants to open the callback mode vault identified by Vault.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must open the vault identified by Vault, creating it if necessary based on the specified OpenMode, and return any associated information in VaultHandle.
If the ReadOnly parameter is initially , the application must open the vault in read-only mode. If ReadOnly is initially , the application may choose whether to open the vault in read-only or read-write mode. It should update the ReadOnly parameter accordingly, if necessary.
If, for any reason, the vault cannot be opened in a manner consistent with the specified OpenMode, the application must return an appropriate error code via ResultCode.
The Vault parameter contains an application-defined vault identifier (e.g., name, file path). The value of this parameter will always match the current value of the VaultFile property.
The VaultHandle parameter is used to return some application-defined handle that uniquely identifies the opened vault. The class uses the returned handle to populate the VaultHandle parameters of the other Vault* events fired for the vault later.
The OpenMode parameter specifies what behavior to use when opening the vault. Valid values are as follows:
VAULT_OM_CREATE_NEW | 0 | Creates a new vault if possible, failing if one already exists. |
VAULT_OM_CREATE_ALWAYS | 1 | Creates a new vault, overwriting an existing one if necessary. |
VAULT_OM_OPEN_EXISTING | 2 | Opens a vault if it exists; fails otherwise. |
VAULT_OM_OPEN_ALWAYS | 3 | Opens a vault if it exists; creates a new one otherwise. |
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultRead Event (CBVault Module)
This event fires to read data from a callback mode vault.
Syntax
func onVaultRead(vaultHandle: Int64, offset: Int64, buffer: NSMutableData, count: Int32, resultCode: inout Int32)
- (void)onVaultRead:(long long)vaultHandle :(long long)offset :(NSMutableData*)buffer :(int)count :(int*)resultCode;
Remarks
This event fires when the class needs to read data from the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must read Count bytes of data from the vault specified by VaultHandle into Buffer, starting at the specified Offset in the vault.
Count is always a multiple of the vault's PageSize. If, for any reason, an application cannot read exactly Count bytes of data from the vault, it must return an appropriate error code via ResultCode.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultSetSize Event (CBVault Module)
This event fires to resize a callback mode vault.
Syntax
func onVaultSetSize(vaultHandle: Int64, newSize: Int64, resultCode: inout Int32)
- (void)onVaultSetSize:(long long)vaultHandle :(long long)newSize :(int*)resultCode;
Remarks
This event fires when the class needs to resize the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must grow or shrink the vault specified by VaultHandle to reach the specified NewSize. When growing a vault, applications do not need to sanitize newly allocated space.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
VaultWrite Event (CBVault Module)
This event fires to write data to a callback mode vault.
Syntax
func onVaultWrite(vaultHandle: Int64, offset: Int64, buffer: Data, count: Int32, resultCode: inout Int32)
- (void)onVaultWrite:(long long)vaultHandle :(long long)offset :(NSMutableData*)buffer :(int)count :(int*)resultCode;
Remarks
This event fires when the class needs to write data to the callback mode vault specified by VaultHandle.
This event needs to be handled only if the CallbackMode property is enabled; please refer to the Callback Mode topic for more information. To handle this event properly, applications must write Count bytes of data from Buffer to the vault specified by VaultHandle, starting at the specified Offset in the vault.
Count is always a multiple of the vault's PageSize. If, for any reason, an application cannot write exactly Count bytes of data to the vault, it must return an appropriate error code via ResultCode.
Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.
The VaultHandle parameter contains an application-defined information, associated with an open callback mode vault, as returned by the application in an earlier VaultOpen event.
The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.
Note: An application should not attempt to call class's methods from handlers of this event. Doing this is guaranteed to cause a deadlock.
CBFSVaultStream Type
Syntax
CBFSVaultStream (declared in cbfsvault.h)
Remarks
The CBFSVaultStream type is returned by some of the CBVault class's methods. All stream types in CBFS Vault share a common API, documented below.
Config Settings (CBVault Module)
The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.CBVault Config Settings
By default, this setting is disabled, and alternate streams can be renamed only within the same file, and cannot be moved between them.
Note: This setting cannot be changed within events.
By default, this setting is set to 0, and automatic compaction operations will start without delay.
Note: This setting cannot be changed within events.
By default, this setting is set to 0.
A vault's maximum nonpaged name length is permanent, and it cannot be changed after the vault is created. When a vault is open, this configuration setting cannot be changed, and it can be queried only to obtain the value used by the vault.
By default, this setting is set to 0, and the class will automatically choose an optimal value when creating a vault based on PageSize.
Note: This setting cannot be changed when Active is , and it cannot be changed within events.
This configuration setting controls the size of the built-in data cache; it is specified in bytes. The cache must be large enough to contain at least eight pages, so this setting's minimum valid value is eight times the value of the PageSize property.
By default, this configuration setting is set to 16777216 (16 MB).
Note: This setting can be changed only when Active is .
A multipart vault's part size is permanent, and it cannot be changed after the vault is created. When a vault is open, this configuration setting cannot be changed, and it can be queried only to obtain the value used by the vault.
By default, this setting is set to 0, and the class will not create multipart vaults.
Note: This setting cannot be changed when Active is , and it cannot be changed within events.
Trappable Errors (CBVault Module)
The class uses the following error codes, all of which are also available as constants for applications' convenience. Please refer to the Error Handling topic for more information.CBVault Errors
-1 | The specified file is not a CBFS Vault vault. (VAULT_ERR_INVALID_VAULT_FILE) |
-2 | The specified page size is not valid. (VAULT_ERR_INVALID_PAGE_SIZE) |
-3 | The vault is corrupted. Please call CheckAndRepair. (VAULT_ERR_VAULT_CORRUPTED) |
-4 | Too many transactions active. (VAULT_ERR_TOO_MANY_TRANSACTIONS) |
-5 | A file, directory, symbolic link, or alternate stream with the specified name already exists. (VAULT_ERR_FILE_ALREADY_EXISTS) |
-6 | One or more transactions are still active. (VAULT_ERR_TRANSACTIONS_STILL_ACTIVE) |
-7 | The specified file tag already exists. (VAULT_ERR_TAG_ALREADY_EXISTS) |
-8 | The specified file, directory, symbolic link, or alternate stream was not found. (VAULT_ERR_FILE_NOT_FOUND) |
-9 | The specified path was not found. (VAULT_ERR_PATH_NOT_FOUND) |
-10 | The specified file or alternate stream is already open in an exclusive access mode. (VAULT_ERR_SHARING_VIOLATION) |
-11 | Cannot seek beyond the end of a file or alternate stream. (VAULT_ERR_SEEK_BEYOND_EOF) |
-12 | No other files, directories, symbolic links, or alternate streams match the search criteria. (VAULT_ERR_NO_MORE_FILES) |
-13 | The specified name is not valid. (VAULT_ERR_INVALID_FILE_NAME) |
-14 | The requested operation cannot be performed while a vault is open. (VAULT_ERR_VAULT_ACTIVE) |
-15 | A vault must be open before the requested operation can be performed. (VAULT_ERR_VAULT_NOT_ACTIVE) |
-16 | The specified password is incorrect. (VAULT_ERR_INVALID_PASSWORD) |
-17 | The requested operation cannot be performed; the vault is open in read-only mode. (VAULT_ERR_VAULT_READ_ONLY) |
-18 | Cannot use custom encryption; no custom encryption event handlers provided. (VAULT_ERR_NO_ENCRYPTION_HANDLERS) |
-19 | Out of memory. (VAULT_ERR_OUT_OF_MEMORY) |
-20 | A symbolic link's destination file could not be found. (VAULT_ERR_SYMLINK_DESTINATION_NOT_FOUND) |
-21 | The specified file is not a symbolic link. (VAULT_ERR_FILE_IS_NOT_SYMLINK) |
-22 | The specified buffer is too small to hold the requested value. (VAULT_ERR_BUFFER_TOO_SMALL) |
-23 | Decompression failed (possibly due to corruption). (VAULT_ERR_BAD_COMPRESSED_DATA) |
-24 | Invalid parameter. (VAULT_ERR_INVALID_PARAMETER) |
-25 | The vault is full (and cannot be automatically resized). (VAULT_ERR_VAULT_FULL) |
-26 | Operation interrupted by user. (VAULT_ERR_INTERRUPTED_BY_USER) |
-27 | The specified file tag was not found. (VAULT_ERR_TAG_NOT_FOUND) |
-28 | The specified directory is not empty. (VAULT_ERR_DIRECTORY_NOT_EMPTY) |
-29 | The file or alternate stream was closed unexpectedly; the handle is no longer valid. (VAULT_ERR_HANDLE_CLOSED) |
-30 | Invalid file or alternate stream handle. (VAULT_ERR_INVALID_STREAM_HANDLE) |
-31 | Access denied. (VAULT_ERR_FILE_ACCESS_DENIED) |
-32 | Cannot use custom compression; no custom compression event handlers provided. (VAULT_ERR_NO_COMPRESSION_HANDLERS) |
-33 | Not implemented in this version of CBFS Vault. (VAULT_ERR_NOT_IMPLEMENTED) |
-35 | The CBFS Vault system driver has not been installed. (VAULT_ERR_DRIVER_NOT_INSTALLED) |
-37 | The specified vault cannot be opened, it was created using a newer version of CBFS Vault. (VAULT_ERR_NEW_VAULT_VERSION) |
-38 | The specified file is not a directory. (VAULT_ERR_FILE_IS_NOT_DIRECTORY) |
-39 | The specified file tag data type is not valid. (VAULT_ERR_INVALID_TAG_DATA_TYPE) |
-40 | The specified vault storage file does not exist. (VAULT_ERR_VAULT_FILE_DOES_NOT_EXIST) |
-41 | The specified vault storage file already exists. (VAULT_ERR_VAULT_FILE_ALREADY_EXISTS) |
-42 | Some callback mode event handler has returned an unidentified error. (VAULT_ERR_CALLBACK_MODE_FAILURE) |
-43 | External library could not be initialized or used. (VAULT_ERR_EXTERNAL_ERROR) |