The canonical C ABI over Node — the foundation for all language bindings. More...

#include "util/rats_export.h"
#include <stddef.h>
#include <stdint.h>

Include dependency graph for rats.h:

Classes
struct	rats_config_t
	Full node configuration. More...

Typedefs
typedef void *	rats_t

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)

typedef void(*	rats_topic_cb) (void user, const char peer_id_hex, const char topic, const void data, size_t len)

typedef void(*	rats_json_cb) (void user, const char peer_id_hex, const char *json)

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)

Enumerations
enum	rats_security_t { RATS_SECURITY_NOISE = 0 , RATS_SECURITY_PLAINTEXT = 1 }

enum	rats_error_t { RATS_OK = 0 , RATS_ERR_INVALID_ARG = 1 , RATS_ERR_NOT_STARTED = 2 , RATS_ERR_ALREADY_STARTED = 3 , RATS_ERR_NOT_ENABLED = 4 , RATS_ERR_NO_SUCH_PEER = 5 , RATS_ERR_BIND = 6 , RATS_ERR_INTERNAL = 7 }

enum	rats_log_level_t { RATS_LOG_DEBUG = 0 , RATS_LOG_INFO = 1 , RATS_LOG_WARN = 2 , RATS_LOG_ERROR = 3 }

Functions
const char *	rats_error_str (rats_error_t err)
	Static human-readable name of an error code (do not free).

rats_config_t	rats_config_default (void)
	A config pre-filled with the library defaults (listening, Noise, ephemeral identity, unlimited peers).

rats_t	rats_create_config (const rats_config_t *config)
	Create a node from a full config (NULL → all defaults).

rats_t	rats_create (uint16_t listen_port)
	Create a listening node (Noise, dual-stack, ephemeral identity, port 0 = ephemeral).

rats_t	rats_create_ex (uint16_t listen_port, int enable_listen, const char *bind_address, rats_security_t security)
	Create with basic control.

void	rats_destroy (rats_t node)

rats_error_t	rats_start (rats_t node)

void	rats_stop (rats_t node)

uint16_t	rats_listen_port (rats_t node)

char *	rats_local_id (rats_t node)
	Our self-certifying peer id as hex.

char *	rats_protocol_name (rats_t node)
	Application protocol identity bound into the handshake (see rats_config_t).

char *	rats_protocol_version (rats_t node)

rats_error_t	rats_connect (rats_t node, const char *host, uint16_t port)

size_t	rats_peer_count (rats_t node)

void	rats_set_max_peers (rats_t node, size_t max_peers)
	Cap on established peers (0 = unlimited).

size_t	rats_max_peers (rats_t node)

rats_error_t	rats_send (rats_t node, const char peer_id_hex, const char channel, const void *data, size_t len)

rats_error_t	rats_broadcast (rats_t node, const char channel, const void data, size_t len)

rats_error_t	rats_on_peer_connected (rats_t node, rats_peer_cb cb, void *user)

rats_error_t	rats_on_peer_disconnected (rats_t node, rats_peer_cb cb, void *user)

rats_error_t	rats_on (rats_t node, const char channel, rats_message_cb cb, void user)

rats_error_t	rats_enable_dht (rats_t node, uint16_t dht_port, const char *discovery_key)
	DHT discovery.

rats_error_t	rats_enable_mdns (rats_t node)
	Local-network mDNS discovery.

rats_error_t	rats_enable_port_mapping (rats_t node, int enable_upnp, int enable_natpmp)
	Automatic NAT port forwarding for the listen port (UPnP IGD + NAT-PMP).

char **	rats_peer_ids (rats_t node, size_t *count)
	Hex ids of currently-connected peers.

void	rats_free_peer_ids (char **ids, size_t count)

rats_error_t	rats_enable_pubsub (rats_t node)
	Enable the pub/sub (GossipSub) subsystem.

rats_error_t	rats_subscribe (rats_t node, const char topic, rats_topic_cb cb, void user)
	Subscribe to `topic`; matching messages invoke `cb` on a reactor thread.

