/*
 * db.h -- scid database access
 *
 * Copyright (c) 2021-2022 David Demelier <markand@malikania.fr>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

#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>

/**
 * Maximum property value.
 */
#define DB_PROP_VALUE_MAX 256

/**
 * Open database specified by path.
 *
 * \pre path != NULL
 * \param path path to the database
 */
int
db_open(const char *path);

/**
 * Reinitialize the API key in database and return it.
 *
 * \pre out != NULL
 * \param out the destination key
 * \param outsz the maximum size to write
 * \return 0 on success or -1 on error
 */
int
db_key_init(char *out, size_t outsz);

/**
 * Fetch the key from the database.
 *
 * \pre out != NULL
 * \param out the destination key
 * \param outsz the maximum size to write
 * \return 0 if not found, 1 if found or -1 on error
 */
int
db_key_get(char *out, size_t outsz);

/**
 * 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 *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 *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 *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 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 job_id);

/**
 * 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 *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 *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 *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);

#endif /* !SCI_DB_H */