rats.h

Go to the documentation of this file.

#pragma once
 
#include "util/rats_export.h"
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef void* rats_t;
 
typedef enum {
    RATS_SECURITY_NOISE     = 0,  /* Noise XX, encrypted + authenticated (default) */
    RATS_SECURITY_PLAINTEXT = 1   /* unencrypted, ids exchanged in the clear */
} rats_security_t;
 
/* Result of a fallible operation. RATS_OK is 0; any non-zero value is an error.
 * NOTE: this inverts the truthiness of the old int-returning calls — test against
 * RATS_OK, not against zero/non-zero, e.g. `if (rats_start(n) != RATS_OK) …`. */
typedef enum {
    RATS_OK                  = 0,
    RATS_ERR_INVALID_ARG     = 1,  /* null/malformed argument (bad peer id, null ptr, bad json) */
    RATS_ERR_NOT_STARTED     = 2,  /* operation requires a started node */
    RATS_ERR_ALREADY_STARTED = 3,  /* enable/attach called after rats_start() */
    RATS_ERR_NOT_ENABLED     = 4,  /* subsystem not enabled — call the matching rats_enable_* */
    RATS_ERR_NO_SUCH_PEER    = 5,  /* peer not connected, or transfer id not found */
    RATS_ERR_BIND            = 6,  /* listen/bind failed during rats_start() */
    RATS_ERR_INTERNAL        = 7
} rats_error_t;
 
RATS_API const char* rats_error_str(rats_error_t err);
 
/* — construction / lifecycle — */
 
typedef struct {
    uint16_t        listen_port;      /* inbound port; 0 = ephemeral */
    int             enable_listen;    /* 0 = dial-only node (no listener) */
    const char*     bind_address;     /* NULL → "::" dual-stack wildcard */
    rats_security_t security;         /* RATS_SECURITY_NOISE / _PLAINTEXT */
    const char*     data_dir;         /* persistent state dir; NULL/"" → ephemeral identity each run */
    const char*     protocol_name;    /* handshake app namespace; NULL → "librats" */
    const char*     protocol_version; /* handshake app version;   NULL → "1.0" */
    size_t          max_peers;        /* established-peer cap; 0 = unlimited */
} rats_config_t;
 
RATS_API rats_config_t rats_config_default(void);
 
RATS_API rats_t rats_create_config(const rats_config_t* config);
 
RATS_API rats_t rats_create(uint16_t listen_port);
 
RATS_API rats_t rats_create_ex(uint16_t listen_port, int enable_listen,
                                         const char* bind_address, rats_security_t security);
 
RATS_API void         rats_destroy(rats_t node);
RATS_API rats_error_t rats_start(rats_t node);   /* RATS_OK / RATS_ERR_ALREADY_STARTED / RATS_ERR_BIND */
RATS_API void         rats_stop(rats_t node);
RATS_API uint16_t     rats_listen_port(rats_t node);
 
RATS_API char*    rats_local_id(rats_t node);
 
RATS_API char*    rats_protocol_name(rats_t node);
RATS_API char*    rats_protocol_version(rats_t node);
 
/* — connections — */
 
RATS_API rats_error_t rats_connect(rats_t node, const char* host, uint16_t port);
RATS_API size_t       rats_peer_count(rats_t node);
 
RATS_API void   rats_set_max_peers(rats_t node, size_t max_peers);
RATS_API size_t rats_max_peers(rats_t node);
 
/* — messaging (named application channel, raw bytes) — */
 
RATS_API rats_error_t rats_send(rats_t node, const char* peer_id_hex,
                                          const char* channel, const void* data, size_t len);
RATS_API rats_error_t rats_broadcast(rats_t node, const char* channel,
                                               const void* data, size_t len);
 
/* — callbacks (register before start; invoked on a reactor thread) — */
 
typedef void (*rats_peer_cb)(void* user, const char* peer_id_hex);
typedef void (*rats_message_cb)(void* user, const char* peer_id_hex, const void* data, size_t len);
 
RATS_API rats_error_t rats_on_peer_connected(rats_t node, rats_peer_cb cb, void* user);
RATS_API rats_error_t rats_on_peer_disconnected(rats_t node, rats_peer_cb cb, void* user);
RATS_API rats_error_t rats_on(rats_t node, const char* channel, rats_message_cb cb, void* user);
 
/* — optional subsystems (enable before start) — */
 
RATS_API rats_error_t rats_enable_dht(rats_t node, uint16_t dht_port, const char* discovery_key);
RATS_API rats_error_t rats_enable_mdns(rats_t node);
RATS_API rats_error_t rats_enable_port_mapping(rats_t node, int enable_upnp, int enable_natpmp);
 
