/*
 * lls C API - query and change the task / account database from C, or from
 * Python through ctypes / cffi (see python/lls.py).
 *
 * Model
 *   - lls_open() loads the database file into memory (or starts empty). Changes
 *     stay in memory until lls_save(); lls_is_dirty() tells whether there is
 *     anything to save. Nothing is saved automatically.
 *   - Every function that can fail returns LLS_OK (0) or an error code, and the
 *     message is available from lls_last_error(). Changes also leave human
 *     readable notes in lls_last_messages() (what the interactive prompt prints,
 *     e.g. "Account 'A' is back in use: its finished wait was cleared.").
 *   - Names are case-insensitive but keep their original spelling.
 *   - Statuses are the text you would type at the prompt: "prompt", "testing",
 *     "uploading", "frozen", "done", "limit-reset", "wait 4:30pm", "wait 16:30"
 *     or just "wait" (only while the task's account is already waiting).
 *   - A wait belongs to the account: setting a task to "wait <time>" sets its
 *     account's wait, and the account's Prompt / Testing tasks then show Wait
 *     until that time and Limit reset after it (see the README).
 *   - Times are Unix seconds (UTC); clock-time text like "4:30pm" is read in the
 *     local time zone, and a time that has passed today means tomorrow.
 *
 * Threads: a lls_db must not be used from several threads at once.
 * Strings: every const char* returned by the library is owned by it. Those in a
 * list stay valid until the list is freed; lls_last_error / lls_last_messages /
 * lls_path stay valid until the next call on the same lls_db.
 */
#ifndef LLS_API_H
#define LLS_API_H

#include <stddef.h>
#include <stdint.h>

#if defined(_WIN32)
#  ifdef LLS_BUILDING_API
#    define LLS_API __declspec(dllexport)
#  else
#    define LLS_API __declspec(dllimport)
#  endif
#else
#  define LLS_API __attribute__((visibility("default")))
#endif

