cubos::core::data::Archive class
#include <core/data/fs/archive.hpp>

Interface for a bridge between the Cubos virtual file system and the real world.

By real world, we mean something such as a file on the OS file system or a network connection. The archive is responsible for creating and destroying files, supplying streams for reading and writing, and retrieving information about existing files.

Each file in an archive is represented by a unique integer identifier. The identifier 0 is reserved for errors, and the identifier 1 is reserved for the root file of the archive.

The root file may be a directory or a regular file. If its a directory, when mounted, the archive will take the form of a directory, with the root file being placed on the mount point. If the root file is a regular file, then the mount point will be a regular file.

This class is not meant to be thread-safe - it is the responsibility of the File class to ensure that the same file is not accessed or modified by multiple threads at the same time.

Implementations should crash when called with invalid arguments - since they're only called by File, its okay to assume the arguments are correct (please do use asserts though).

Derived classes

class EmbeddedArchive: Archive implementation which reads data embedded in the application. Meant to be used with the quadrados embed tool.
class StandardArchive: Archive implementation which reads and writes from/into the OS file system using the standard library.

Public functions

auto create(std::size_t parent, std::string_view name, bool directory = false) -> std::size_t pure virtual: Creates a new file in the archive.
auto destroy(std::size_t id) -> bool pure virtual: Destroys a regular file or empty directory in the archive.
auto name(std::size_t id) const -> std::string pure virtual: Gets the name of the file with the given id.
auto directory(std::size_t id) const -> bool pure virtual: Checks whether the file with the given id is a directory.
auto readOnly() const -> bool pure virtual: Checks whether the archive is read-only.
auto parent(std::size_t id) const -> std::size_t pure virtual: Gets the identifier of the parent file of the file with the given id.
auto sibling(std::size_t id) const -> std::size_t pure virtual: Gets the identifier of the sibling of the file with the given id.
auto child(std::size_t id) const -> std::size_t pure virtual: Gets the identifier of the first child of the file with the given id.
auto open(std::size_t id, File::Handle handle, File::OpenMode mode) -> std::unique_ptr<memory::Stream> pure virtual: Opens a file in the archive.

Function documentation

std::size_t cubos::core::data::Archive::create(std::size_t parent, std::string_view name, bool directory = false) pure virtual

Creates a new file in the archive.

Parameters
parent	Parent directory of the new file.
name	Name of the new file.
directory	Whether the new file is a directory or not.
Returns	Identifier of the file, or 0 if the file could not be created.

The first child of the parent will have its sibling set to the new file and then be replaced by the new file.

bool cubos::core::data::Archive::destroy(std::size_t id) pure virtual

Destroys a regular file or empty directory in the archive.

Parameters
id	Identifier of the file.
Returns	Whether the file was destroyed successfully.

Will be replaced in the tree by its sibling.

std::string cubos::core::data::Archive::name(std::size_t id) const pure virtual

Gets the name of the file with the given id.

Parameters
id	Identifier of the file.
Returns	Name of the file.

bool cubos::core::data::Archive::directory(std::size_t id) const pure virtual

Checks whether the file with the given id is a directory.

Parameters
id	Identifier of the file.
Returns	Whether the file is a directory or not.

bool cubos::core::data::Archive::readOnly() const pure virtual

Checks whether the archive is read-only.

Returns	Whether the archive is read-only.

std::size_t cubos::core::data::Archive::parent(std::size_t id) const pure virtual

Gets the identifier of the parent file of the file with the given id.

Parameters
id	Identifier of the file.
Returns	Identifier of the parent file, or 0 if the file is the root file.

std::size_t cubos::core::data::Archive::sibling(std::size_t id) const pure virtual

Gets the identifier of the sibling of the file with the given id.

Parameters
id	Identifier of the file.
Returns	Identifier of the sibling, or 0 if there are no more files in the parent.

std::size_t cubos::core::data::Archive::child(std::size_t id) const pure virtual

Gets the identifier of the first child of the file with the given id.

Parameters
id	Identifier of the file.
Returns	Identifier of the first child, or 0 if the file is not a directory or is empty.

std::unique_ptr<memory::Stream> cubos::core::data::Archive::open(std::size_t id, File::Handle handle, File::OpenMode mode) pure virtual

Opens a file in the archive.

Parameters
id	Identifier of the file.
handle	Handle to the file.
mode	Mode to open the file in.
Returns	File stream, or nullptr if the file could not be opened.

Although a bit hacky, the handle parameter is used to keep a reference to the respective File alive, preventing the file from being destroyed while the stream is open.