Ikarus/libikarus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

change error system & function signatures

Browse source 
Signed-off-by: Folling <mail@folling.io>
This commit is contained in:
Folling 2024-01-02 15:14:39 +01:00 • committed by Folling
parent 1367373819
commit e1bf97704a
No known key found for this signature in database
28 changed files with 633 additions and 651 deletions
Download patch file Download diff file Expand all files Collapse all files

96
include/ikarus/persistence/project.h
View file

@ -25,28 +25,31 @@ struct IkarusProject;
/// \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 error_out \see errors.h
/// \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);
IKA_API IkarusProject * ikarus_project_create(char const * path, char const * name, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \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);
IKA_API IkarusProject * ikarus_project_create_in_memory(char const * name, IkarusErrorData * error_out);
/// \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 error_out \see errors.h
/// \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);
IKA_API IkarusProject * ikarus_project_open(char const * path, IkarusErrorData * error_out);
/// \brief Copies a project to a new location.
/// \details The new project is not opened.
@ -59,25 +62,29 @@ IKA_API IkarusProject * ikarus_project_open(char const * path);
/// \param target_name The name of the new project.
/// \pre \li Must not be null.
/// \pre \li Must not be empty.
/// \param error_out \see errors.h
/// \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);
IKA_API void
ikarus_project_copy(IkarusProject const * project, char const * target_path, char const * target_name, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \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);
IKA_API void ikarus_project_delete(IkarusProject * project, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \return The name of the project.
/// \remark Must be freed using #ikarus_free.
IKA_API char const * ikarus_project_get_name(IkarusProject const * project);
IKA_API char const * ikarus_project_get_name(IkarusProject const * project, IkarusErrorData * error_out);
/// \brief Sets the name of a project.
/// \param project The project to set the name of.
@ -86,15 +93,17 @@ IKA_API char const * ikarus_project_get_name(IkarusProject const * project);
/// \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);
/// \param error_out \see errors.h
IKA_API void ikarus_project_set_name(IkarusProject * project, char const * new_name, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \return The path of the project.
/// \remark Must be freed using #ikarus_free.
IKA_API char const * ikarus_project_get_path(IkarusProject const * project);
IKA_API char const * ikarus_project_get_path(IkarusProject const * project, IkarusErrorData * error_out);
/// \brief Moves a project to a new location.
/// \param project The project to move.
@ -103,39 +112,19 @@ IKA_API char const * ikarus_project_get_path(IkarusProject const * project);
/// \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 error_out \see errors.h
/// \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);
IKA_API void ikarus_project_move(IkarusProject * project, char const * target_path, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \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);
IKA_API struct IkarusBlueprintFolder * ikarus_project_get_blueprint_root_folder(IkarusProject const * project, IkarusErrorData * error_out);
/// \brief Gets the blueprints of a project.
/// \param project The project to get the blueprints of.
@ -144,23 +133,30 @@ IKA_API size_t ikarus_project_get_blueprint_count(IkarusProject const * project)
/// \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);
/// \param error_out \see errors.h
IKA_API void ikarus_project_get_blueprints(
IkarusProject const * project,
struct IkarusBlueprint ** blueprints_out,
size_t blueprints_out_size,
IkarusErrorData * error_out
);
/// \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.
/// \param error_out \see errors.h
/// \return The number of blueprints or undefined if an error occurs.
IKA_API size_t ikarus_project_get_blueprint_count(IkarusProject const * project, IkarusErrorData * error_out);
/// \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.
/// \param error_out \see errors.h
/// \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);
IKA_API struct IkarusEntityFolder * ikarus_project_get_entity_root_folder(IkarusProject const * project, IkarusErrorData * error_out);
/// \brief Gets the entities of a project.
/// \param project The project to get the entities of.
@ -169,7 +165,21 @@ IKA_API size_t ikarus_project_get_entity_count(IkarusProject const * project);
/// \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);
/// \param error_out \see errors.h
IKA_API void ikarus_project_get_entities(
IkarusProject const * project,
struct IkarusEntity ** entities_out,
size_t entities_out_size,
IkarusErrorData * error_out
);
/// \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.
/// \param error_out \see errors.h
/// \return The number of entities or undefined if an error occurs.
IKA_API size_t ikarus_project_get_entity_count(IkarusProject const * project, IkarusErrorData * error_out);
IKARUS_END_HEADER