rats_error_t	rats_unsubscribe (rats_t node, const char *topic)

rats_error_t	rats_publish (rats_t node, const char topic, const void data, size_t len)
	Publish `data` on `topic` to every subscribed peer (and local subscribers).

rats_error_t	rats_enable_json (rats_t node)
	Enable the JSON-messaging subsystem (the C view of MessageJson).

rats_error_t	rats_on_json (rats_t node, const char type, rats_json_cb cb, void user)
	Register a handler for JSON messages of `type`.

rats_error_t	rats_once_json (rats_t node, const char type, rats_json_cb cb, void user)
	Like rats_on_json, but the handler is removed right after it fires once.

rats_error_t	rats_off_json (rats_t node, const char *type)

rats_error_t	rats_send_json (rats_t node, const char peer_id_hex, const char type, const char *json)
	Send/broadcast a JSON message.

rats_error_t	rats_broadcast_json (rats_t node, const char type, const char json)

rats_error_t	rats_enable_file_transfer (rats_t node, const char *temp_dir)
	Enable the file-transfer subsystem.

rats_error_t	rats_on_file_offer (rats_t node, rats_file_offer_cb cb, void *user)

rats_error_t	rats_on_file_progress (rats_t node, rats_file_progress_cb cb, void *user)

rats_error_t	rats_on_file_complete (rats_t node, rats_file_complete_cb cb, void *user)

uint64_t	rats_send_file (rats_t node, const char peer_id_hex, const char path)
	Offer a file / directory tree to a peer.

uint64_t	rats_send_directory (rats_t node, const char peer_id_hex, const char dir_path)

rats_error_t	rats_accept_file (rats_t node, const char peer_id_hex, uint64_t transfer_id, const char dest_path)
	Respond to an offer.

rats_error_t	rats_reject_file (rats_t node, const char *peer_id_hex, uint64_t transfer_id)

rats_error_t	rats_cancel_file (rats_t node, const char *peer_id_hex, uint64_t transfer_id)
	Control a live transfer (either side).

rats_error_t	rats_pause_file (rats_t node, const char *peer_id_hex, uint64_t transfer_id)

rats_error_t	rats_resume_file (rats_t node, const char *peer_id_hex, uint64_t transfer_id)

rats_error_t	rats_enable_ping (rats_t node)
	Enable periodic ping/pong RTT probing of every peer.

int64_t	rats_peer_rtt_ms (rats_t node, const char *peer_id_hex)
	Last measured round-trip time to a peer in milliseconds, or -1 if unknown (ping not enabled, or no pong received yet).

rats_error_t	rats_enable_reconnect (rats_t node)
	Enable the reconnection subsystem: re-dials dropped peers with exponential backoff.

rats_error_t	rats_add_reconnect (rats_t node, const char *host, uint16_t port)
	Add an address to keep connected (re-dialed on drop).

rats_error_t	rats_remove_reconnect (rats_t node, const char *host, uint16_t port)
	Stop reconnecting to an address and drop it from the store.

void	rats_set_log_level (rats_log_level_t level)

void	rats_set_log_file (const char *path)
	Mirror logs to `path` (NULL/empty disables file logging).

const char *	rats_version_string (void)
	Library version as a static string, e.g.

void	rats_version (int major, int minor, int patch, int build)
	Library version components.

const char *	rats_git_describe (void)
	Git describe of the build, e.g.

uint32_t	rats_abi (void)
	Packed ABI id as (major<<16)\|(minor<<8)\|patch — MAJOR bumps on breaking changes, MINOR on additive ones.

void	rats_string_free (char *str)

Detailed Description

The canonical C ABI over Node — the foundation for all language bindings.

Opaque-pointer style. A rats_t wraps a C++ Node. Strings returned by the library (e.g. peer ids) are heap-allocated and must be released with rats_string_free(). Peer ids are 64-char lowercase hex of the peer's self-certifying PeerId.

