Mercurial > sci
comparison 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 |
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 */ |