open_file Method

Opens a new or existing file or alternate stream in the vault.

Syntax

def open_file(file_name: str, open_mode: int, read_enabled: bool, write_enabled: bool, password: str) -> CBFSStorageStream: ...

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 read_only 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 read_only is True.)

The Password parameter works as follows:

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

If the value passed for Password is null or empty string, the class will use the current value of the default_file_password property instead (if necessary).

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

• ShareDenyRead and ShareDenyWrite use True.
• Encryption uses the current default_file_encryption value.
• Compression and CompressionLevel use the current default_file_compression and DefaultFileCompressionLevel values, respectively.
• PagesPerBlock uses 16.

Please refer to the open_file_ex method's documentation for more information.

Note: This method can only be called when active is True, and cannot be called within events.