179 lines
7.6 KiB
C
179 lines
7.6 KiB
C
#pragma once
|
|
|
|
/// \file project.h
|
|
/// \author Folling <folling@ikarus.world>
|
|
|
|
#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 Gets undefined
|
|
/// behavior.
|
|
struct IkarusProject;
|
|
|
|
/// \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.
|
|
/// \return The created project or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free. Freeing does not delete the project from the filesystem. For that, use
|
|
/// ikarus_project_delete
|
|
IKA_API IkarusProject * ikarus_project_create(char const * path, char const * name);
|
|
|
|
/// \brief Creates a project in memory.
|
|
/// \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.
|
|
/// \return The created project or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free. Freeing does not delete the project from the filesystem. For that, use
|
|
/// ikarus_project_delete
|
|
IKA_API IkarusProject * ikarus_project_create_in_memory(char const * name);
|
|
|
|
/// \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.
|
|
/// \return The opened project or null if an error occurs.
|
|
/// \remark Must be freed using ikarus_free. Freeing does not delete the project from the filesystem. For that, use
|
|
/// ikarus_project_delete
|
|
IKA_API IkarusProject * ikarus_project_open(char const * path);
|
|
|
|
/// \brief Copies a project to a new location.
|
|
/// \details The new project is not opened.
|
|
/// \param project The project to copy.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param target_path The new location of the project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must point to a valid unused path on the system.
|
|
/// \param target_name The name of the new project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \remark If successful the project connection remains intact. The previous location will still exist.
|
|
IKA_API void ikarus_project_copy(IkarusProject const * project, char const * target_path, char const * target_name);
|
|
|
|
/// \brief Deletes a project and all its associated data from the filesystem.
|
|
/// \param project The project to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \remark also frees the project.
|
|
/// \remark In-Memory projects will just be freed.
|
|
/// \remark If deletion fails, the project pointer remains intact.
|
|
IKA_API void ikarus_project_delete(IkarusProject * project);
|
|
|
|
/// \brief Gets the name of a project.
|
|
/// \param project The project to get the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The name of the project.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API char const * ikarus_project_get_name(IkarusProject const * project);
|
|
|
|
/// \brief Sets the name of a project.
|
|
/// \param project The project to set the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param new_name The new name of the project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
IKA_API void ikarus_project_set_name(IkarusProject * project, char const * new_name);
|
|
|
|
/// \brief Gets the path of a project.
|
|
/// \param project The project to get the path of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The path of the project.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API char const * ikarus_project_get_path(IkarusProject const * project);
|
|
|
|
/// \brief Moves a project to a new location.
|
|
/// \param project The project to move.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param target_path The new location of the project.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must point to a valid unused path on the system.
|
|
/// \remark If successful the project connection remains intact. The previous location will not exist anymore.
|
|
/// \remark Due to the nature of filesystems this function may not be atomic.
|
|
IKA_API void ikarus_project_move(IkarusProject * project, char const * target_path);
|
|
|
|
/// \brief Gets the error code of a project.
|
|
/// \param project The project to get the error code of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The error code of the project.
|
|
IKA_API int ikarus_project_get_error_code(IkarusProject const * project);
|
|
/// \brief Gets the error message of a project.
|
|
/// \param project The project to get the error message of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The error message of the project.
|
|
/// \remark The returned pointer is valid until the project is freed but may be altered by other operations.
|
|
/// \warning Must not be freed.
|
|
IKA_API char const * ikarus_project_get_error_message(IkarusProject const * project);
|
|
|
|
/// \brief Gets the blueprint root folder of a project.
|
|
/// \param project The project to get the blueprint root folder of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The blueprint root folder of the project or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API struct IkarusBlueprintFolder * ikarus_project_get_blueprint_root_folder(IkarusProject const * project);
|
|
|
|
/// \brief Gets the number of blueprints of a project.
|
|
/// \param project The project to get the number of blueprints of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The number of blueprints or undefined if an error occurs.
|
|
IKA_API size_t ikarus_project_get_blueprint_count(IkarusProject const * project);
|
|
|
|
/// \brief Gets the blueprints of a project.
|
|
/// \param project The project to get the blueprints of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprints_out The buffer to write the blueprints to.
|
|
/// \pre \li Must not be null.
|
|
/// \param blueprints_out_size The size of the buffer.
|
|
IKA_API void ikarus_project_get_blueprints(
|
|
IkarusProject const * project, struct IkarusBlueprint ** blueprints_out, size_t blueprints_out_size
|
|
);
|
|
|
|
/// \brief Gets the entity root folder of a project.
|
|
/// \param project The project to get the entity root folder of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The entity root folder of the project or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API struct IkarusEntityFolder * ikarus_project_get_entity_root_folder(IkarusProject const * project);
|
|
|
|
/// \brief Gets the number of entities of a project.
|
|
/// \param project The project to get the number of entities of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The number of entities or undefined if an error occurs.
|
|
IKA_API size_t ikarus_project_get_entity_count(IkarusProject const * project);
|
|
|
|
/// \brief Gets the entities of a project.
|
|
/// \param project The project to get the entities of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param entities_out The buffer to write the entities to.
|
|
/// \pre \li Must not be null.
|
|
/// \param entities_out_size The size of the buffer.
|
|
IKA_API void ikarus_project_get_entities(
|
|
IkarusProject const * project, struct IkarusEntity ** entities_out, size_t entities_out_size
|
|
);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
/// @}
|