Error model: fallible operations return a rats_error_t (RATS_OK == 0 on success). Pure getters return their value directly. Use rats_error_str() for a static human-readable name. Delivery of messages is asynchronous and best-effort: a RATS_OK from rats_send()/rats_publish() means the request was accepted and queued, not that a peer received it.

Subsystems are explicit and opt-in: discovery, pub/sub, typed messaging, file transfer and ping must each be turned on with the matching rats_enable_*() BEFORE rats_start(). Calling a subsystem function before its enable returns RATS_ERR_NOT_ENABLED; calling an enable after start returns RATS_ERR_ALREADY_STARTED.

Threading: callbacks fire on an internal reactor thread — do not block in them. Register callbacks and enable subsystems BEFORE rats_start().

Definition in file rats.h.

Typedef Documentation

◆ rats_file_complete_cb

typedef void(* rats_file_complete_cb) (void *user, uint64_t transfer_id, int success, const char *path)

Definition at line 192 of file rats.h.

◆ rats_file_offer_cb

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)

Definition at line 188 of file rats.h.

◆ rats_file_progress_cb

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)

Definition at line 190 of file rats.h.

◆ rats_json_cb

typedef void(* rats_json_cb) (void *user, const char *peer_id_hex, const char *json)

Definition at line 171 of file rats.h.

◆ rats_message_cb

typedef void(* rats_message_cb) (void *user, const char *peer_id_hex, const void *data, size_t len)

Definition at line 132 of file rats.h.

◆ rats_peer_cb

typedef void(* rats_peer_cb) (void *user, const char *peer_id_hex)

Definition at line 131 of file rats.h.

◆ rats_t

typedef void* rats_t

Definition at line 37 of file rats.h.

◆ rats_topic_cb

typedef void(* rats_topic_cb) (void *user, const char *peer_id_hex, const char *topic, const void *data, size_t len)

Definition at line 158 of file rats.h.

Enumeration Type Documentation

◆ rats_error_t

enum rats_error_t

Enumerator
RATS_OK
RATS_ERR_INVALID_ARG
RATS_ERR_NOT_STARTED
RATS_ERR_ALREADY_STARTED
RATS_ERR_NOT_ENABLED
RATS_ERR_NO_SUCH_PEER
RATS_ERR_BIND
RATS_ERR_INTERNAL

Definition at line 47 of file rats.h.

◆ rats_log_level_t

enum rats_log_level_t

Enumerator
RATS_LOG_DEBUG
RATS_LOG_INFO
RATS_LOG_WARN
RATS_LOG_ERROR

Definition at line 241 of file rats.h.

◆ rats_security_t

enum rats_security_t

Enumerator
RATS_SECURITY_NOISE
RATS_SECURITY_PLAINTEXT

Definition at line 39 of file rats.h.

Function Documentation

◆ rats_abi()

uint32_t rats_abi ( void )

Packed ABI id as (major<<16)|(minor<<8)|patch — MAJOR bumps on breaking changes, MINOR on additive ones.

◆ rats_accept_file()

rats_error_t rats_accept_file	(	rats_t	node,
		const char *	peer_id_hex,
		uint64_t	transfer_id,
		const char *	dest_path
	)

Respond to an offer.

For a single file, dest_path is the file path; for a directory, the destination directory. (peer_id, transfer_id) names the offer.

◆ rats_add_reconnect()

rats_error_t rats_add_reconnect	(	rats_t	node,
		const char *	host,
		uint16_t	port
	)

Add an address to keep connected (re-dialed on drop).

Persisted if a store is configured. May be called before or after start().

◆ rats_broadcast()

rats_error_t rats_broadcast	(	rats_t	node,
		const char *	channel,
		const void *	data,
		size_t	len
	)

◆ rats_broadcast_json()

rats_error_t rats_broadcast_json	(	rats_t	node,
		const char *	type,
		const char *	json
	)

◆ rats_cancel_file()

