From c92febd80b03f82addd548123ce237d80cd57ae2 Mon Sep 17 00:00:00 2001 From: Arnaud Date: Fri, 19 Dec 2025 08:38:29 +0100 Subject: [PATCH] Provide better comments --- .github/workflows/artifacts.yml | 4 +- library/libstorage.h | 509 ++++++++++++++++++++++---------- 2 files changed, 354 insertions(+), 159 deletions(-) diff --git a/.github/workflows/artifacts.yml b/.github/workflows/artifacts.yml index 049ed580..7c7cd920 100644 --- a/.github/workflows/artifacts.yml +++ b/.github/workflows/artifacts.yml @@ -2,8 +2,8 @@ name: Artifacts on: push: - tags: - - "v*" + # tags: + # - "v*" workflow_dispatch: jobs: diff --git a/library/libstorage.h b/library/libstorage.h index 76d5e2e1..cf129b0c 100644 --- a/library/libstorage.h +++ b/library/libstorage.h @@ -1,203 +1,398 @@ /** -* libstorage.h - C Interface for Example Library -* -* This header provides the public API for libstorage -* -* To see the auto-generated header by Nim, run `make libstorage` from the -* repository root. The generated file will be created at: -* nimcache/release/libstorage/libstorage.h -*/ + * 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 #include +#include // The possible returned values for the functions that return int -#define RET_OK 0 -#define RET_ERR 1 -#define RET_MISSING_CALLBACK 2 -#define RET_PROGRESS 3 +#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" { +extern "C" +{ #endif -typedef void (*StorageCallback) (int callerRet, const char* msg, size_t len, void* userData); + typedef void (*StorageCallback)(int callerRet, const char *msg, size_t len, void *userData); -void* storage_new( - const char* configJson, - StorageCallback callback, - 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); -int storage_version( - void* ctx, - 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); -int storage_revision( - 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); -int storage_repo( - void* ctx, - StorageCallback callback, - void* userData); + // Get the repo (data-dir) used by the node. + int storage_repo( + void *ctx, + StorageCallback callback, + void *userData); -int storage_debug( - 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); -int storage_spr( - void* ctx, - StorageCallback callback, - void* userData); + /// Get the node's (Signed Peer Record) + int storage_spr( + void *ctx, + StorageCallback callback, + void *userData); -int storage_peer_id( - 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); -int storage_log_level( - void* ctx, - const char* logLevel, - 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); -int storage_connect( - void* ctx, - const char* peerId, - const char** peerAddresses, - size_t peerAddressesSize, - StorageCallback callback, - void* userData); + /* Connect to a peer by `peerId`; optionally provide an array of multiaddrs + * in `peerAddresses` of length `peerAddressesSize`. Result via `callback`. + */ + int storage_connect( + void *ctx, + const char *peerId, + const char **peerAddresses, + size_t peerAddressesSize, + StorageCallback callback, + void *userData); -int storage_peer_debug( - void* ctx, - const char* peerId, - 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); -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); -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); -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); -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); -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); -int storage_download_stream( - void* ctx, - const char* cid, - size_t chunkSize, - bool local, - const char* filepath, - 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); -int storage_download_init( - void* ctx, - const char* cid, - size_t chunkSize, - bool local, - 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); -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); -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); -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); -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); -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); -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); -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); -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); -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); -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); -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); -// Destroys an instance of a Logos Storage node created with storage_new -int storage_destroy(void* ctx, - StorageCallback callback, - void* userData); - -void storage_set_event_callback(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 }