The C ABI over Node — what every language binding is built on. More...
#include "librats/util/rats_export.h"#include <stddef.h>#include <stdint.h>Go to the source code of this file.
Classes | |
| struct | rats_config_t |
| struct | rats_peer_info_t |
| struct | rats_path_stats_t |
| struct | rats_file_progress_t |
| struct | rats_bt_config_t |
Macros | |
| #define | RATS_ENUM_BASE |
| #define | RATS_TRANSPORT_MASK_TCP 0x1u |
| #define | RATS_TRANSPORT_MASK_UDP 0x2u |
| #define | RATS_FALLBACK_NEVER 0xFFFFFFFFu |
| #define | RATS_LIVE_MAX_LIFETIME_MS 30000u |
| #define | RATS_LIVE_MAX_PAYLOAD (4u * 1024u * 1024u) |
Typedefs | |
| typedef struct rats_node * | rats_t |
| typedef void(* | rats_peer_cb) (void *user, const char *peer_id) |
| typedef void(* | rats_disconnect_cb) (void *user, const char *peer_id, rats_close_reason_t reason) |
| typedef void(* | rats_dial_failed_cb) (void *user, const char *address) |
| typedef void(* | rats_message_cb) (void *user, const char *peer_id, const void *data, size_t len) |
| typedef void(* | rats_path_cb) (void *user, const char *peer_id, const rats_path_stats_t *stats) |
| typedef void(* | rats_topic_cb) (void *user, const char *peer_id, const char *topic, const void *data, size_t len) |
| typedef void(* | rats_json_cb) (void *user, const char *peer_id, const char *json) |
| typedef void(* | rats_file_offer_cb) (void *user, const char *peer_id, uint64_t transfer_id, const char *name, uint64_t size, int is_directory) |
| typedef void(* | rats_file_progress_cb) (void *user, const rats_file_progress_t *progress) |
| typedef void(* | rats_file_complete_cb) (void *user, const char *peer_id, uint64_t transfer_id, int success, const char *path) |
Functions | |
| const char * | rats_error_str (rats_error_t err) |
| Static name of an error code, e.g. | |
| const char * | rats_close_reason_str (rats_close_reason_t reason) |
| Static name of a close reason, e.g. | |
| rats_t | rats_create (const rats_config_t *config) |
| Create a node. | |
| void | rats_destroy (rats_t node) |
| Stop the node if running and free it. | |
| rats_error_t | rats_start (rats_t node) |
| Open the sockets, start the I/O threads and every enabled subsystem. | |
| void | rats_stop (rats_t node) |
| Close every connection and stop. | |
| const char * | rats_local_id (rats_t node) |
| Our peer id as hex. | |
| const char * | rats_protocol (rats_t node) |
| The protocol bound into the handshake. | |
| uint16_t | rats_listen_port (rats_t node) |
| The bound listen port (the real one when 0 was asked for); 0 before start. | |
| uint32_t | rats_transports (rats_t node) |
| Transports actually running, as RATS_TRANSPORT_MASK_* bits. | |
| rats_nat_mapping_t | rats_nat_mapping (rats_t node) |
| What the mesh has shown about this node's NAT, from where UDP peers report seeing its socket. | |
| char ** | rats_observed_addresses (rats_t node, size_t *count) |
| Our own addresses as peers report seeing us ("ip:port", our listen port). | |
| rats_error_t | rats_connect (rats_t node, const char *host, uint16_t port) |
| Dial host:port (a literal or a hostname). | |
| rats_error_t | rats_disconnect (rats_t node, const char *peer_id) |
| Close the connection to a peer. | |
| size_t | rats_peer_count (rats_t node) |
| char ** | rats_peer_ids (rats_t node, size_t *count) |
| Ids of the connected peers: an array of *count strings, NULL when there are none. | |
| rats_error_t | rats_peer_info (rats_t node, const char *peer_id, rats_peer_info_t *out) |
| Fill out for a connected peer. | |
| 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, const char *channel, const void *data, size_t len, uint32_t lifetime_ms) |
| Queue bytes for one peer on a named channel. | |
| rats_error_t | rats_broadcast (rats_t node, const char *channel, const void *data, size_t len, uint32_t lifetime_ms) |
| rats_send() to every connected peer. | |
| int | rats_peer_writable (rats_t node, const char *peer_id) |
| 1 while the peer's send queue has room, 0 when it does not or the peer is not connected. | |
| rats_error_t | rats_path_stats (rats_t node, const char *peer_id, rats_path_stats_t *out) |
| The latest path sample for a peer. | |
| 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_disconnect_cb cb, void *user) |
| rats_error_t | rats_on_dial_failed (rats_t node, rats_dial_failed_cb cb, void *user) |
| A dial to a numeric address failed over every transport tried — one made by rats_connect() or by a discovery subsystem. | |
| rats_error_t | rats_on_peer_writable (rats_t node, rats_peer_cb cb, void *user) |
| A peer whose queue had filled has drained back under its mark. | |
| rats_error_t | rats_on_peer_path (rats_t node, rats_path_cb cb, void *user) |
| A path sample of every connected peer, every path_sample_ms (100 ms if 0). | |
| rats_error_t | rats_on (rats_t node, const char *channel, rats_message_cb cb, void *user) |
| Messages arriving on a named channel. | |
| rats_error_t | rats_enable_dht (rats_t node, uint16_t dht_port, const char *discovery_key) |
| Mainline DHT: announce and search a key, dialing the peers found. | |
| rats_error_t | rats_enable_mdns (rats_t node) |
| mDNS discovery on the local network. | |
| rats_error_t | rats_enable_peer_exchange (rats_t node) |
| Peer exchange: connected peers trade the addresses of peers they hold, so a node needs one contact to find the rest of the mesh. | |
| rats_error_t | rats_enable_port_mapping (rats_t node, int upnp, int natpmp) |
| Ask the router to forward the listen port, over UPnP IGD and/or NAT-PMP (non-zero enables each; both run in parallel). | |
| rats_error_t | rats_enable_hole_punch (rats_t node, int serve_rendezvous) |
| UDP hole punching: reach a peer behind a NAT by having a peer both sides share arrange for the two to dial each other at the same moment. | |
| rats_error_t | rats_punch_peer (rats_t node, const char *peer_id) |
| Start punching to a peer. | |
| rats_error_t | rats_enable_relay (rats_t node, int serve) |
| Relaying: reach a peer nothing else can, through a node both ends are connected to. | |
| rats_error_t | rats_connect_via_relay (rats_t node, const char *peer_id) |
| Start a relayed connection to a peer. | |
| rats_error_t | rats_enable_pubsub (rats_t node) |
| Enable before start. | |
| rats_error_t | rats_subscribe (rats_t node, const char *topic, rats_topic_cb cb, void *user) |
| Subscribe to a topic; one handler per topic, a second subscribe replaces it. | |
| 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 to every subscriber of the topic. | |
| rats_error_t | rats_enable_json (rats_t node) |
| Enable before start. | |
| rats_error_t | rats_on_json (rats_t node, const char *type, rats_json_cb cb, void *user) |
| Add a handler for 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(); the handler is removed after its first message. | |
| rats_error_t | rats_off_json (rats_t node, const char *type) |
| Remove every handler of type. | |
| rats_error_t | rats_send_json (rats_t node, const char *peer_id, const char *type, const char *json) |
| json must be valid JSON text (else RATS_ERR_INVALID_ARG). | |
| 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 before start. | |
| 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) |
| rats_error_t | rats_send_file (rats_t node, const char *peer_id, const char *path, uint64_t *transfer_id) |
| Offer a file or a directory tree to a connected peer; the transfer id is written to *transfer_id (which may be NULL). | |
| rats_error_t | rats_send_directory (rats_t node, const char *peer_id, const char *path, uint64_t *transfer_id) |
| rats_error_t | rats_accept_file (rats_t node, const char *peer_id, uint64_t transfer_id, const char *dest_path) |
| Answer an offer. | |
| rats_error_t | rats_reject_file (rats_t node, const char *peer_id, uint64_t transfer_id) |
| rats_error_t | rats_cancel_file (rats_t node, const char *peer_id, uint64_t transfer_id) |
| Control a running transfer from either side. | |
| rats_error_t | rats_pause_file (rats_t node, const char *peer_id, uint64_t transfer_id) |
| rats_error_t | rats_resume_file (rats_t node, const char *peer_id, uint64_t transfer_id) |
| rats_error_t | rats_enable_ping (rats_t node) |
| Enable before start. | |
| int64_t | rats_peer_rtt_ms (rats_t node, const char *peer_id) |
| Last measured round trip to a peer in ms; -1 if unknown (ping not enabled, no answer yet). | |
| rats_error_t | rats_enable_reconnect (rats_t node) |
| Re-dial dropped peers with exponential backoff. | |
| rats_error_t | rats_add_reconnect (rats_t node, const char *host, uint16_t port) |
| Keep an address connected. | |
| rats_error_t | rats_remove_reconnect (rats_t node, const char *host, uint16_t port) |
| Stop keeping an address connected and forget it. | |
| rats_error_t | rats_enable_reconnect_lost (rats_t node, uint32_t lost_for_ms) |
| rats_enable_reconnect(), and a peer lost — its connection closed by neither side: gone quiet past the idle timeout, or stopped answering — dialed again where it was last known for lost_for_ms, until it is back over any route. | |
| rats_error_t | rats_enable_bittorrent (rats_t node, const rats_bt_config_t *config) |
| Enable before start. | |
| rats_error_t | rats_bt_add_magnet (rats_t node, const char *magnet_uri, const char *save_path) |
| Start a download from a magnet link (metadata is fetched from peers). | |
| rats_error_t | rats_bt_add_torrent_file (rats_t node, const char *torrent_path, const char *save_path) |
| Start a download from a .torrent file. | |
| rats_error_t | rats_bt_remove_torrent (rats_t node, const char *info_hash_hex) |
| Remove a torrent by its 40-char hex info-hash. | |
| void | rats_set_log_level (rats_log_level_t level) |
| void | rats_set_log_file (const char *path) |
| Also write logs to path; NULL or "" stops file logging. | |
| const char * | rats_version_string (void) |
| Library version with the build number, e.g. | |
| void | rats_version (int *major, int *minor, int *patch, int *build) |
| Version components; any pointer may be NULL. | |
| const char * | rats_git_describe (void) |
| git describe of the build, e.g. | |
| uint32_t | rats_abi (void) |
| (major << 16) | (minor << 8) | patch. | |
| void | rats_strings_free (char **strings, size_t count) |
| Free an array from rats_peer_ids() / rats_observed_addresses(). | |
The C ABI over Node — what every language binding is built on.
A rats_t is an opaque handle to one node. Peer ids cross the ABI as 64-char lowercase hex of the peer's self-certifying PeerId.
Configuration: rats_config_t is zero-initialisable — every field's zero is the library default — so rats_config_t cfg = {0}; (or a designated initialiser naming only what you change) is a complete config, and rats_create(NULL) is a node with all defaults.
Errors: a fallible call returns rats_error_t, RATS_OK (0) on success; rats_error_str() names a code. Sending is asynchronous: RATS_OK from rats_send()/rats_publish() means the message was queued, not that it arrived.
Subsystems are opt-in. Discovery, NAT traversal, pub/sub, JSON messaging, file transfer, ping and reconnection each need their rats_enable_*() BEFORE rats_start(). Using one that was not enabled returns RATS_ERR_NOT_ENABLED; enabling after start returns RATS_ERR_ALREADY_STARTED.
Threading: every call may be made from any thread. Callbacks run on an internal reactor thread — keep them short and never block in them. Register them before rats_start(); the node-level ones refuse afterwards (RATS_ERR_ALREADY_STARTED). Strings and structs handed to a callback are valid only for the duration of the call.
Memory: the string arrays rats_peer_ids() and rats_observed_addresses() return are released with rats_strings_free(). Every const char* the library returns is its own and must not be freed.
Definition in file rats.h.
| typedef void(* rats_dial_failed_cb) (void *user, const char *address) |
| typedef void(* rats_disconnect_cb) (void *user, const char *peer_id, rats_close_reason_t reason) |
| typedef void(* rats_file_complete_cb) (void *user, const char *peer_id, uint64_t transfer_id, int success, const char *path) |
| typedef void(* rats_file_offer_cb) (void *user, const char *peer_id, uint64_t transfer_id, const char *name, uint64_t size, int is_directory) |
| typedef void(* rats_file_progress_cb) (void *user, const rats_file_progress_t *progress) |
| typedef void(* rats_json_cb) (void *user, const char *peer_id, const char *json) |
| typedef void(* rats_message_cb) (void *user, const char *peer_id, const void *data, size_t len) |
| typedef void(* rats_path_cb) (void *user, const char *peer_id, const rats_path_stats_t *stats) |
| typedef void(* rats_peer_cb) (void *user, const char *peer_id) |
| typedef void(* rats_topic_cb) (void *user, const char *peer_id, const char *topic, const void *data, size_t len) |
| enum rats_bt_encryption_t |
| enum rats_close_reason_t |
| enum rats_congestion_t |
| enum rats_direction_t |
| enum rats_error_t |
| enum rats_file_status_t |
| enum rats_log_level_t |
| enum rats_nat_mapping_t |
| enum rats_security_t |
| enum rats_transport_t |
| uint32_t rats_abi | ( | void | ) |
(major << 16) | (minor << 8) | patch.
| rats_error_t rats_accept_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| uint64_t | transfer_id, | ||
| const char * | dest_path ) |
Answer an offer.
dest_path is the file to write for a file, the directory to fill for a directory.
| rats_error_t rats_add_reconnect | ( | rats_t | node, |
| const char * | host, | ||
| uint16_t | port ) |
Keep an address connected.
May be called while running.
| rats_error_t rats_broadcast | ( | rats_t | node, |
| const char * | channel, | ||
| const void * | data, | ||
| size_t | len, | ||
| uint32_t | lifetime_ms ) |
rats_send() to every connected peer.
| rats_error_t rats_broadcast_json | ( | rats_t | node, |
| const char * | type, | ||
| const char * | json ) |
| rats_error_t rats_bt_add_magnet | ( | rats_t | node, |
| const char * | magnet_uri, | ||
| const char * | save_path ) |
Start a download from a magnet link (metadata is fetched from peers).
| rats_error_t rats_bt_add_torrent_file | ( | rats_t | node, |
| const char * | torrent_path, | ||
| const char * | save_path ) |
Start a download from a .torrent file.
| rats_error_t rats_bt_remove_torrent | ( | rats_t | node, |
| const char * | info_hash_hex ) |
Remove a torrent by its 40-char hex info-hash.
Downloaded files are kept.
| rats_error_t rats_cancel_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| uint64_t | transfer_id ) |
Control a running transfer from either side.
RATS_ERR_NOT_FOUND if there is no such transfer.
| const char * rats_close_reason_str | ( | rats_close_reason_t | reason | ) |
Static name of a close reason, e.g.
"RATS_CLOSE_SLOW_CONSUMER" (never NULL).
| rats_error_t rats_connect | ( | rats_t | node, |
| const char * | host, | ||
| uint16_t | port ) |
Dial host:port (a literal or a hostname).
Non-blocking: success arrives as rats_on_peer_connected, failure as rats_on_dial_failed.
| rats_error_t rats_connect_via_relay | ( | rats_t | node, |
| const char * | peer_id ) |
Start a relayed connection to a peer.
Success arrives as rats_on_peer_connected. RATS_ERR_DECLINED: already connected, already trying or cooling down, or no connected peer could carry it.
| rats_t rats_create | ( | const rats_config_t * | config | ) |
Create a node.
config may be NULL for all defaults. Returns NULL when the config is invalid: no transport, an out-of-range enum, or TCP preferred while turned off. With a data_dir the identity is loaded from it, or created and saved there. No socket is opened until rats_start().
| void rats_destroy | ( | rats_t | node | ) |
Stop the node if running and free it.
The handle is invalid afterwards.
| rats_error_t rats_disconnect | ( | rats_t | node, |
| const char * | peer_id ) |
Close the connection to a peer.
RATS_ERR_NO_SUCH_PEER if it is not connected.
| rats_error_t rats_enable_bittorrent | ( | rats_t | node, |
| const rats_bt_config_t * | config ) |
Enable before start.
config may be NULL for the defaults.
| rats_error_t rats_enable_dht | ( | rats_t | node, |
| uint16_t | dht_port, | ||
| const char * | discovery_key ) |
Mainline DHT: announce and search a key, dialing the peers found.
dht_port 0 is ephemeral. discovery_key NULL → the node's protocol, so only nodes that could handshake find each other.
| rats_error_t rats_enable_file_transfer | ( | rats_t | node, |
| const char * | temp_dir ) |
Enable before start.
temp_dir holds partial downloads (NULL → ".").
| rats_error_t rats_enable_hole_punch | ( | rats_t | node, |
| int | serve_rendezvous ) |
UDP hole punching: reach a peer behind a NAT by having a peer both sides share arrange for the two to dial each other at the same moment.
Every node involved needs it enabled. serve_rendezvous non-zero also passes other peers' rendezvous along — a few dozen bytes per punch; a mesh where nobody does this cannot punch.
| rats_error_t rats_enable_json | ( | rats_t | node | ) |
Enable before start.
| rats_error_t rats_enable_mdns | ( | rats_t | node | ) |
mDNS discovery on the local network.
| rats_error_t rats_enable_peer_exchange | ( | rats_t | node | ) |
Peer exchange: connected peers trade the addresses of peers they hold, so a node needs one contact to find the rest of the mesh.
| rats_error_t rats_enable_ping | ( | rats_t | node | ) |
Enable before start.
| rats_error_t rats_enable_port_mapping | ( | rats_t | node, |
| int | upnp, | ||
| int | natpmp ) |
Ask the router to forward the listen port, over UPnP IGD and/or NAT-PMP (non-zero enables each; both run in parallel).
| rats_error_t rats_enable_pubsub | ( | rats_t | node | ) |
Enable before start.
| rats_error_t rats_enable_reconnect | ( | rats_t | node | ) |
Re-dial dropped peers with exponential backoff.
Every address dialed is remembered; with a data_dir the list survives restarts (peers.json). Enable before start — a node without it never redials on its own.
| rats_error_t rats_enable_reconnect_lost | ( | rats_t | node, |
| uint32_t | lost_for_ms ) |
rats_enable_reconnect(), and a peer lost — its connection closed by neither side: gone quiet past the idle timeout, or stopped answering — dialed again where it was last known for lost_for_ms, until it is back over any route.
A peer that left is not. Enable before start, instead of rats_enable_reconnect().
| rats_error_t rats_enable_relay | ( | rats_t | node, |
| int | serve ) |
Relaying: reach a peer nothing else can, through a node both ends are connected to.
Encryption stays end to end; rats_peer_info() reports RATS_TRANSPORT_RELAY. serve non-zero also carries OTHER peers' connections, which costs this node their bandwidth (each circuit is capped by bytes, time and count). With hole punching enabled too, a punch that cannot work falls back to a relay by itself, and a relayed peer is upgraded to a direct connection when a punch later succeeds.
| const char * rats_error_str | ( | rats_error_t | err | ) |
Static name of an error code, e.g.
"RATS_ERR_NO_SUCH_PEER" (never NULL).
| const char * rats_git_describe | ( | void | ) |
git describe of the build, e.g.
"v1.2.3-4-gabcdef".
| uint16_t rats_listen_port | ( | rats_t | node | ) |
The bound listen port (the real one when 0 was asked for); 0 before start.
| const char * rats_local_id | ( | rats_t | node | ) |
Our peer id as hex.
Owned by the node, valid until rats_destroy().
| size_t rats_max_peers | ( | rats_t | node | ) |
| rats_nat_mapping_t rats_nat_mapping | ( | rats_t | node | ) |
What the mesh has shown about this node's NAT, from where UDP peers report seeing its socket.
| char ** rats_observed_addresses | ( | rats_t | node, |
| size_t * | count ) |
Our own addresses as peers report seeing us ("ip:port", our listen port).
Returns an array of *count strings, NULL when there are none; release with rats_strings_free().
| rats_error_t rats_off_json | ( | rats_t | node, |
| const char * | type ) |
Remove every handler of type.
| rats_error_t rats_on | ( | rats_t | node, |
| const char * | channel, | ||
| rats_message_cb | cb, | ||
| void * | user ) |
Messages arriving on a named channel.
| rats_error_t rats_on_dial_failed | ( | rats_t | node, |
| rats_dial_failed_cb | cb, | ||
| void * | user ) |
A dial to a numeric address failed over every transport tried — one made by rats_connect() or by a discovery subsystem.
address is "ip:port"; a dial by hostname is not reported.
| rats_error_t rats_on_file_complete | ( | rats_t | node, |
| rats_file_complete_cb | cb, | ||
| void * | user ) |
| 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_json | ( | rats_t | node, |
| const char * | type, | ||
| rats_json_cb | cb, | ||
| void * | user ) |
Add a handler for messages of type.
May be called while running.
| 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_disconnect_cb | cb, | ||
| void * | user ) |
| rats_error_t rats_on_peer_path | ( | rats_t | node, |
| rats_path_cb | cb, | ||
| void * | user ) |
A path sample of every connected peer, every path_sample_ms (100 ms if 0).
Registering one turns sampling on. Runs once per peer per interval.
| rats_error_t rats_on_peer_writable | ( | rats_t | node, |
| rats_peer_cb | cb, | ||
| void * | user ) |
A peer whose queue had filled has drained back under its mark.
| rats_error_t rats_once_json | ( | rats_t | node, |
| const char * | type, | ||
| rats_json_cb | cb, | ||
| void * | user ) |
Like rats_on_json(); the handler is removed after its first message.
| rats_error_t rats_path_stats | ( | rats_t | node, |
| const char * | peer_id, | ||
| rats_path_stats_t * | out ) |
The latest path sample for a peer.
RATS_ERR_NO_SUCH_PEER if the peer is not connected or nothing was sampled yet (sampling runs only with path_sample_ms set or a rats_on_peer_path() callback registered).
| rats_error_t rats_pause_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| uint64_t | transfer_id ) |
| size_t rats_peer_count | ( | rats_t | node | ) |
| char ** rats_peer_ids | ( | rats_t | node, |
| size_t * | count ) |
Ids of the connected peers: an array of *count strings, NULL when there are none.
Release with rats_strings_free().
| rats_error_t rats_peer_info | ( | rats_t | node, |
| const char * | peer_id, | ||
| rats_peer_info_t * | out ) |
Fill out for a connected peer.
RATS_ERR_NO_SUCH_PEER if not connected.
| int64_t rats_peer_rtt_ms | ( | rats_t | node, |
| const char * | peer_id ) |
Last measured round trip to a peer in ms; -1 if unknown (ping not enabled, no answer yet).
| int rats_peer_writable | ( | rats_t | node, |
| const char * | peer_id ) |
1 while the peer's send queue has room, 0 when it does not or the peer is not connected.
0 means stop: what you sent was queued, but keep adding and the peer is dropped with RATS_CLOSE_SLOW_CONSUMER. Resume on rats_on_peer_writable(), or poll this from a thread of your own. It counts bytes just handed to rats_send() too, so asking right after a send is exact.
| const char * rats_protocol | ( | rats_t | node | ) |
The protocol bound into the handshake.
Owned by the node, valid until rats_destroy().
| rats_error_t rats_publish | ( | rats_t | node, |
| const char * | topic, | ||
| const void * | data, | ||
| size_t | len ) |
Publish to every subscriber of the topic.
| rats_error_t rats_punch_peer | ( | rats_t | node, |
| const char * | peer_id ) |
Start punching to a peer.
Success arrives as rats_on_peer_connected. RATS_ERR_DECLINED: already connected, already punching, or no external endpoint of our own known yet (that takes at least one UDP peer).
| rats_error_t rats_reject_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| uint64_t | transfer_id ) |
| rats_error_t rats_remove_reconnect | ( | rats_t | node, |
| const char * | host, | ||
| uint16_t | port ) |
Stop keeping an address connected and forget it.
| rats_error_t rats_resume_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| uint64_t | transfer_id ) |
| rats_error_t rats_send | ( | rats_t | node, |
| const char * | peer_id, | ||
| const char * | channel, | ||
| const void * | data, | ||
| size_t | len, | ||
| uint32_t | lifetime_ms ) |
Queue bytes for one peer on a named channel.
RATS_ERR_NO_SUCH_PEER if the peer is not connected.
lifetime_ms 0 is reliable: the message arrives, in order with everything else this node sends on its channels. Non-zero makes it a live message, worth delivering only within that many ms of this call: repaired while it can still arrive in time, dropped whole once it cannot, never delivered partly or twice, and ordered with nothing (number them if order matters). Made for audio and video frames. The receiver needs nothing special — it arrives at rats_on() like any message.
If you send in bulk, ask rats_peer_writable() after each send: that is the only warning before the peer is dropped as a slow consumer.
| rats_error_t rats_send_directory | ( | rats_t | node, |
| const char * | peer_id, | ||
| const char * | path, | ||
| uint64_t * | transfer_id ) |
| rats_error_t rats_send_file | ( | rats_t | node, |
| const char * | peer_id, | ||
| const char * | path, | ||
| uint64_t * | transfer_id ) |
Offer a file or a directory tree to a connected peer; the transfer id is written to *transfer_id (which may be NULL).
RATS_ERR_NO_SUCH_PEER if the peer is not connected, RATS_ERR_NOT_FOUND if the path cannot be read.
| rats_error_t rats_send_json | ( | rats_t | node, |
| const char * | peer_id, | ||
| const char * | type, | ||
| const char * | json ) |
json must be valid JSON text (else RATS_ERR_INVALID_ARG).
| void rats_set_log_file | ( | const char * | path | ) |
Also write logs to path; NULL or "" stops file logging.
| void rats_set_log_level | ( | rats_log_level_t | level | ) |
| void rats_set_max_peers | ( | rats_t | node, |
| size_t | max_peers ) |
Cap on established peers (0 = unlimited).
Can be changed while running.
| rats_error_t rats_start | ( | rats_t | node | ) |
Open the sockets, start the I/O threads and every enabled subsystem.
RATS_ERR_ALREADY_STARTED, or RATS_ERR_BIND if the listen port is taken.
| void rats_stop | ( | rats_t | node | ) |
Close every connection and stop.
Idempotent.
| void rats_strings_free | ( | char ** | strings, |
| size_t | count ) |
Free an array from rats_peer_ids() / rats_observed_addresses().
NULL is a no-op.
| rats_error_t rats_subscribe | ( | rats_t | node, |
| const char * | topic, | ||
| rats_topic_cb | cb, | ||
| void * | user ) |
Subscribe to a topic; one handler per topic, a second subscribe replaces it.
| uint32_t rats_transports | ( | rats_t | node | ) |
Transports actually running, as RATS_TRANSPORT_MASK_* bits.
Can be narrower than the config asked for: a UDP socket that cannot be bound leaves the node TCP-only rather than failing to start. 0 when not running.
| rats_error_t rats_unsubscribe | ( | rats_t | node, |
| const char * | topic ) |
| void rats_version | ( | int * | major, |
| int * | minor, | ||
| int * | patch, | ||
| int * | build ) |
Version components; any pointer may be NULL.
| const char * rats_version_string | ( | void | ) |
Library version with the build number, e.g.
"2.3.7.884".