/* — peer enumeration — */
 
RATS_API char** rats_peer_ids(rats_t node, size_t* count);
RATS_API void   rats_free_peer_ids(char** ids, size_t count);
 
/* — pub/sub (topic-based, raw bytes; enable + subscribe before start) — */
 
typedef void (*rats_topic_cb)(void* user, const char* peer_id_hex,
                              const char* topic, const void* data, size_t len);
 
RATS_API rats_error_t rats_enable_pubsub(rats_t node);
RATS_API rats_error_t rats_subscribe(rats_t node, const char* topic, rats_topic_cb cb, void* user);
RATS_API rats_error_t rats_unsubscribe(rats_t node, const char* topic);
RATS_API rats_error_t rats_publish(rats_t node, const char* topic, const void* data, size_t len);
 
/* — typed JSON messaging (named message type; payload is JSON text) — */
 
typedef void (*rats_json_cb)(void* user, const char* peer_id_hex, const char* json);
 
RATS_API rats_error_t rats_enable_json(rats_t node);
RATS_API rats_error_t rats_on_json(rats_t node, const char* type, rats_json_cb cb, void* user);
RATS_API rats_error_t rats_once_json(rats_t node, const char* type, rats_json_cb cb, void* user);
RATS_API rats_error_t rats_off_json(rats_t node, const char* type);
RATS_API rats_error_t rats_send_json(rats_t node, const char* peer_id_hex, const char* type, const char* json);
RATS_API rats_error_t rats_broadcast_json(rats_t node, const char* type, const char* json);
 
/* — file transfer (push model; enable + register callbacks before start) — */
 
typedef void (*rats_file_offer_cb)(void* user, const char* peer_id_hex, uint64_t transfer_id,
                                   const char* name, uint64_t size, int is_directory);
typedef void (*rats_file_progress_cb)(void* user, uint64_t transfer_id, const char* peer_id_hex,
                                      uint64_t bytes_transferred, uint64_t total_bytes, int status);
typedef void (*rats_file_complete_cb)(void* user, uint64_t transfer_id, int success, const char* path);
 
RATS_API rats_error_t rats_enable_file_transfer(rats_t node, const char* temp_dir);
 
RATS_API rats_error_t rats_on_file_offer(rats_t node, rats_file_offer_cb cb, void* user);
RATS_API rats_error_t rats_on_file_progress(rats_t node, rats_file_progress_cb cb, void* user);
RATS_API rats_error_t rats_on_file_complete(rats_t node, rats_file_complete_cb cb, void* user);
 
RATS_API uint64_t rats_send_file(rats_t node, const char* peer_id_hex, const char* path);
RATS_API uint64_t rats_send_directory(rats_t node, const char* peer_id_hex, const char* dir_path);
 
RATS_API rats_error_t rats_accept_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id, const char* dest_path);
RATS_API rats_error_t rats_reject_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
 
RATS_API rats_error_t rats_cancel_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
RATS_API rats_error_t rats_pause_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
RATS_API rats_error_t rats_resume_file(rats_t node, const char* peer_id_hex, uint64_t transfer_id);
 
/* — liveness (RTT probing) — */
 
RATS_API rats_error_t rats_enable_ping(rats_t node);
RATS_API int64_t rats_peer_rtt_ms(rats_t node, const char* peer_id_hex);
 
/* — automatic reconnection — */
 
RATS_API rats_error_t rats_enable_reconnect(rats_t node);
RATS_API rats_error_t rats_add_reconnect(rats_t node, const char* host, uint16_t port);
RATS_API rats_error_t rats_remove_reconnect(rats_t node, const char* host, uint16_t port);
 
/* — logging (process-global; no node required) — */
 
typedef enum {
    RATS_LOG_DEBUG = 0,
    RATS_LOG_INFO  = 1,
    RATS_LOG_WARN  = 2,
    RATS_LOG_ERROR = 3
} rats_log_level_t;
 
RATS_API void rats_set_log_level(rats_log_level_t level);
RATS_API void rats_set_log_file(const char* path);
 
/* — library info (process-global; no node required) — */
 
RATS_API const char* rats_version_string(void);
RATS_API void        rats_version(int* major, int* minor, int* patch, int* build);
RATS_API const char* rats_git_describe(void);
RATS_API uint32_t    rats_abi(void);
 
/* — utility — */
 
RATS_API void rats_string_free(char* str);
 
#ifdef __cplusplus
}
#endif