Opens a new or existing vault.
int OpenVault(int iOpenMode);
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 fails with an error.
Note: This method cannot be called when Active is true, and cannot be called within events.
This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)