OpenFile Method

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

Syntax

CBFSStorageStream* OpenFile(const QString& qsFileName, int iOpenMode, bool bReadEnabled, bool bWriteEnabled, const QString& qsPassword);

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_NEW0Creates a new file or alternate stream if possible, failing if one already exists.

CBFSSTORAGE_FOM_CREATE_ALWAYS1Creates a new file or stream, overwriting an existing one if necessary.

CBFSSTORAGE_FOM_OPEN_EXISTING2Opens a file or stream if it exists; fails otherwise.

CBFSSTORAGE_FOM_OPEN_ALWAYS3Opens 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 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 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 DefaultFilePassword property instead (if necessary).

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

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

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

Error Handling

This method returns a Stream; after it returns, call the GetLastErrorCode() method to obtain its 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.

Copyright (c) 2021 Callback Technologies, Inc. - All rights reserved.
CBFS Storage 2020 Qt Edition - Version 20.0 [Build 8031]