# cee::vtfx::File

class `File` : public RefCountedObject

  A VTFx file.

  The class creates or opens a VTFx file for adding databases and cases.

  A VTFx file is a collection of databases and cases. Each database contains blocks for storing data. A block has a block type and an id. The id must be unique amongst all blocks of the same type within a database. The order of blocks in a database is arbitrary, so one can write blocks to a database at any time. However, the user has to take special care in using block types correctly and assigning block ids correctly, since the library does not validate these.

  Cases reference databases and define a visualization of database contents using so-called case properties. Moreover, cases store auxiliary data such as a vendor logo, a visualization snapshot (if available), and HTML text to describe a case, for instance with further information on the database and the visualization.

  The minimal contents of a VTFx file are :

  - One database with
    - One node block (NodeBlock)
    - One element block (ElementBlock), referencing the node block
    - One geometry block (GeometryBlock), referencing the element block
    - One geometry info block (GeometryInfoBlock)
    - One state info block (StateInfoBlock), defining a single state (state id 1)
  - One case with
    - A reference to the database

  Public Functions

  `File`()

    Constructs an empty file object.

  virtual `~File`()
  bool `open`(const Str &filename)

    Opens an existing file.

    Returns true if the file was opened successfully.

  bool `create`(const Str &filename, const FileSettings &fileSettings)

    Creates a file with the given file name and file settings and prepares it for writing.

    An existing file with the same file name will be overwritten without notice.

    Returns false if an error occurred. See the log for more information on the error.

  bool `openForAppend`(const Str &filename)

    Opens a VTFx file with the given file name and file settings for appending databases and cases.

    New cases may reference existing databases within the VTFx file.

    The user has to take care that appended databases and cases do not clash with existing ones, i.e. case and database ids need to be unique.

    Returns false if an error occurred. See the log for more information on the error.

  bool `close`()

    Closes the file.

    Final writing of data is done by this method, thus it is important to check the return value.

    Note: The destructor File::~File() does not close the file.

    Returns false if the file could not be closed properly. See the log for more information on the error.

  size_t `userTextFileCount`() const

    Returns the number of user created text files in the VTFx file.

  Str `userTextFileName`(size_t textFileIndex) const

    Returns the name of the user text file with index textFileIndex.

  Str `userTextFileContent`(size_t textFileIndex) const

    Returns the content of the user text file with index textFileIndex.

  bool `addUserTextFile`(const Str &filename, const Str &content)

    Adds a the string in content as a file into the VTFx archive.

    The name of the file is filename. The file will be stored in the “UserData” VTFx directory.

    Previously added files with the same name will be overwritten.

    Returns false if an error occurred.

  size_t `databaseCount`() const

    Returns the number of databases in the VTFx file.

  int `unusedDatabaseId`() const

    Returns an available database id to create a new database.

    Returns -1 if no file was opened for writing or appending.

  Database *`database`(size_t databaseIndex)

    Returns the database at the given index.

    Returns NULL if the index is not valid.

  size_t `fileCaseCount`() const

    Returns the number of cases in the VTFx file.

  int `unusedFileCaseId`() const

    Returns an available case id to create a new case.

    Returns -1 if no file was opened for writing or appending.

  const Case *`fileCase`(size_t caseIndex) const

    Returns the case at the given index.

    Returns NULL if the case index is not valid.

  Case *`fileCase`(size_t caseIndex)

    Returns the case at the given index.

    Returns NULL if the case index is not valid.

  const FileSettings *`settings`() const

    Returns the file settings for this file.

  VTFxAccess *`internal_access`()

  Public Static Functions

  static bool `isVTFxFile`(const Str &filename)

    Returns the content of the user text file with index textFileIndex.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...