rats_error_t rats_cancel_file	(	rats_t	node,
		const char *	peer_id_hex,
		uint64_t	transfer_id
	)

Control a live transfer (either side).

RATS_OK if the transfer was found and the action applied; RATS_ERR_NO_SUCH_PEER if no matching transfer.

◆ rats_config_default()

rats_config_t rats_config_default ( void )

A config pre-filled with the library defaults (listening, Noise, ephemeral identity, unlimited peers).

Mutate the returned struct and pass to rats_create_config().

◆ rats_connect()

rats_error_t rats_connect	(	rats_t	node,
		const char *	host,
		uint16_t	port
	)

◆ rats_create()

rats_t rats_create ( uint16_t listen_port )

Create a listening node (Noise, dual-stack, ephemeral identity, port 0 = ephemeral).

◆ rats_create_config()

rats_t rats_create_config ( const rats_config_t * config )

Create a node from a full config (NULL → all defaults).

When data_dir is set, the identity persists across restarts and subsystems (DHT routing table, reconnection store) co-locate their state there.

◆ rats_create_ex()

rats_t rats_create_ex	(	uint16_t	listen_port,
		int	enable_listen,
		const char *	bind_address,
		rats_security_t	security
	)

Create with basic control.

enable_listen=0 makes a dial-only node. For data_dir / protocol identity / max_peers use rats_create_config().

◆ rats_destroy()

void rats_destroy ( rats_t node )

◆ rats_enable_dht()

rats_error_t rats_enable_dht	(	rats_t	node,
		uint16_t	dht_port,
		const char *	discovery_key
	)

DHT discovery.

dht_port 0 = ephemeral; discovery_key namespaces the app (NULL → default).

◆ rats_enable_file_transfer()

rats_error_t rats_enable_file_transfer	(	rats_t	node,
		const char *	temp_dir
	)

Enable the file-transfer subsystem.

temp_dir holds in-progress downloads (NULL → current directory). Call before start().

◆ rats_enable_json()

rats_error_t rats_enable_json ( rats_t node )

Enable the JSON-messaging subsystem (the C view of MessageJson).

Call before start().

◆ rats_enable_mdns()

rats_error_t rats_enable_mdns ( rats_t node )

Local-network mDNS discovery.

◆ rats_enable_ping()

rats_error_t rats_enable_ping ( rats_t node )

Enable periodic ping/pong RTT probing of every peer.

Call before start().

◆ rats_enable_port_mapping()

rats_error_t rats_enable_port_mapping	(	rats_t	node,
		int	enable_upnp,
		int	enable_natpmp
	)

Automatic NAT port forwarding for the listen port (UPnP IGD + NAT-PMP).

Pass non-zero to enable each backend; both run in parallel.

◆ rats_enable_pubsub()

rats_error_t rats_enable_pubsub ( rats_t node )

Enable the pub/sub (GossipSub) subsystem.

Call before start().

◆ rats_enable_reconnect()

rats_error_t rats_enable_reconnect ( rats_t node )

Enable the reconnection subsystem: re-dials dropped peers with exponential backoff.

Dialed peers are remembered automatically; when the node has a data_dir, targets persist to "<data_dir>/peers.txt" across restarts. Call before start(). A bare node never reconnects on its own.

◆ rats_error_str()

const char * rats_error_str ( rats_error_t err )

Static human-readable name of an error code (do not free).

◆ rats_free_peer_ids()

void rats_free_peer_ids	(	char **	ids,
		size_t	count
	)

◆ rats_git_describe()

const char * rats_git_describe ( void )

Git describe of the build, e.g.

"v1.2.3-4-gabcdef" (static; do not free).

◆ rats_listen_port()

uint16_t rats_listen_port ( rats_t node )

◆ rats_local_id()

char * rats_local_id ( rats_t node )

Our self-certifying peer id as hex.

Caller frees with rats_string_free().

◆ rats_max_peers()

size_t rats_max_peers ( rats_t node )

◆ rats_off_json()

