/**
 * libstorage.h - C-exported interface for the Storage shared library
 *
 * This file implements the public C API for libstorage. It acts as the bridge
 * between C programs and the internal Nim implementation.
 *
 * Unless it is explicitly stated otherwise, all functions are asynchronous and execute
 * their work on a separate thread, returning results via the provided callback. The
 * result code of the function represents the synchronous status of the call itself:
 * returning RET_OK if the job has been dispatched to the thread, and RET_ERR in case
 * of immediate failure.
 *
 * The callback function is invoked with the result of the operation, including
 * any data or error messages. If the call was successful, `callerRet` will be RET_OK,
 * and `msg` will contain the result data. If there was an error, `callerRet` will be RET_ERR,
 * and `msg` will contain the error message.
 *
 * When a function supports progress updates, it may invoke the callback multiple times:
 * first with RET_PROGRESS and progress information, and finally with RET_OK or RET_ERR
 * upon completion. The msg parameter will a chunk of data for upload and download operations.
 *
 * `userData` is a pointer provided by the caller that is passed back to the callback
 * for context.
 */

#ifndef __libstorage__
#define __libstorage__

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

// The possible returned values for the functions that return int
#define RET_OK 0
#define RET_ERR 1
#define RET_MISSING_CALLBACK 2

// RET_PROGRESS is used to indicate that the callback is being
// with progress updates.
#define RET_PROGRESS 3

