OpenFileEx Method
Opens a new or existing file or alternate stream in the vault.
Syntax
public CUSTOM openFileEx(String fileName, int openMode, boolean readEnabled, boolean writeEnabled, boolean shareDenyRead, boolean shareDenyWrite, int encryption, String 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.
Please note that files and alternate streams cannot be created or written to if the vault itself 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:
| CBFSSTORAGE_FOM_CREATE_NEW | 0 | Creates a new file or alternate stream if possible, failing if one already exists. |
| CBFSSTORAGE_FOM_CREATE_ALWAYS | 1 | Creates a new file or stream, overwriting an existing one if necessary. |
| CBFSSTORAGE_FOM_OPEN_EXISTING | 2 | Opens a file or stream if it exists; fails otherwise. |
| CBFSSTORAGE_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 true.)
The ShareDenyRead and ShareDenyWrite parameters specify whether other accessors may read and/or write the specified file or alternate stream simultaneously. To prevent simultaneous read and/or write access, pass true; to allow it, pass false.
The Encryption parameter specifies the encryption mode to use when creating a file or alternate stream. Valid values are:
| CBFSSTORAGE_EM_NONE | 0x0 | Don't use encryption. |
| CBFSSTORAGE_EM_DEFAULT | 0x1 | Use default encryption (CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA256). |
| CBFSSTORAGE_EM_XTS_AES256_PBKDF2_HMAC_SHA256 | 0x2 | Use AES256 encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash. |
| CBFSSTORAGE_EM_CUSTOM256_PBKDF2_HMAC_SHA256 | 0x3 | Use event-based custom 256-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
256-bit (32-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM512_PBKDF2_HMAC_SHA256 | 0x4 | Use event-based custom 512-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
512-bit (64-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM1024_PBKDF2_HMAC_SHA256 | 0x5 | Use event-based custom 1024-bit encryption with PBKDF2 key derivation based on a HMAC_SHA256 key hash.
1024-bit (128-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM256_CUSTOM_KEY_DERIVE | 0x23 | Use event-based custom 256-bit encryption with custom key derivation.
256-bit (32-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM512_CUSTOM_KEY_DERIVE | 0x24 | Use event-based custom 512-bit encryption with custom key derivation.
512-bit (64-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM1024_CUSTOM_KEY_DERIVE | 0x25 | Use event-based custom 1024-bit encryption with custom key derivation.
1024-bit (128-byte) block size. |
| CBFSSTORAGE_EM_CUSTOM256_DIRECT_KEY | 0x43 | Use event-based custom 256-bit encryption with no key derivation.
256-bit (32-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
| CBFSSTORAGE_EM_CUSTOM512_DIRECT_KEY | 0x44 | Use event-based custom 512-bit encryption with no key derivation.
512-bit (64-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
| CBFSSTORAGE_EM_CUSTOM1024_DIRECT_KEY | 0x45 | Use event-based custom 1024-bit encryption with no key derivation.
1024-bit (128-byte) block size. Useful for cases where the password is an identifier for an external key and should not be used for key derivation. |
| CBFSSTORAGE_EM_UNKNOWN | 0xFF | Unidentified or unknown encryption. |
Applications that use custom encryption must implement at least the DataDecrypt and DataEncrypt events; and certain custom encryption modes may also 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 CBFSSTORAGE_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:
| CBFSSTORAGE_CM_NONE | 0 | Don't use compression. |
| CBFSSTORAGE_CM_DEFAULT | 1 | Use default compression (zlib). |
| CBFSSTORAGE_CM_CUSTOM | 2 | Use event-based custom compression.
Compression level is not used. |
| CBFSSTORAGE_CM_ZLIB | 3 | Use zlib compression.
Valid compression levels are 1-9. |
| CBFSSTORAGE_CM_RLE | 4 | Use RLE compression.
Compression level is not used. |
Applications that use custom compression must 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 RLE). Larger values allow for more efficient compression; however, since a block must be decompressed (and, for writes, recompressed) anytime its data is accessed, larger values can also cause excessive slowdown, especially for random access.
Note: This method can only be called when Active is true, and cannot be called within events.