rats_error_t rats_off_json	(	rats_t	node,
		const char *	type
	)

◆ rats_on()

rats_error_t rats_on	(	rats_t	node,
		const char *	channel,
		rats_message_cb	cb,
		void *	user
	)

◆ rats_on_file_complete()

rats_error_t rats_on_file_complete	(	rats_t	node,
		rats_file_complete_cb	cb,
		void *	user
	)

◆ rats_on_file_offer()

rats_error_t rats_on_file_offer	(	rats_t	node,
		rats_file_offer_cb	cb,
		void *	user
	)

◆ rats_on_file_progress()

rats_error_t rats_on_file_progress	(	rats_t	node,
		rats_file_progress_cb	cb,
		void *	user
	)

◆ rats_on_json()

rats_error_t rats_on_json	(	rats_t	node,
		const char *	type,
		rats_json_cb	cb,
		void *	user
	)

Register a handler for JSON messages of type.

json is compact JSON text owned by the library (valid only for the duration of the call). Additive: multiple handlers may coexist. The sender id is the authenticated handshake PeerId.

◆ rats_on_peer_connected()

rats_error_t rats_on_peer_connected	(	rats_t	node,
		rats_peer_cb	cb,
		void *	user
	)

◆ rats_on_peer_disconnected()

rats_error_t rats_on_peer_disconnected	(	rats_t	node,
		rats_peer_cb	cb,
		void *	user
	)

◆ rats_once_json()

rats_error_t rats_once_json	(	rats_t	node,
		const char *	type,
		rats_json_cb	cb,
		void *	user
	)

Like rats_on_json, but the handler is removed right after it fires once.

◆ rats_pause_file()

rats_error_t rats_pause_file	(	rats_t	node,
		const char *	peer_id_hex,
		uint64_t	transfer_id
	)

◆ rats_peer_count()

size_t rats_peer_count ( rats_t node )

◆ rats_peer_ids()

char ** rats_peer_ids	(	rats_t	node,
		size_t *	count
	)

Hex ids of currently-connected peers.

Writes the count to *count and returns a heap array of count heap strings; free the whole thing with rats_free_peer_ids(). Returns NULL (and *count = 0) when there are no peers.

◆ rats_peer_rtt_ms()

int64_t rats_peer_rtt_ms	(	rats_t	node,
		const char *	peer_id_hex
	)

Last measured round-trip time to a peer in milliseconds, or -1 if unknown (ping not enabled, or no pong received yet).

◆ rats_protocol_name()

char * rats_protocol_name ( rats_t node )

Application protocol identity bound into the handshake (see rats_config_t).

Two nodes whose (name, version) differ cannot complete a handshake. Caller frees the returned string with rats_string_free().

◆ rats_protocol_version()

char * rats_protocol_version ( rats_t node )

◆ rats_publish()

rats_error_t rats_publish	(	rats_t	node,
		const char *	topic,
		const void *	data,
		size_t	len
	)

Publish data on topic to every subscribed peer (and local subscribers).

◆ rats_reject_file()

rats_error_t rats_reject_file	(	rats_t	node,
		const char *	peer_id_hex,
		uint64_t	transfer_id
	)

◆ rats_remove_reconnect()

rats_error_t rats_remove_reconnect	(	rats_t	node,
		const char *	host,
		uint16_t	port
	)

Stop reconnecting to an address and drop it from the store.

◆ rats_resume_file()

rats_error_t rats_resume_file	(	rats_t	node,
		const char *	peer_id_hex,
		uint64_t	transfer_id
	)

◆ rats_send()

rats_error_t rats_send	(	rats_t	node,
		const char *	peer_id_hex,
		const char *	channel,
		const void *	data,
		size_t	len
	)

◆ rats_send_directory()

uint64_t rats_send_directory	(	rats_t	node,
		const char *	peer_id_hex,
		const char *	dir_path
	)

◆ rats_send_file()

uint64_t rats_send_file	(	rats_t	node,
		const char *	peer_id_hex,
		const char *	path
	)

