OpenVault Method
Opens a new or existing vault.
Syntax
cbdrive.openVault(openMode, [callback])
Callback
The 'callback' parameter specifies a function which will be called when the operation completes (or an error is encountered). If the 'callback' parameter is not specified, then the method will block and will not return until the operation completes (or an error is encountered).
The callback for this method is defined as:
function(err){ }
'err' is the error that occurred. If there was no error, then 'err' is 'null'.
'err' has 2 properties which hold detailed information:
err.code err.message
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:
| CBFSSTORAGE_OM_CREATE_NEW | 0 | Creates a new vault if possible, failing if one already exists. |
| CBFSSTORAGE_OM_CREATE_ALWAYS | 1 | Creates a new vault, overwriting an existing one if necessary. |
| CBFSSTORAGE_OM_OPEN_EXISTING | 2 | Opens a vault if it exists; fails otherwise. |
| CBFSSTORAGE_OM_OPEN_ALWAYS | 3 | Opens a vault if it exists; creates a new one otherwise. |
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 itself controls where the vault is located and how it is accessed via 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
- UseJournaling 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 throws an exception.
For the CBDrive class on Windows, an attempt to open a vault file that is compressed or encrypted using NTFS capabilities will lead to an error being reported by this method. It is necessary to not use NTFS compression or encryption on the file in order to avoid a system-wide deadlock in Windows internals.
Note: This method cannot be called when Active is true, and cannot be called within events.