Mercurial > sci

comparison scid/db.h @ 33:1d0ddf9e6efd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: general documentation
author David Demelier <markand@malikania.fr>
date Thu, 04 Aug 2022 16:47:10 +0200
parents 081e1c258e64
children 00b9af607524
comparison
equal deleted inserted replaced
32:081e1c258e64 33:1d0ddf9e6efd
17 */ 17 */
18 18
19 #ifndef SCI_DB_H 19 #ifndef SCI_DB_H
20 #define SCI_DB_H 20 #define SCI_DB_H
21 21
22 /**
23 * \file db.h
24 * \brief Database access.
25 *
26 * This module access the SQLite database.
27 *
28 * A global variable is used to access the database, the function \ref db_open
29 * must be called before any other functions.
30 *
31 * Many of the function that insert or update model will also update the JSON
32 * object to fill the generated row id if any.
33 *
34 * This module logs message with tag `db`.
35 */
36
22 #include <stdint.h> 37 #include <stdint.h>
23 38
24 #include <jansson.h> 39 #include <jansson.h>
25 40
41 /**
42 * Open database specified by path.
43 *
44 * \pre path != NULL
45 * \param path path to the database
46 */
26 int 47 int
27 db_open(const char *); 48 db_open(const char *path);
28 49
50 /**
51 * Add a new job.
52 *
53 * \pre job != NULL
54 * \param job the job to add
55 * \return 0 on success or -1 on error
56 */
29 int 57 int
30 db_job_add(json_t *); 58 db_job_add(json_t *job);
31 59
60 /**
61 * Get a list of jobs to perform for this worker.
62 *
63 * The returned list will only contain jobs to perform if their date are
64 * greater or equal to the worker creation date to avoid running jobs that are
65 * older and probably too numerous.
66 *
67 * \pre worker != NULL
68 * \param worker the worker name
69 * \return the JSON model or NULL on failure
70 */
32 json_t * 71 json_t *
33 db_job_todo(const char *); 72 db_job_todo(const char *worker);
34 73
74 /**
75 * Return the whole list of jobs for the given project.
76 *
77 * \pre project != NULL
78 * \param project the project name
79 * \return the JSON model or NULL on failure
80 */
35 json_t * 81 json_t *
36 db_job_list(const char *); 82 db_job_list(const char *project);
37 83
84 /**
85 * Add a new job result.
86 *
87 * \pre result != NULL
88 * \param result the job result to add
89 * \return 0 on success or -1 on error
90 */
38 int 91 int
39 db_jobresult_add(json_t *); 92 db_jobresult_add(json_t *result);
40 93
94 /**
95 * Get a list of job results by job id.
96 *
97 * This will contain every job done by all workers for this job id.
98 *
99 * \param job_id the job id
100 * \return the JSON model or NULL on failure
101 */
41 json_t * 102 json_t *
42 db_jobresult_list_by_job(intmax_t); 103 db_jobresult_list_by_job(intmax_t job_id);
43 104
105 /**
106 * Get a list of job results for this job id but only the more recent per each
107 * worker.
108 *
109 * This function is handy if you want to retrieve all last jobs realized by all
110 * workers.
111 *
112 * \param job_id the job id
113 * \return the JSON model or NULL on failure
114 */
44 json_t * 115 json_t *
45 db_jobresult_list_by_job_group(intmax_t); 116 db_jobresult_list_by_job_group(intmax_t);
46 117
118 /**
119 * Get a list of job results realized by this worker.
120 *
121 * \pre worker != NULL
122 * \param worker the worker name
123 * \return the JSON model or NULL on failure
124 */
47 json_t * 125 json_t *
48 db_jobresult_list_by_worker(const char *); 126 db_jobresult_list_by_worker(const char *);
49 127
128 /**
129 * Add or update the given project.
130 *
131 * In case of update, all fields must be present anyway.
132 *
133 * \pre project != NULL
134 * \param project the project to update
135 * \return 0 on success or -1 on error
136 */
50 int 137 int
51 db_project_save(json_t *); 138 db_project_save(json_t *project);
52 139
140 /**
141 * Get a list of all projects.
142 *
143 * \return the JSON model or NULL on failure
144 */
53 json_t * 145 json_t *
54 db_project_list(void); 146 db_project_list(void);
55 147
148 /**
149 * Find a project by name.
150 *
151 * \pre name != NULL
152 * \param name the project name
153 * \return the JSON model or NULL on failure
154 */
56 json_t * 155 json_t *
57 db_project_find(const char *); 156 db_project_find(const char *name);
58 157
158 /**
159 * Add or update the given worker.
160 *
161 * In case of update, all fields must be present anyway.
162 *
163 * \pre worker != NULL
164 * \param worker the worker to update
165 * \return 0 on success or -1 on error
166 */
59 int 167 int
60 db_worker_save(json_t *); 168 db_worker_save(json_t *worker);
61 169
170 /**
171 * Get a list of all workers.
172 *
173 * \return the JSON model or NULL on failure
174 */
62 json_t * 175 json_t *
63 db_worker_list(void); 176 db_worker_list(void);
64 177
178 /**
179 * Find a worker by name.
180 *
181 * \pre name != NULL
182 * \param name the worker name
183 * \return the JSON model or NULL on failure
184 */
65 json_t * 185 json_t *
66 db_worker_find(const char *); 186 db_worker_find(const char *);
67 187
188 /**
189 * Close database and associated resources.
190 */
68 void 191 void
69 db_finish(void); 192 db_finish(void);
70 193
71 #endif /* !SCI_DB_H */ 194 #endif /* !SCI_DB_H */