Offer a file / directory tree to a peer.

Returns the transfer id (0 on failure, e.g. file transfer not enabled or bad peer id).

◆ rats_send_json()

rats_error_t rats_send_json	(	rats_t	node,
		const char *	peer_id_hex,
		const char *	type,
		const char *	json
	)

Send/broadcast a JSON message.

json must be valid JSON text (invalid → RATS_ERR_INVALID_ARG).

◆ rats_set_log_file()

void rats_set_log_file ( const char * path )

Mirror logs to path (NULL/empty disables file logging).

◆ rats_set_log_level()

void rats_set_log_level ( rats_log_level_t level )

◆ rats_set_max_peers()

void rats_set_max_peers	(	rats_t	node,
		size_t	max_peers
	)

Cap on established peers (0 = unlimited).

Guards inbound; our dials are honored. May be set before or after start().

◆ rats_start()

rats_error_t rats_start ( rats_t node )

◆ rats_stop()

void rats_stop ( rats_t node )

◆ rats_string_free()

void rats_string_free ( char * str )

◆ rats_subscribe()

rats_error_t rats_subscribe	(	rats_t	node,
		const char *	topic,
		rats_topic_cb	cb,
		void *	user
	)

Subscribe to topic; matching messages invoke cb on a reactor thread.

◆ rats_unsubscribe()

rats_error_t rats_unsubscribe	(	rats_t	node,
		const char *	topic
	)

◆ rats_version()

void rats_version	(	int *	major,
		int *	minor,
		int *	patch,
		int *	build
	)

Library version components.

Any out-pointer may be NULL.

◆ rats_version_string()

const char * rats_version_string ( void )

Library version as a static string, e.g.

"1.2.3" (do not free).

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ rats_file_complete_cb

◆ rats_file_offer_cb

◆ rats_file_progress_cb

◆ rats_json_cb

◆ rats_message_cb

◆ rats_peer_cb

◆ rats_t

◆ rats_topic_cb

Enumeration Type Documentation

◆ rats_error_t

◆ rats_log_level_t

◆ rats_security_t

Function Documentation

◆ rats_abi()

◆ rats_accept_file()

◆ rats_add_reconnect()

◆ rats_broadcast()

◆ rats_broadcast_json()

◆ rats_cancel_file()

◆ rats_config_default()

◆ rats_connect()

◆ rats_create()

◆ rats_create_config()

◆ rats_create_ex()

◆ rats_destroy()

◆ rats_enable_dht()

◆ rats_enable_file_transfer()

◆ rats_enable_json()

◆ rats_enable_mdns()

◆ rats_enable_ping()

◆ rats_enable_port_mapping()

◆ rats_enable_pubsub()

◆ rats_enable_reconnect()

◆ rats_error_str()

◆ rats_free_peer_ids()

◆ rats_git_describe()

◆ rats_listen_port()

◆ rats_local_id()

◆ rats_max_peers()

◆ rats_off_json()

◆ rats_on()

◆ rats_on_file_complete()

◆ rats_on_file_offer()

◆ rats_on_file_progress()

◆ rats_on_json()

◆ rats_on_peer_connected()

◆ rats_on_peer_disconnected()

◆ rats_once_json()

◆ rats_pause_file()

◆ rats_peer_count()

◆ rats_peer_ids()

◆ rats_peer_rtt_ms()

◆ rats_protocol_name()

◆ rats_protocol_version()

◆ rats_publish()

◆ rats_reject_file()

◆ rats_remove_reconnect()

◆ rats_resume_file()

◆ rats_send()

◆ rats_send_directory()

◆ rats_send_file()

◆ rats_send_json()

◆ rats_set_log_file()

◆ rats_set_log_level()

◆ rats_set_max_peers()

◆ rats_start()

◆ rats_stop()

◆ rats_string_free()

◆ rats_subscribe()

◆ rats_unsubscribe()

◆ rats_version()

◆ rats_version_string()