Appearance
file Connection.h
Namespaces
| Name |
|---|
| flake |
Namespaces
| Name |
|---|
| flake |
Types
| Name | |
|---|---|
| struct | flake::ConnectionSink Callback interface for connection lifecycle events. |
| struct | flake::AuthenticationSink Callback interface for authentication during connection setup. |
| class | flake::Connection Primary client-side handle to the Flake system. |
Functions Overview
| Name | |
|---|---|
| int | flakeInitialize(flake::Wire * wire, flake::ConnectionSink * sink, flake::Connection ** conn) Initialize the Flake library with an explicit wire and no local router. |
| void | flakeUninitialize(flake::Connection * c) Shut down the library and release all resources (client mode). |
| flake::Wire * | flakeCreateTcpWire(const char * ip, int port) Create a plain TCP client wire. |
| flake::Wire * | flakeCreateUdpWire(const char * ip, int port, int rcv_timeout_s) Create a UDP client wire. |
| const char * | flakeFindRouter(int timeout_s) Discover a router on the local network via broadcast / mDNS. |
| void | flakeSetMTU(flake::Connection * c, uint16_t mtu) Override the Maximum Transmission Unit for a connection. |
| int | flakeSetArena(unsigned char * buf, size_t size) Supply the library's arena backing buffer. |
| int | flakeSetContactInterval(flake::Connection * c, uint32_t seconds) Announce the client's contact interval with every connect. |
| int | flakeSetContactFlags(flake::Connection * c, uint8_t flags) Contact flags sent alongside the interval ( CONTACT_FLAGS); 0 sends none. See FLAKE_CONTACT_FLAG_NAT. |
| int | flakeAnnounceContactInterval(flake::Connection * c, uint32_t seconds) Change the interval without reconnecting. |
| uint32_t | flakeAcceptedContactInterval(flake::Connection * c) Contact interval the router confirmed, in seconds. |
| int | flakeSetLivenessProbe(flake::Connection * c, uint32_t idle_ms, uint8_t retries) Configure the client's router-liveness probe. |
| int | flakeSetClientPingIdle(flake::Connection * c, uint32_t idle_ms) Same as flakeSetLivenessProbe(c, idle_ms, 0). |
| uint32_t | flakeLastRxAgeMs(flake::Connection * c) Milliseconds since the last valid message from the router; safe across the tick wrap. UINT32_MAX for a null c. |
| uint32_t | flakeRxCount(flake::Connection * c) Valid messages received on the connection since it was created. |
| uint32_t | flakeTxCount(flake::Connection * c) Messages written to the wire since the connection was created. |
| unsigned | flakePeerSessionsOpen(flake::Connection * c) Streams peers currently hold open on this client's objects, one per opener and stream. |
| int | flakeSetPeerStreamIdleMs(flake::Connection * c, uint32_t ms) Idle time after which a peer session no longer counts as open. |
| int | flakeSetStreamTimeoutMs(flake::Connection * c, uint32_t ms) Inactivity after which a stream a peer opened on one of this connection's objects is closed. |
Defines
| Name | |
|---|---|
| FLAKE_HAS_CONTACT_INTERVAL | flakeSetContactInterval() and its companions are available. |
| FLAKE_CONTACT_FLAG_NAT | flakeSetContactFlags bit: the client sits behind NAT. |
| FLAKE_HAS_LIVENESS_PROBE | flakeSetLivenessProbe() and flakeSetClientPingIdle() are available. |
| FLAKE_HAS_RX_STATS | flakeLastRxAgeMs(), flakeRxCount() and flakeTxCount() are available. |
| FLAKE_HAS_PEER_SESSIONS | flakePeerSessionsOpen() and flakeSetPeerStreamIdleMs() are available. |
| FLAKE_HAS_STREAM_TIMEOUT | flakeSetStreamTimeoutMs() is available. |
Function Details
function flakeInitialize
cpp
int flakeInitialize(
flake::Wire * wire,
flake::ConnectionSink * sink,
flake::Connection ** conn
)Initialize the Flake library with an explicit wire and no local router.
Parameters:
- wire The transport wire to use (e.g. TCP, Serial).
- sink Callback for disconnect notifications (may be
nullptr). - conn Receives a pointer to the newly created Connection.
Return: E_OK on success, or a negative error code.
This is the standard entry point for a pure client that connects to an external router over the provided Wire.
function flakeUninitialize
cpp
void flakeUninitialize(
flake::Connection * c
)Shut down the library and release all resources (client mode).
Parameters:
- c The Connection obtained from one of the
flakeInitialize*functions.
Call this before program exit.
function flakeCreateTcpWire
cpp
flake::Wire * flakeCreateTcpWire(
const char * ip,
int port
)Create a plain TCP client wire.
Parameters:
- ip Remote host IP or hostname.
- port Remote port.
Return: Pointer to a new Wire, or nullptr on failure. The caller takes ownership.
function flakeCreateUdpWire
cpp
flake::Wire * flakeCreateUdpWire(
const char * ip,
int port,
int rcv_timeout_s
)Create a UDP client wire.
Parameters:
- ip Remote host IP or hostname.
- port Remote port.
- rcv_timeout_s Receive timeout in seconds.
Return: Pointer to a new Wire, or nullptr on failure. The caller takes ownership.
function flakeFindRouter
cpp
const char * flakeFindRouter(
int timeout_s
)Discover a router on the local network via broadcast / mDNS.
Parameters:
- timeout_s Maximum time to wait for a response, in seconds.
Return: Null-terminated string with the router's address, or nullptr if none was found. The caller does not own the pointer.
function flakeSetMTU
cpp
void flakeSetMTU(
flake::Connection * c,
uint16_t mtu
)Override the Maximum Transmission Unit for a connection.
Parameters:
- c The Connection.
- mtu New MTU value in bytes.
function flakeSetArena
cpp
int flakeSetArena(
unsigned char * buf,
size_t size
)Supply the library's arena backing buffer.
Parameters:
- buf Start of the integrator-supplied arena region.
- size Size of
bufin bytes;FLAKE_ARENA_SIZEis a conservative upper bound that always fits.
Return: E_OK on success.
libflake keeps all internal storage in a single process-wide arena: per-class object pools (Messages, Streams, PropArrays, Wires, Router, Connection), the size-class byte buckets, and the remaining overhang for variable-length payloads. By default the arena spans an internal static buffer of FLAKE_ARENA_SIZE bytes; integrators who want to place libflake's working set in a specific region (e.g. a reserved ``.bss section, a MMIO'd SRAM bank, a caller-controlled heap slice) pass a buffer here.
Call exactly once, before any flakeInitialize* call and before any Wire/Message/Connection is constructed. Passing nullptr / 0 explicitly selects the internal static buffer.
function flakeSetContactInterval
cpp
int flakeSetContactInterval(
flake::Connection * c,
uint32_t seconds
)Announce the client's contact interval with every connect.
Parameters:
- c The Connection.
- seconds Longest silence under normal operation; 0 sends none.
Return: E_OK, or E_INVALID_PARAM for a null c.
The value travels as CONTACT_INTERVAL in the connect request (and in every ping to the router). A router that understands it stops pinging the client before the interval has passed and confirms the value; see flakeAcceptedContactInterval(). Set it before Connection::connect().
function flakeSetContactFlags
cpp
int flakeSetContactFlags(
flake::Connection * c,
uint8_t flags
)Contact flags sent alongside the interval (CONTACT_FLAGS); 0 sends none. See FLAKE_CONTACT_FLAG_NAT.
Return: E_OK, or E_INVALID_PARAM for a null c.
function flakeAnnounceContactInterval
cpp
int flakeAnnounceContactInterval(
flake::Connection * c,
uint32_t seconds
)Change the interval without reconnecting.
Parameters:
- c The Connection.
- seconds New interval; 0 withdraws the announcement for later connects and sends a plain ping.
Return: E_OK when the ping was queued, E_NOT_CONNECTED without a session (the interval is still taken over), E_INVALID_PARAM for a null c.
Takes seconds as the interval for this and every later connect (as flakeSetContactInterval() does) and sends a ping to the router carrying it. Routers that predate Spec 1.2 ignore the payload. An answer that carries an interval updates flakeAcceptedContactInterval().
function flakeAcceptedContactInterval
cpp
uint32_t flakeAcceptedContactInterval(
flake::Connection * c
)Contact interval the router confirmed, in seconds.
Valid once Connection::connect() returned E_OK; every connect resets it. 0 means the router did not confirm an interval: it keeps pinging at its own cadence, and nothing that depends on a long silence may be switched on.
function flakeSetLivenessProbe
cpp
int flakeSetLivenessProbe(
flake::Connection * c,
uint32_t idle_ms,
uint8_t retries
)Configure the client's router-liveness probe.
Parameters:
- c The Connection.
- idle_ms Silence after which the router is pinged; 0 disables the probe, FLAKE_PROBE_AUTO follows the confirmed contact interval. See FLAKE_CLIENT_PING_IDLE_MS.
- retries Unanswered probes before the session is dropped; 0 keeps the current budget.
Return: E_OK, or E_INVALID_PARAM for a null c.
function flakeSetClientPingIdle
cpp
int flakeSetClientPingIdle(
flake::Connection * c,
uint32_t idle_ms
)Same as flakeSetLivenessProbe(c, idle_ms, 0).
function flakeLastRxAgeMs
cpp
uint32_t flakeLastRxAgeMs(
flake::Connection * c
)Milliseconds since the last valid message from the router; safe across the tick wrap. UINT32_MAX for a null c.
function flakeRxCount
cpp
uint32_t flakeRxCount(
flake::Connection * c
)Valid messages received on the connection since it was created.
function flakeTxCount
cpp
uint32_t flakeTxCount(
flake::Connection * c
)Messages written to the wire since the connection was created.
function flakePeerSessionsOpen
cpp
unsigned flakePeerSessionsOpen(
flake::Connection * c
)Streams peers currently hold open on this client's objects, one per opener and stream.
function flakeSetPeerStreamIdleMs
cpp
int flakeSetPeerStreamIdleMs(
flake::Connection * c,
uint32_t ms
)Idle time after which a peer session no longer counts as open.
Parameters:
- c The Connection.
- ms 0 = never; default FLAKE_PEER_STREAM_IDLE_MS.
Return: E_OK, or E_INVALID_PARAM for a null c.
function flakeSetStreamTimeoutMs
cpp
int flakeSetStreamTimeoutMs(
flake::Connection * c,
uint32_t ms
)Inactivity after which a stream a peer opened on one of this connection's objects is closed.
Parameters:
- c The Connection.
- ms 0 = never; default FLAKE_STREAM_TIMEOUT_MS.
Return: E_OK, or E_INVALID_PARAM for a null c.
Macros Documentation
define FLAKE_HAS_CONTACT_INTERVAL
cpp
#define FLAKE_HAS_CONTACT_INTERVAL 1flakeSetContactInterval() and its companions are available.
define FLAKE_CONTACT_FLAG_NAT
cpp
#define FLAKE_CONTACT_FLAG_NAT 0x01UflakeSetContactFlags bit: the client sits behind NAT.
define FLAKE_HAS_LIVENESS_PROBE
cpp
#define FLAKE_HAS_LIVENESS_PROBE 1flakeSetLivenessProbe() and flakeSetClientPingIdle() are available.
define FLAKE_HAS_RX_STATS
cpp
#define FLAKE_HAS_RX_STATS 1flakeLastRxAgeMs(), flakeRxCount() and flakeTxCount() are available.
define FLAKE_HAS_PEER_SESSIONS
cpp
#define FLAKE_HAS_PEER_SESSIONS 1flakePeerSessionsOpen() and flakeSetPeerStreamIdleMs() are available.
define FLAKE_HAS_STREAM_TIMEOUT
cpp
#define FLAKE_HAS_STREAM_TIMEOUT 1flakeSetStreamTimeoutMs() is available.
Source code
cpp
/*******************************************************************************
* @file Connection.h
* @brief Connection management, authentication callbacks, and the
* top-level library initialization / shutdown API.
* @details This header defines:
* - ConnectionSink – callback interface for connection state events.
* - AuthenticationSink – callback interface for challenge/response
* authentication between clients and the router.
* - Connection – the main handle through which a client interacts
* with the Flake system (register objects, query objects, etc.).
* - C-linkage @c flakeInitialize* / @c flakeUninitialize* functions
* that bootstrap and tear down the library.
* - Convenience factory functions for creating Wire instances.
*
* @license This file is part of the ImagineOn Flake software package
* licensed under the ImagineOn software-licensing terms available
* under https://www.imagineon.de/de/info/licensing-terms
* @copyright Copyright (c) 2025 ImagineOn GmbH. www.imagineon.de.
******************************************************************************/
#ifndef CONNECTION_H_
#define CONNECTION_H_
#include "Object.h"
#include "Wire.h"
namespace flake
{
constexpr uint16_t defaultPort = 9986U;
constexpr uint16_t defaultTLSPort = 9987U;
class ConnectionImpl;
struct ConnectionSink
{
public:
ConnectionSink(const ConnectionSink&) = delete;
ConnectionSink& operator=(const ConnectionSink&) = delete;
ConnectionSink(ConnectionSink&&) = delete;
ConnectionSink& operator=(ConnectionSink&&) = delete;
protected:
ConnectionSink() = default;
~ConnectionSink() = default;
public:
virtual void onDisconnected() = 0;
virtual void onPeerSessions(unsigned open) { (void)open; }
};
struct AuthenticationSink
{
public:
AuthenticationSink(const AuthenticationSink&) = delete;
AuthenticationSink& operator=(const AuthenticationSink&) = delete;
AuthenticationSink(AuthenticationSink&&) = delete;
AuthenticationSink& operator=(AuthenticationSink&&) = delete;
protected:
virtual ~AuthenticationSink() noexcept = default;
AuthenticationSink() = default;
public:
virtual void onAuthChallengeReceived(const char* challenge_type, uint8_t* challenge,
// NOLINTNEXTLINE(modernize-avoid-c-arrays) - low-level byte/POD storage; std::array adds no benefit here
int challenge_len, uint8_t* response[], int* response_len) = 0;
// NOLINTNEXTLINE(modernize-avoid-c-arrays) - low-level byte/POD storage; std::array adds no benefit here
virtual int onAuthChallengeRequested(void* wire, char* challenge_type[],
// NOLINTNEXTLINE(modernize-avoid-c-arrays) - low-level byte/POD storage; std::array adds no benefit here
uint8_t* challenge[], int* challenge_len) = 0;
virtual int onAuthResponseReceived(const char* challenge_type, uint8_t* challenge,
int challenge_len, uint8_t* response, int response_len) = 0;
virtual int onConnect(const PropArray& props) = 0;
virtual flakeAuthType authenticationType() = 0;
};
class Connection
{
protected:
Connection() = default;
public:
Connection(const Connection&) = delete;
Connection& operator=(const Connection&) = delete;
Connection(Connection&&) = delete;
Connection& operator=(Connection&&) = delete;
virtual ~Connection() noexcept = default;
virtual int connect(AuthenticationSink* authentication_sink) = 0;
virtual int connect(PropArray& props) = 0;
virtual void disconnect() = 0;
virtual bool connected() = 0;
virtual int registerObject(ObjectDelegate* srv, uniqueId_t& uuid, bool requires_auth = false) = 0;
virtual int unregisterObject(ObjectDelegate* srv) = 0;
virtual int queryObjects(uniqueId_t type, Object** objects, int maxCount) = 0;
[[nodiscard]] virtual uint16_t getMTU() const = 0;
virtual ConnectionImpl* impl() = 0;
};
using Device = Connection;
}
#if defined (__cplusplus)
extern "C" {
#endif
/* -----------------------------------------------------------------------
* Library Initialization / Shutdown
* ----------------------------------------------------------------------- */
int flakeInitialize(flake::Wire* wire, flake::ConnectionSink* sink, flake::Connection** conn);
void flakeUninitialize(flake::Connection* c);
/* -----------------------------------------------------------------------
* Wire Factory Functions
* ----------------------------------------------------------------------- */
#if FLAKE_TLS
flake::Wire *flakeCreateTLSWire(const char* ip, int port,unsigned char* x509_ca_cert, unsigned int x509_ca_cert_len);
#endif
#if FLAKE_DTLS
flake::Wire *flakeCreateDTLSWire(const char* ip, int port,unsigned char* x509_ca_cert, unsigned int x509_ca_cert_len);
#endif
flake::Wire* flakeCreateTcpWire(const char* ip, int port);
flake::Wire* flakeCreateUdpWire(const char* ip, int port, int rcv_timeout_s);
const char* flakeFindRouter(int timeout_s);
void flakeSetMTU(flake::Connection* c, uint16_t mtu);
int flakeSetArena(unsigned char* buf, size_t size);
/* -----------------------------------------------------------------------
* Contact interval (Spec 1.2, parameter 0x0040)
* ----------------------------------------------------------------------- */
#define FLAKE_HAS_CONTACT_INTERVAL 1
#define FLAKE_CONTACT_FLAG_NAT 0x01U
int flakeSetContactInterval(flake::Connection* c, uint32_t seconds);
int flakeSetContactFlags(flake::Connection* c, uint8_t flags);
int flakeAnnounceContactInterval(flake::Connection* c, uint32_t seconds);
uint32_t flakeAcceptedContactInterval(flake::Connection* c);
/* -----------------------------------------------------------------------
* Liveness probe and receive statistics
* ----------------------------------------------------------------------- */
#define FLAKE_HAS_LIVENESS_PROBE 1
int flakeSetLivenessProbe(flake::Connection* c, uint32_t idle_ms, uint8_t retries);
int flakeSetClientPingIdle(flake::Connection* c, uint32_t idle_ms);
#define FLAKE_HAS_RX_STATS 1
uint32_t flakeLastRxAgeMs(flake::Connection* c);
uint32_t flakeRxCount(flake::Connection* c);
uint32_t flakeTxCount(flake::Connection* c);
/* -----------------------------------------------------------------------
* Peer sessions
* ----------------------------------------------------------------------- */
#define FLAKE_HAS_PEER_SESSIONS 1
unsigned flakePeerSessionsOpen(flake::Connection* c);
int flakeSetPeerStreamIdleMs(flake::Connection* c, uint32_t ms);
#define FLAKE_HAS_STREAM_TIMEOUT 1
int flakeSetStreamTimeoutMs(flake::Connection* c, uint32_t ms);
#if defined (__cplusplus)
}
#endif
#endif /* CONNECTION_H_ */