#ifdef __cplusplus
extern "C" {
#endif

#define LLS_API_VERSION 1

/* ---- Result codes --------------------------------------------------------- */
#define LLS_OK 0
#define LLS_E_INVALID 1    /* bad argument: NULL, invalid name, unknown status or time */
#define LLS_E_NOT_FOUND 2  /* no such task or account */
#define LLS_E_EXISTS 3     /* a task or account with that name already exists */
#define LLS_E_DATABASE 4   /* SQLite or file problem */
#define LLS_E_INTERNAL 5

/* ---- Status kinds (lls_task_info.status, .stored_status) ------------------ */
#define LLS_STATUS_PROMPT 0       /* free to accept prompts */
#define LLS_STATUS_LIMIT_RESET 1  /* the account's wait is over */
#define LLS_STATUS_TESTING 2
#define LLS_STATUS_WAIT 3         /* the account's wait is running */
#define LLS_STATUS_UPLOADING 4
#define LLS_STATUS_FROZEN 5
#define LLS_STATUS_DONE 6

/* ---- Account levels (lls_account_info.level), most taken first ------------ */
#define LLS_LEVEL_BUSY 0   /* Testing, Limit reset or Wait task, or a wait nothing else shows */
#define LLS_LEVEL_TAKEN 1  /* has a Prompt task */
#define LLS_LEVEL_FREE 2   /* only Uploading / Frozen / Done tasks, or none */

/* ---- Account wait states (lls_account_info.wait_state) -------------------- */
#define LLS_WAIT_NONE 0
#define LLS_WAIT_WAITING 1      /* wait_until is in the future */
#define LLS_WAIT_LIMIT_RESET 2  /* wait_until has passed; stays until cleared */

typedef struct lls_db lls_db;
typedef struct lls_task_list lls_task_list;
typedef struct lls_account_list lls_account_list;

/* A task as the user sees it. */
typedef struct lls_task_info {
    const char* name;
    const char* account;       /* NULL when the task has no account */
    int status;                /* LLS_STATUS_*, as shown (Wait / Limit reset come from the account) */
    const char* status_label;  /* "Prompt", "Limit reset", "Wait 16:30", ... */
    int stored_status;         /* LLS_STATUS_*, what is saved underneath */
    int64_t until;             /* for Wait / Limit reset: when the wait ends (ended); else 0 */
    const char* notes;         /* the full text, "" if none (any length) */
    int notes_lines;           /* number of lines in the notes */
} lls_task_info;

/* An account with its computed state. */
typedef struct lls_account_info {
    const char* name;
    int level;                 /* LLS_LEVEL_* */
    const char* level_label;   /* "Busy", "Taken", "Free" */
    int wait_state;            /* LLS_WAIT_* */
    int64_t wait_until;        /* when the wait ends (ended); 0 if none */
    int wait_listed;           /* 1 if the wait is not shown by any task (it still makes the account Busy) */
    int task_count;
    const char* const* tasks;  /* the tasks at the account's level (a Free account: its Uploading/Frozen/Done ones) */
} lls_account_info;

/* ---- Library -------------------------------------------------------------- */

LLS_API int lls_api_version(void);  /* compare with LLS_API_VERSION */

/* Name of a status kind: "prompt", "limit-reset", "testing", "wait", ... (NULL if unknown). */
LLS_API const char* lls_status_name(int status);

/* Parses a clock time as `acc wait` does ("16:30", "4:30pm", "4 pm"); now = 0 means the
 * current time. Returns LLS_OK or LLS_E_INVALID. */
LLS_API int lls_parse_time(const char* text, int64_t now, int64_t* out_until);

/* ---- Database ------------------------------------------------------------- */

/* Opens `path` (loaded into memory; created by the first lls_save if it does not exist).
 * On failure *out_db is NULL; the message is in lls_last_error(NULL). */
LLS_API int lls_open(const char* path, lls_db** out_db);
LLS_API void lls_close(lls_db* db);  /* does not save */

/* Message of the last failed call on `db`; with db == NULL, of the last failed lls_open
 * on this thread. Empty string if the last call succeeded. */
LLS_API const char* lls_last_error(const lls_db* db);
/* Notes from the last call that changed something, one per line, no trailing newline.
 * Queries (lls_tasks / lls_accounts) do not reset them; a failed change leaves none. */
LLS_API const char* lls_last_messages(const lls_db* db);

LLS_API const char* lls_path(const lls_db* db);
LLS_API int lls_is_dirty(const lls_db* db);  /* 1 if there are unsaved changes */
LLS_API int lls_save(lls_db* db);
/* Writes a copy. file == NULL: "<path>.<timestamp>.bak". The path used is copied to
 * used_path (if not NULL), truncated to used_path_size. */
LLS_API int lls_backup(lls_db* db, const char* file, char* used_path, size_t used_path_size);
/* Replaces the in-memory data with the contents of `file` (not saved until lls_save). */
LLS_API int lls_restore(lls_db* db, const char* file);

/* Pretends the time is `now` (Unix seconds) for every later call: useful for tests and
 * simulations. 0 goes back to the real clock. */
LLS_API void lls_set_clock(lls_db* db, int64_t now);
LLS_API int64_t lls_now(const lls_db* db);

/* ---- Accounts ------------------------------------------------------------- */

LLS_API int lls_account_add(lls_db* db, const char* name);
LLS_API int lls_account_delete(lls_db* db, const char* name);  /* its tasks become unassigned */
LLS_API int lls_account_rename(lls_db* db, const char* name, const char* new_name);
/* The account hit its limit until a clock time ("16:30", "4:30pm") / until a Unix time. */
LLS_API int lls_account_set_wait(lls_db* db, const char* name, const char* time_text);
LLS_API int lls_account_set_wait_at(lls_db* db, const char* name, int64_t until);
/* Clears its wait / limit reset. Sets *was_waiting (if not NULL) to 1 or 0. */
LLS_API int lls_account_clear_wait(lls_db* db, const char* name, int* was_waiting);

/* ---- Tasks ---------------------------------------------------------------- */

/* account == NULL: no account. status == NULL: prompt (see the notes at the top). */
LLS_API int lls_task_add(lls_db* db, const char* name, const char* account, const char* status);
LLS_API int lls_task_delete(lls_db* db, const char* name);
LLS_API int lls_task_rename(lls_db* db, const char* name, const char* new_name);
LLS_API int lls_task_set_account(lls_db* db, const char* name, const char* account);  /* NULL = none */
LLS_API int lls_task_set_status(lls_db* db, const char* name, const char* status);
/* Stores the text as it is (any length, any number of lines; "" clears). */
LLS_API int lls_task_set_notes(lls_db* db, const char* name, const char* notes);

/* ---- Queries -------------------------------------------------------------- */

/* Tasks in display order: status priority (Limit reset, Testing, Prompt, Wait, Uploading,
 * Frozen, Done); Wait / Limit reset by time; then account A-Z (none last); then name. */
LLS_API int lls_tasks(lls_db* db, lls_task_list** out_list);
LLS_API int lls_task_list_count(const lls_task_list* list);
LLS_API const lls_task_info* lls_task_list_get(const lls_task_list* list, int index);  /* NULL if out of range */
LLS_API void lls_task_list_free(lls_task_list* list);

/* Accounts in display order, most free first: Free, Taken, Busy; ties by name. */
LLS_API int lls_accounts(lls_db* db, lls_account_list** out_list);
LLS_API int lls_account_list_count(const lls_account_list* list);
LLS_API const lls_account_info* lls_account_list_get(const lls_account_list* list, int index);
LLS_API void lls_account_list_free(lls_account_list* list);

#ifdef __cplusplus
}
#endif

#endif /* LLS_API_H */