67 lines
3 KiB
C
67 lines
3 KiB
C
/*
|
|
* C ABI between fumi (Rust) and the microReticulum client shim.
|
|
*
|
|
* All calls block the caller; the shim owns the Reticulum loop thread and
|
|
* every callback fires on that thread. link_id and destination_hash are
|
|
* always 16 bytes. No client Reticulum identity is created or loaded anywhere
|
|
* (upstream spec sec 13.8): a server MUST NOT require identification, and a
|
|
* durable client handle is exactly what the wire format withholds.
|
|
*/
|
|
#ifndef SMOLMAIL_RNS_H
|
|
#define SMOLMAIL_RNS_H
|
|
|
|
#include <stddef.h>
|
|
#include <stdint.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/* Implemented in smolmail_rns.cpp, called from src/rns/ffi.rs.
|
|
* udp_forward_host may be NULL: with no forward target the interface sends
|
|
* to the source address of the last datagram received, which a client that
|
|
* only listens cannot use -- a client speaks first, so the forward target
|
|
* should point at the server's UDP interface.
|
|
* Returns 0 on success, negative on failure. */
|
|
int smolmail_rns_start(const char *storage_dir,
|
|
const char *udp_listen_host, uint16_t udp_listen_port,
|
|
const char *udp_forward_host, uint16_t udp_forward_port);
|
|
|
|
/* Requests a path if none is known and waits for it (upstream spec sec
|
|
* 13.3), recalls the identity, builds the OUT/SINGLE smolmail.server
|
|
* destination, opens the link and waits for ACTIVE. Returns the 16-byte
|
|
* link id, which the caller's AUTH and REGISTER bind values are derived
|
|
* from (upstream spec sec 13.6).
|
|
* Returns 0 on success, negative on failure. */
|
|
int smolmail_rns_connect(const uint8_t *destination_hash, uint32_t timeout_ms,
|
|
uint8_t *link_id_out);
|
|
|
|
/* request is `op u8 || body`, the response `status u8 || payload`
|
|
* (upstream spec sec 13.5). A CLI has one request in flight at a time, so
|
|
* the shim keeps a single response slot rather than a map.
|
|
* Returns 0 on success and writes the response length to *out_len;
|
|
* negative on failure: no link (-1), send failure (-2), timeout or closed
|
|
* link (-3), failed transfer (-4), malformed response (-5), response larger
|
|
* than cap (-6). These are local errors and MUST NOT be reported as status
|
|
* codes (upstream spec sec 13.5). */
|
|
int smolmail_rns_request(const uint8_t *request, size_t request_len,
|
|
uint32_t timeout_ms, uint8_t *out, size_t cap,
|
|
size_t *out_len);
|
|
|
|
/* Tears the link down rather than leave it on keepalives, which run for
|
|
* minutes (upstream spec sec 13.10). */
|
|
void smolmail_rns_close(void);
|
|
|
|
/* Stops the Reticulum stack: halts and joins the loop thread, tears the link
|
|
* down, deregisters and stops the UDP interface, and releases the
|
|
* Reticulum instance. The loop thread must be joined before the process (or
|
|
* embedding host) tears down statics, or it keeps calling into Reticulum
|
|
* while their destructors run. A no-op when the stack is not running.
|
|
* The stack can be started again afterwards. */
|
|
void smolmail_rns_stop(void);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* SMOLMAIL_RNS_H */
|