The canonical C ABI over Node — the foundation for all language bindings. 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 |
| Full node configuration. More... | |
Macros | |
| #define | RATS_TRANSPORT_MASK_TCP 0x1u |
| #define | RATS_TRANSPORT_MASK_UDP 0x2u |
Typedefs | |
| typedef void * | rats_t |
| typedef void(* | rats_peer_cb) (void *user, const char *peer_id_hex) |
| typedef void(* | rats_peer_disconnect_cb) (void *user, const char *peer_id_hex, rats_close_reason_t reason) |
| 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, const char *peer_id_hex, int success, const char *path) |
Functions | |
| const char * | rats_close_reason_str (rats_close_reason_t reason) |
| Static human-readable name for a close reason (never NULL, never freed). | |
| 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) |
| uint32_t | rats_transports (rats_t node) |
| Transports this node is actually running, as a RATS_TRANSPORT_MASK_* bitmask. | |
| char * | rats_local_id (rats_t node) |
| Our self-certifying peer id as hex. | |
| char * | rats_protocol (rats_t node) |
| Application protocol identity bound into the handshake (see rats_config_t). | |
| 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) |
| 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) |
| int | rats_peer_writable (rats_t node, const char *peer_id_hex) |
| Whether this peer's send queue still has room — the same question rats_send() answers, asked without sending. | |
| 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_disconnect_cb cb, void *user) |
| rats_error_t | rats_on_peer_writable (rats_t node, rats_peer_cb cb, void *user) |
| "This peer can be written to again" — fired when a peer whose queue had filled past its mark has drained back under it. | |
| 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). | |
| rats_error_t | rats_enable_hole_punch (rats_t node, int serve_as_relay) |
| UDP hole punching: reach a peer that no port forwarding made reachable, by arranging with a peer both sides already have that the two dial each other at the same moment. | |
| rats_error_t | rats_punch_peer (rats_t node, const char *peer_id_hex) |
Try to reach peer_id_hex by punching. | |
| rats_error_t | rats_enable_relay (rats_t node, int serve_as_relay) |
| Relaying: reach a peer that neither port forwarding nor hole punching could make reachable, by routing the connection through a node both ends are already connected to. | |
| rats_error_t | rats_connect_via_relay (rats_t node, const char *peer_id_hex) |
Try to reach peer_id_hex through a relay. | |
| int | rats_nat_mapping (rats_t node) |
| What the mesh has shown about this node's own NAT, from the endpoints datagram peers report seeing its shared UDP socket at. | |
| 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) |
| int | rats_peer_transport (rats_t node, const char *peer_id_hex) |
| Which transport a connected peer's link runs on, or -1 if not connected. | |
| int | rats_peer_transports (rats_t node, const char *peer_id_hex) |
| Transports a connected peer advertised in its identify message, as a RATS_TRANSPORT_MASK_* bitmask. | |
| 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. | |
| rats_error_t | rats_enable_bittorrent (rats_t node, uint16_t listen_port, const char *download_path) |
| Enable BitTorrent. | |
| rats_error_t | rats_bt_set_encryption (rats_t node, rats_bt_enc_policy_t out_policy, rats_bt_enc_policy_t in_policy) |
| Set the BitTorrent encryption policy. | |
| rats_error_t | rats_bt_set_utp (rats_t node, int enable_outgoing, int enable_incoming) |
| Turn uTP (BEP 29) on or off, per direction. | |
| rats_error_t | rats_bt_add_magnet (rats_t node, const char *magnet_uri, const char *save_path) |
| Start downloading 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 torrent from a .torrent file on disk. | |
| 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). | |
| 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) |
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 void(* rats_file_complete_cb) (void *user, uint64_t transfer_id, const char *peer_id_hex, int success, const char *path) |
| 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_json_cb) (void *user, const char *peer_id_hex, const char *json) |
| typedef void(* rats_message_cb) (void *user, const char *peer_id_hex, const void *data, size_t len) |
| typedef void(* rats_peer_cb) (void *user, const char *peer_id_hex) |
| typedef void(* rats_peer_disconnect_cb) (void *user, const char *peer_id_hex, rats_close_reason_t reason) |
| typedef void(* rats_topic_cb) (void *user, const char *peer_id_hex, const char *topic, const void *data, size_t len) |
| anonymous enum |
| enum rats_bt_enc_policy_t |
| enum rats_close_reason_t |
| enum rats_error_t |
| enum rats_log_level_t |
| enum rats_security_t |
| enum rats_transport_t |
| uint32_t rats_abi | ( | void | ) |
Packed ABI id as (major<<16)|(minor<<8)|patch — MAJOR bumps on breaking changes, MINOR on additive ones.
| 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_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_error_t rats_broadcast | ( | rats_t | node, |
| const char * | channel, | ||
| const void * | data, | ||
| size_t | len | ||
| ) |
| 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 downloading 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 torrent from a .torrent file on disk.
| 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_bt_set_encryption | ( | rats_t | node, |
| rats_bt_enc_policy_t | out_policy, | ||
| rats_bt_enc_policy_t | in_policy | ||
| ) |
Set the BitTorrent encryption policy.
Optional — the default (ENABLED for both) already dials obfuscated first, which is what reaches the large part of the swarm that refuses plaintext. Must be called BEFORE rats_enable_bittorrent, since the policy is fixed when the session is created.
| rats_error_t rats_bt_set_utp | ( | rats_t | node, |
| int | enable_outgoing, | ||
| int | enable_incoming | ||
| ) |
Turn uTP (BEP 29) on or off, per direction.
Optional — both are on by default, which is what every modern client ships: uTP's delay-based congestion control yields to other traffic instead of saturating the user's uplink, and much of the swarm answers UDP more readily than TCP. A peer with no uTP costs one connect timeout before the dial falls back to TCP, and is remembered.
Pass non-zero to enable each direction. Turning outgoing uTP off makes every dial TCP. Turning incoming off still dials out over uTP but never answers, which is what a blocked inbound UDP port looks like anyway. Must be called BEFORE rats_enable_bittorrent, since the setting is fixed when the session is created.
| 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.
| const char * rats_close_reason_str | ( | rats_close_reason_t | reason | ) |
Static human-readable name for a close reason (never NULL, never freed).
| 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_error_t rats_connect | ( | rats_t | node, |
| const char * | host, | ||
| uint16_t | port | ||
| ) |
| rats_error_t rats_connect_via_relay | ( | rats_t | node, |
| const char * | peer_id_hex | ||
| ) |
Try to reach peer_id_hex through a relay.
Non-blocking: success arrives as an ordinary peer-connected callback. RATS_OK if an attempt was started; RATS_ERR_NOT_ENABLED if relaying is off; RATS_ERR_NO_SUCH_PEER if there is nothing to do or nothing to try with — the peer is already connected, an attempt is already running, it is in cooldown, or this node has no peer that could carry the connection.
Usually there is no need to call this: with hole punching enabled too, a punch that cannot work hands the target over by itself.
| rats_t rats_create | ( | uint16_t | listen_port | ) |
Create a listening node (Noise, dual-stack, ephemeral identity, port 0 = ephemeral).
| 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_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().
| void rats_destroy | ( | rats_t | node | ) |
| rats_error_t rats_enable_bittorrent | ( | rats_t | node, |
| uint16_t | listen_port, | ||
| const char * | download_path | ||
| ) |
Enable BitTorrent.
listen_port 0 picks an ephemeral port; download_path is the default save directory (NULL = "."). Enable DHT first to share the node's 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 → the node's protocol, so only same-protocol peers discover each other).
| 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_error_t rats_enable_hole_punch | ( | rats_t | node, |
| int | serve_as_relay | ||
| ) |
UDP hole punching: reach a peer that no port forwarding made reachable, by arranging with a peer both sides already have that the two dial each other at the same moment.
Call before start(); both punching nodes must have it enabled, and so must the node that carries the rendezvous between them.
serve_as_relay (non-zero) also carries other peers' rendezvous — a few dozen forwarded bytes per punch, only ever to peers this node already holds. A mesh in which nobody relays cannot punch at all.
| rats_error_t rats_enable_json | ( | rats_t | node | ) |
Enable the JSON-messaging subsystem (the C view of MessageJson).
Call before start().
| rats_error_t rats_enable_mdns | ( | rats_t | node | ) |
Local-network mDNS discovery.
| rats_error_t rats_enable_ping | ( | rats_t | node | ) |
Enable periodic ping/pong RTT probing of every peer.
Call before start().
| 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_error_t rats_enable_pubsub | ( | rats_t | node | ) |
Enable the pub/sub (GossipSub) subsystem.
Call before start().
| 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.json" across restarts. Call before start(). A bare node never reconnects on its own.
| rats_error_t rats_enable_relay | ( | rats_t | node, |
| int | serve_as_relay | ||
| ) |
Relaying: reach a peer that neither port forwarding nor hole punching could make reachable, by routing the connection through a node both ends are already connected to.
Call before start(). The peer that comes out is ordinary in every way — the same end-to-end encryption, the same channels — except that its bytes take a detour, which rats_peer_transport() reports as RATS_TRANSPORT_RELAY.
serve_as_relay (non-zero) also carries OTHER peers' connections. Unlike a hole-punch rendezvous, that spends real bandwidth on somebody else's traffic, so it is off by default and opted into here; a mesh in which nobody serves cannot relay at all. A serving node forwards only between peers it already holds, never chains circuits, and caps each one by bytes, duration and count.
| const char * rats_error_str | ( | rats_error_t | err | ) |
Static human-readable name of an error code (do not free).
| void rats_free_peer_ids | ( | char ** | ids, |
| size_t | count | ||
| ) |
| const char * rats_git_describe | ( | void | ) |
Git describe of the build, e.g.
"v1.2.3-4-gabcdef" (static; do not free).
| uint16_t rats_listen_port | ( | rats_t | node | ) |
| char * rats_local_id | ( | rats_t | node | ) |
Our self-certifying peer id as hex.
Caller frees with rats_string_free().
| size_t rats_max_peers | ( | rats_t | node | ) |
| int rats_nat_mapping | ( | rats_t | node | ) |
What the mesh has shown about this node's own NAT, from the endpoints datagram peers report seeing its shared UDP socket at.
One of the RATS_NAT_* values; RATS_NAT_ENDPOINT_DEPENDENT means punching cannot work from here.
| rats_error_t rats_off_json | ( | rats_t | node, |
| const char * | type | ||
| ) |
| rats_error_t rats_on | ( | rats_t | node, |
| const char * | channel, | ||
| rats_message_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_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 | ||
| ) |
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_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_disconnect_cb | cb, | ||
| void * | user | ||
| ) |
| rats_error_t rats_on_peer_writable | ( | rats_t | node, |
| rats_peer_cb | cb, | ||
| void * | user | ||
| ) |
"This peer can be written to again" — fired when a peer whose queue had filled past its mark has drained back under it.
The other half of rats_send() reporting 0; an application that never asks never needs this.
| 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_pause_file | ( | rats_t | node, |
| const char * | peer_id_hex, | ||
| uint64_t | transfer_id | ||
| ) |
| size_t rats_peer_count | ( | rats_t | node | ) |
| 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.
| 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).
| int rats_peer_transport | ( | rats_t | node, |
| const char * | peer_id_hex | ||
| ) |
Which transport a connected peer's link runs on, or -1 if not connected.
| int rats_peer_transports | ( | rats_t | node, |
| const char * | peer_id_hex | ||
| ) |
Transports a connected peer advertised in its identify message, as a RATS_TRANSPORT_MASK_* bitmask.
0 means the peer did not say (an older build), which is "no information", not "none". -1 if the peer is not connected.
| int rats_peer_writable | ( | rats_t | node, |
| const char * | peer_id_hex | ||
| ) |
Whether this peer's send queue still has room — the same question rats_send() answers, asked without sending.
Returns 1 for room, 0 for none (and 0 for a peer that is not connected).
A 0 says "stop". The message you just sent was queued like any other and nothing was dropped, but keep piling on and this peer is dropped with RATS_CLOSE_SLOW_CONSUMER. Wait for the callback registered with rats_on_peer_writable(), or poll this from a thread of your own.
Ask it right after rats_send(): the bytes you just handed over are already counted, so the answer covers your own send and not just what the reactor has got round to. It is NOT a size limit — a single message of any size is always accepted; only sending more on top of a full queue drops a peer.
| char * rats_protocol | ( | rats_t | node | ) |
Application protocol identity bound into the handshake (see rats_config_t).
Two nodes whose protocol differs cannot complete a handshake. Caller frees the returned string with rats_string_free().
| 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_punch_peer | ( | rats_t | node, |
| const char * | peer_id_hex | ||
| ) |
Try to reach peer_id_hex by punching.
Non-blocking: success arrives as an ordinary peer-connected callback. RATS_OK if a rendezvous was started; RATS_ERR_NOT_ENABLED if hole punching is off; RATS_ERR_NO_SUCH_PEER if there is nothing to do or nothing to try with — the peer is already connected, a punch to it is already running, or this node does not yet know an external endpoint of its own to advertise (it needs at least one datagram peer first).
| rats_error_t rats_reject_file | ( | rats_t | node, |
| const char * | peer_id_hex, | ||
| uint64_t | transfer_id | ||
| ) |
| 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_error_t rats_resume_file | ( | rats_t | node, |
| const char * | peer_id_hex, | ||
| uint64_t | transfer_id | ||
| ) |
| rats_error_t rats_send | ( | rats_t | node, |
| const char * | peer_id_hex, | ||
| const char * | channel, | ||
| const void * | data, | ||
| size_t | len | ||
| ) |
Queue bytes for one peer on a named channel.
RATS_OK means accepted and queued, never that it arrived. Pair it with rats_peer_writable() below if you send in bulk — that is the only way to learn you are outrunning the link before the peer is dropped for it.
| uint64_t rats_send_directory | ( | rats_t | node, |
| const char * | peer_id_hex, | ||
| const char * | dir_path | ||
| ) |
| 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_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).
| void rats_set_log_file | ( | const char * | path | ) |
Mirror logs to path (NULL/empty disables 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).
Guards inbound; our dials are honored. May be set before or after start().
| rats_error_t rats_start | ( | rats_t | node | ) |
| void rats_stop | ( | rats_t | node | ) |
| void rats_string_free | ( | char * | str | ) |
| 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.
| uint32_t rats_transports | ( | rats_t | node | ) |
Transports this node is actually running, as a RATS_TRANSPORT_MASK_* bitmask.
May be narrower than the config asked for: a UDP socket that could not be bound leaves the node TCP-only rather than failing to start. 0 before rats_start() and after rats_stop().
| rats_error_t rats_unsubscribe | ( | rats_t | node, |
| const char * | topic | ||
| ) |
| void rats_version | ( | int * | major, |
| int * | minor, | ||
| int * | patch, | ||
| int * | build | ||
| ) |
Library version components.
Any out-pointer may be NULL.
| const char * rats_version_string | ( | void | ) |
Library version as a static string, e.g.
"1.2.3" (do not free).