Mercurial > sci
diff scid/db.h @ 33:1d0ddf9e6efd
misc: general documentation
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 04 Aug 2022 16:47:10 +0200 |
parents | 081e1c258e64 |
children | 00b9af607524 |
line wrap: on
line diff
--- a/scid/db.h Thu Aug 04 14:59:33 2022 +0200 +++ b/scid/db.h Thu Aug 04 16:47:10 2022 +0200 @@ -19,52 +19,175 @@ #ifndef SCI_DB_H #define SCI_DB_H +/** + * \file db.h + * \brief Database access. + * + * This module access the SQLite database. + * + * A global variable is used to access the database, the function \ref db_open + * must be called before any other functions. + * + * Many of the function that insert or update model will also update the JSON + * object to fill the generated row id if any. + * + * This module logs message with tag `db`. + */ + #include <stdint.h> #include <jansson.h> -int -db_open(const char *); - +/** + * Open database specified by path. + * + * \pre path != NULL + * \param path path to the database + */ int -db_job_add(json_t *); +db_open(const char *path); + +/** + * Add a new job. + * + * \pre job != NULL + * \param job the job to add + * \return 0 on success or -1 on error + */ +int +db_job_add(json_t *job); +/** + * Get a list of jobs to perform for this worker. + * + * The returned list will only contain jobs to perform if their date are + * greater or equal to the worker creation date to avoid running jobs that are + * older and probably too numerous. + * + * \pre worker != NULL + * \param worker the worker name + * \return the JSON model or NULL on failure + */ json_t * -db_job_todo(const char *); +db_job_todo(const char *worker); +/** + * Return the whole list of jobs for the given project. + * + * \pre project != NULL + * \param project the project name + * \return the JSON model or NULL on failure + */ json_t * -db_job_list(const char *); +db_job_list(const char *project); +/** + * Add a new job result. + * + * \pre result != NULL + * \param result the job result to add + * \return 0 on success or -1 on error + */ int -db_jobresult_add(json_t *); +db_jobresult_add(json_t *result); +/** + * Get a list of job results by job id. + * + * This will contain every job done by all workers for this job id. + * + * \param job_id the job id + * \return the JSON model or NULL on failure + */ json_t * -db_jobresult_list_by_job(intmax_t); +db_jobresult_list_by_job(intmax_t job_id); +/** + * Get a list of job results for this job id but only the more recent per each + * worker. + * + * This function is handy if you want to retrieve all last jobs realized by all + * workers. + * + * \param job_id the job id + * \return the JSON model or NULL on failure + */ json_t * db_jobresult_list_by_job_group(intmax_t); +/** + * Get a list of job results realized by this worker. + * + * \pre worker != NULL + * \param worker the worker name + * \return the JSON model or NULL on failure + */ json_t * db_jobresult_list_by_worker(const char *); +/** + * Add or update the given project. + * + * In case of update, all fields must be present anyway. + * + * \pre project != NULL + * \param project the project to update + * \return 0 on success or -1 on error + */ int -db_project_save(json_t *); +db_project_save(json_t *project); +/** + * Get a list of all projects. + * + * \return the JSON model or NULL on failure + */ json_t * db_project_list(void); +/** + * Find a project by name. + * + * \pre name != NULL + * \param name the project name + * \return the JSON model or NULL on failure + */ json_t * -db_project_find(const char *); +db_project_find(const char *name); +/** + * Add or update the given worker. + * + * In case of update, all fields must be present anyway. + * + * \pre worker != NULL + * \param worker the worker to update + * \return 0 on success or -1 on error + */ int -db_worker_save(json_t *); +db_worker_save(json_t *worker); +/** + * Get a list of all workers. + * + * \return the JSON model or NULL on failure + */ json_t * db_worker_list(void); +/** + * Find a worker by name. + * + * \pre name != NULL + * \param name the worker name + * \return the JSON model or NULL on failure + */ json_t * db_worker_find(const char *); +/** + * Close database and associated resources. + */ void db_finish(void);