/*
 * HEART Core embedding interface, version 1.0 (draft).
 *
 * Plain C99. No threads, heap or operating system required: the product
 * supplies one block of memory and calls heart_tick() from its own loop.
 * Every function returns quickly and never blocks.
 *
 * This header is a design. No implementation exists yet.
 */
#ifndef HEART_CORE_H
#define HEART_CORE_H

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

#ifdef __cplusplus
extern "C" {
#endif

#define HEART_CORE_VERSION_MAJOR 1
#define HEART_CORE_VERSION_MINOR 0

typedef struct heart_core heart_core;

typedef enum {
    HEART_OK = 0,
    HEART_ERR_ARGUMENT,   /* a parameter was invalid */
    HEART_ERR_NO_MEMORY,  /* the arena is too small */
    HEART_ERR_QUEUE_FULL, /* dropped and counted; never fatal to the product */
    HEART_ERR_STOPPED     /* the Core has shut itself down */
} heart_status;

typedef enum { HEART_HEALTHY, HEART_DEGRADED, HEART_FAILING, HEART_UNKNOWN } heart_health;
typedef enum { HEART_INFO, HEART_WARNING, HEART_ERROR, HEART_CRITICAL } heart_severity;
typedef enum { HEART_READ, HEART_WRITE, HEART_DESTRUCTIVE } heart_risk;

/* Writes a message out. Supplied by the product for its transport. */
typedef heart_status (*heart_send_fn)(void *user, const uint8_t *data, size_t length);

/* Stores state atomically, so that power loss cannot corrupt it. */
typedef heart_status (*heart_persist_fn)(void *user, const uint8_t *data, size_t length);

/* Reads back the state last stored by heart_persist_fn, at startup, so the
 * Core can resume without repeating a completed Action and can undo a Trial
 * that was running (Core Standard, Sections 7.5 and 9). Copies up to
 * buffer_size bytes and sets *length. Returns HEART_ERR_ARGUMENT if nothing
 * is stored. */
typedef heart_status (*heart_restore_fn)(void *user, uint8_t *buffer, size_t buffer_size,
                                         size_t *length);

/* Runs a capability. Returns a JSON result in out, up to out_size bytes. */
typedef heart_status (*heart_handler_fn)(void *user, const char *arguments_json,
                                         char *out, size_t out_size);

typedef struct {
    const char *card_json;     /* the HEART Card, as JSON */
    uint32_t pulse_interval_ms;
    heart_send_fn send;
    heart_persist_fn persist;  /* may be NULL if nothing is stored */
    heart_restore_fn restore;  /* NULL only if persist is NULL */
    void *user;                /* passed back to the callbacks */
} heart_config;

/* What the product can do. risk and physical override the same fields in
 * definition_json; callers (who may use it) comes from definition_json and
 * defaults to human only (API Standard, Section 6.2). */
typedef struct {
    const char *definition_json; /* capability or custom definition */
    heart_risk risk;
    int physical;                /* non-zero if it affects the physical world */
    heart_handler_fn handler;
} heart_capability;

/* Starts a Core inside the given memory. Returns NULL if it does not fit. */
heart_core *heart_init(void *arena, size_t arena_size, const heart_config *config);

/* Gives the Core time to work. Call from the product's own loop. */
heart_status heart_tick(heart_core *core, uint64_t now_ms);

/* Hands over a received message or API request. Queued, handled in heart_tick. */
heart_status heart_receive(heart_core *core, const uint8_t *data, size_t length);

/* Reports what is happening. */
heart_status heart_state(heart_core *core, const char *state);
heart_status heart_status_set(heart_core *core, heart_health health);
heart_status heart_vital(heart_core *core, const char *name, double value);
heart_status heart_record(heart_core *core, const char *event, heart_severity severity);

/* Tells the Core the current values of a capability's settings, as a JSON
 * object such as {"ramp_rate": 2.0}, when they change outside the Core.
 * A Trial restores these values; without them it cannot start (Core
 * Standard, Section 7.5). */
heart_status heart_setting(heart_core *core, const char *capability, const char *values_json);

/* Registers what the product can do. */
heart_status heart_register(heart_core *core, const heart_capability *capability);

/* Stops all autonomous action at once. Always succeeds. */
void heart_stop_autonomy(heart_core *core);

/* Shuts the Core down. The product carries on. */
void heart_shutdown(heart_core *core);

#ifdef __cplusplus
}
#endif

#endif /* HEART_CORE_H */