#ifdef __cplusplus
extern "C"
{
#endif

    typedef void (*StorageCallback)(int callerRet, const char *msg, size_t len, void *userData);

    // Create a new instance of a Logos Storage node.
    // `configJson` is a JSON string with the configuration overwriting defaults.
    // Returns a pointer to the StorageContext used to interact with the node.
    //
    // Typical usage:
    // ctx = storage_new(configJson, myCallback, myUserData);
    // storage_start(ctx, ...);
    // ...
    // storage_stop(ctx, ...);
    // storage_destroy(ctx, ...);
    void *storage_new(
        const char *configJson,
        StorageCallback callback,
        void *userData);

    // Get the Logos Storage version string.
    // This call does not require the node to be started and
    // does not involve a thread call.
    int storage_version(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Get the Logos Storage contracts revision.
    // This call does not require the node to be started and
    // does not involve a thread call.
    int storage_revision(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Get the repo (data-dir) used by the node.
    int storage_repo(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Retrieve debug information (JSON).
    //
    // Here is an example of the returned JSON structure:
    // {
    //  "id": "...",
    //  "addrs": ["..."],
    //  "spt": "",
    //  "announceAddresses": ["..."],
    //  "table": {
    //   "localNode": "",
    //   "nodes": [
    //      {
    //       "nodeId": "...",
    //       "peerId": "...",
    //       "record": "...",
    //       "address": "...",
    //       "seen": true,
    //      }
    //   ]
    // }
    int storage_debug(
        void *ctx,
        StorageCallback callback,
        void *userData);

    /// Get the node's  (Signed Peer Record)
    int storage_spr(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Get the node's peer ID.
    // Peer Identity reference as specified at
    // https://docs.libp2p.io/concepts/fundamentals/peers/
    int storage_peer_id(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Set the log level at run time.
    // `logLevel` can be one of:
    // TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL
    int storage_log_level(
        void *ctx,
        const char *logLevel,
        StorageCallback callback,
        void *userData);

    // Connect to a peer by using `peerAddresses` if provided, otherwise use `peerId`.
    // Note that the `peerId` has to be advertised in the DHT for this to work.
    int storage_connect(
        void *ctx,
        const char *peerId,
        const char **peerAddresses,
        size_t peerAddressesSize,
        StorageCallback callback,
        void *userData);

    // Request debug information for a given peer ID.
    // This api is only available if the library was compiled with
    // `storage_enable_api_debug_peers` argument.
    //
    // Here is an example of the returned JSON structure:
    // {
    //  "peerId": "...",
    //  "seqNo": 0,
    //  "addresses": [],
    // }
    int storage_peer_debug(
        void *ctx,
        const char *peerId,
        StorageCallback callback,
        void *userData);

    // Initialize an upload session for a file.
    // `filepath` for a file upload, this is the absolute path to the file
    // to be uploaded. For an upload using chunks, this is the name of the file.
    // The metadata filename and mime type are derived from this value.
    //
    // `chunkSize` defines the size of each chunk to be used during upload.
    // The default value is the default block size 1024 * 64 bytes.
    //
    // The callback returns the `sessionId` for the download session created.
    //
    // Typical usage:
    // storage_upload_init(ctx, filepath, chunkSize, myCallback, myUserData);
    // ...
    // storage_upload_chunk(ctx, sessionId, chunk, len, myCallback, myUserData);
    // ...
    // storage_upload_finalize(ctx, sessionId, myCallback, myUserData);
    int storage_upload_init(
        void *ctx,
        const char *filepath,
        size_t chunkSize,
        StorageCallback callback,
        void *userData);

    // Upload a chunk for the given `sessionId`.
    int storage_upload_chunk(
        void *ctx,
        const char *sessionId,
        const uint8_t *chunk,
        size_t len,
        StorageCallback callback,
        void *userData);

    // Finalize an upload session identified by `sessionId`.
    // The callback returns the `cid` of the uploaded content.
    int storage_upload_finalize(
        void *ctx,
        const char *sessionId,
        StorageCallback callback,
        void *userData);

    // Cancel an ongoing upload session.
    int storage_upload_cancel(
        void *ctx,
        const char *sessionId,
        StorageCallback callback,
        void *userData);

    // Upload the file defined as `filepath` in the init method.
    // The callback will be called with RET_PROGRESS updates during the upload,
    // if the chunk size is equal or greater than the session chunkSize.
    //
    // The callback returns the `cid` of the uploaded content.
    //
    // Typical usage:
    // storage_upload_init(ctx, filepath, chunkSize, myCallback, myUserData);
    // ...
    // storage_upload_file(ctx, sessionId, myCallback, myUserData);
    int storage_upload_file(
        void *ctx,
        const char *sessionId,
        StorageCallback callback,
        void *userData);

    // Initialize a download for `cid`.
    // `chunkSize` defines the size of each chunk to be used during download.
    // The default value is the default block size 1024 * 64 bytes.
    // `local` indicates whether to attempt local store retrieval only.
    //
    // Typical usage:
    // storage_download_init(ctx, cid, chunkSize, local, myCallback, myUserData);
    // ...
    // storage_download_stream(ctx, cid, filepath, myCallback, myUserData);
    int storage_download_init(
        void *ctx,
        const char *cid,
        size_t chunkSize,
        bool local,
        StorageCallback callback,
        void *userData);

    // Perform a streaming download for `cid`.
    // The init method must have been called prior to this.
    // If filepath is provided, the content will be written to that file.
    // The callback will be called with RET_PROGRESS updates during the download/
    // `local` indicates whether to attempt local store retrieval only.
    //
    // Typical usage:
    // storage_download_init(ctx, cid, chunkSize, local, myCallback, myUserData);
    // ...
    // storage_download_stream(ctx, cid, filepath, myCallback, myUserData);
    int storage_download_stream(
        void *ctx,
        const char *cid,
        size_t chunkSize,
        bool local,
        const char *filepath,
        StorageCallback callback,
        void *userData);

    // Download a chunk for the given `cid`.
    // The init method must have been called prior to this.
    // The chunk will be returned via the callback using `RET_PROGRESS`.
    int storage_download_chunk(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Cancel an ongoing download for `cid`.
    int storage_download_cancel(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Retrieve the manifest for the given `cid`.
    //
    // Here is an example of the returned manifest JSON structure:
    // {
    //  "treeCid": "zDzSvJTf8JYwvysKPmG7BtzpbiAHfuwFMRphxm4hdvnMJ4XPJjKX",
    //  "datasetSize": 123456,
    //  "blockSize": 65536,
    //  "filename": "example.txt",
    //  "mimetype": "text/plain",
    //  "protected": false
    // }
    int storage_download_manifest(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Retrieve the list of the manifests stored in the node.
    int storage_list(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Retrieve the storage space information.
    //
    // Here is an example of the returned JSON structure:
    // {
    //  "totalBlocks": 100000,
    //  "quotaMaxBytes": 0,
    //  "quotaUsedBytes": 0,
    //  "quotaReservedBytes": 0
    // }
    int storage_space(
        void *ctx,
        StorageCallback callback,
        void *userData);

    // Delete the content identified by `cid`.
    int storage_delete(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Fetch the content identified by `cid` from the network into
    // local store.
    // The download is done in background so the callback
    // will not receive progress updates.
    int storage_fetch(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Check if the content identified by `cid` exists in local store.
    int storage_exists(
        void *ctx,
        const char *cid,
        StorageCallback callback,
        void *userData);

    // Start the Logos Storage node.
    // The node can be started and stopped multiple times.
    //
    // Typical usage:
    // ctx = storage_new(configJson, myCallback, myUserData);
    // storage_start(ctx, ...);
    // ...
    // storage_stop(ctx, ...);
    // storage_destroy(ctx, ...);
    int storage_start(void *ctx,
                      StorageCallback callback,
                      void *userData);

    // Stop the Logos Storage node.
    // The node can be started and stopped multiple times.
    //
    // Typical usage:
    // ctx = storage_new(configJson, myCallback, myUserData);
    // storage_start(ctx, ...);
    // ...
    // storage_stop(ctx, ...);
    // storage_destroy(ctx, ...);
    int storage_stop(void *ctx,
                     StorageCallback callback,
                     void *userData);

    // Close the Logos Storage node.
    // Use this to release resources before destroying the node.
    //
    // Typical usage:
    // ctx = storage_new(configJson, myCallback, myUserData);
    // storage_start(ctx, ...);
    // ...
    // storage_stop(ctx, ...);
    // storage_close(ctx, ...);
    int storage_close(void *ctx,
                      StorageCallback callback,
                      void *userData);

    // Destroys an instance of a Logos Storage node.
    // This will free all resources associated with the node.
    // The node must be stopped and closed before calling this function.
    //
    // Typical usage:
    // ctx = storage_new(configJson, myCallback, myUserData);
    // storage_start(ctx, ...);
    // ...
    // storage_stop(ctx, ...);
    // storage_close(ctx, ...);
    // storage_destroy(ctx, ...);
    int storage_destroy(void *ctx,
                        StorageCallback callback,
                        void *userData);

    // Not used currently.
    // Reserved for future use to set an event callback.
    void storage_set_event_callback(void *ctx,
                                    StorageCallback callback,
                                    void *userData);

#ifdef __cplusplus
}
#endif

#endif /* __libstorage__ */