206 lines
6.6 KiB
C++
206 lines
6.6 KiB
C++
#pragma once
|
|
|
|
/// \file project.h
|
|
/// \author Folling <mail@folling.io>
|
|
|
|
#include <cstdint>
|
|
|
|
#include <ikarus/errors.h>
|
|
#include <ikarus/macros.h>
|
|
#include <ikarus/stdtypes.h>
|
|
|
|
/// \defgroup projects Projects
|
|
/// \brief Projects are the persistence mechanism of Ikarus. Each project contains a set of objects.
|
|
/// \details Projects are stored on the filesystem. Each project has a name.
|
|
/// @{
|
|
|
|
IKARUS_BEGIN_HEADER
|
|
|
|
/// \brief An Ikarus project.
|
|
/// \details A project may only be open once at a time.
|
|
/// Opening a project from two different locations results in undefined
|
|
/// behavior.
|
|
struct IkarusProject;
|
|
|
|
/// \brief Flags for creating a project.
|
|
enum IkarusProjectCreateFlags {
|
|
/// \brief No flags.
|
|
IkarusProjectCreateFlags_None = 0,
|
|
/// \brief Allow overwriting existing files.
|
|
IkarusProjectCreateFlags_AllowOverwrite = 1 << 0,
|
|
};
|
|
|
|
/// \brief Creates a persisted project on the filesystem.
|
|
/// \param path The path to the project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must point to a valid unused path on the system.
|
|
/// \param name The name of the project. Must neither be null nor empty.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for creating the project.
|
|
/// \param error_out \see errors.h
|
|
/// \return The created project or null if an error occurs.
|
|
/// \remark Must be closed with #ikarus_project_close.
|
|
IKA_API struct IkarusProject * ikarus_project_create(
|
|
char const * path,
|
|
char const * name,
|
|
IkarusProjectCreateFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for creating a project in memory.
|
|
enum IkarusProjectCreateInMemoryFlags {
|
|
/// \brief No flags.
|
|
IkarusProjectCreateInMemoryFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Creates a project in memory. The project is not persisted.
|
|
/// \param name The name of the project. Must neither be null nor empty.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for creating the project.
|
|
/// \param error_out \see errors.h
|
|
/// \return The created project or null if an error occurs.
|
|
/// \remark Must be closed with #ikarus_project_close.
|
|
IKA_API struct IkarusProject * ikarus_project_create_in_memory(
|
|
char const * name,
|
|
IkarusProjectCreateInMemoryFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for opening a project.
|
|
enum IkarusProjectOpenFlags {
|
|
/// \brief No flags.
|
|
IkarusProjectOpenFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Opens an existing project.
|
|
/// \param path The path to the project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must point to an existing project on the system.
|
|
/// \param flags Flags for opening the project.
|
|
/// \param error_out \see errors.h
|
|
/// \return The opened project or null if an error occurs.
|
|
/// \remark Must be closed with #ikarus_project_close.
|
|
IKA_API struct IkarusProject * ikarus_project_open(
|
|
char const * path,
|
|
IkarusProjectOpenFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for closing a project in memory.
|
|
enum IkarusProjectCloseFlags {
|
|
/// \brief No flags.
|
|
IkarusProjectCloseFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Closes a project. This function must be called to free resources.
|
|
/// \param project The project to close.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be open.
|
|
/// \param flags Flags for closing the project.
|
|
/// \param error_out \see errors.h
|
|
/// \remark The project must not be used after closing.
|
|
/// \remark Does not delete the project from the filesystem.
|
|
/// \remark Mutually exclusive with #ikarus_project_delete.
|
|
IKA_API void ikarus_project_close(
|
|
struct IkarusProject * project,
|
|
IkarusProjectCloseFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for deleting a project.
|
|
enum IkarusProjectDeleteFlags {
|
|
/// \brief No flags.
|
|
IkarusProjectDeleteFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Deletes a project from the filesystem.
|
|
/// \param project The project to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param flags Flags for deleting the project.
|
|
/// \param error_out \see errors.h
|
|
/// \remark The project must not be used after deletion.
|
|
/// \remark Mutually exclusive with #ikarus_project_close.
|
|
IKA_API void ikarus_project_delete(
|
|
struct IkarusProject * project,
|
|
IkarusProjectDeleteFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the name of a project.
|
|
/// \param project The project to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \returns The name of the project or null if an error occurs.
|
|
IKA_API char const * ikarus_project_get_name(
|
|
struct IkarusProject const * project,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the path of a project.
|
|
/// \param project The project to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \returns The path of the project or null if an error occurs.
|
|
IKA_API char const * ikarus_project_get_path(
|
|
struct IkarusProject const * project,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets all entities in a project.
|
|
/// \param project The project from which to get the entities.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of entities in the returned array
|
|
/// or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \returns An array of entities or null if an error occurs.
|
|
IKA_API struct IkarusEntity ** ikarus_project_get_entities(
|
|
struct IkarusProject const * project,
|
|
size_t * size_out,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets how many entities in a project there are.
|
|
/// \param project The project from which to get the count.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The count or 0 if an error occurs.
|
|
IKA_API size_t ikarus_project_get_entities_count(
|
|
IkarusProject const * project,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets all blueprints from a project.
|
|
/// \param project The project from which to get the blueprints.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of blueprints in the returned array
|
|
/// or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \return An array of blueprints or null if an error occurs.
|
|
IKA_API struct IkarusBlueprint ** ikarus_project_get_blueprints(
|
|
struct IkarusProject const * project,
|
|
size_t * size_out,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets how many blueprints in a project there are.
|
|
/// \param project The project from which to get the count.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The count or 0 if an error occurs.
|
|
IKA_API size_t ikarus_project_get_blueprints_count(
|
|
IkarusProject const * project,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
/// @}
|