Skip to content

file Connection.h ​

Namespaces ​

Name
flake

Namespaces ​

Name
flake

Types ​

Name
structflake::ConnectionSink
Callback interface for connection lifecycle events.
structflake::AuthenticationSink
Callback interface for authentication during connection setup.
classflake::Connection
Primary client-side handle to the Flake system.

Functions Overview ​

Name
intflakeInitialize(flake::Wire * wire, flake::ConnectionSink * sink, flake::Connection ** conn)
Initialize the Flake library with an explicit wire and no local router.
voidflakeUninitialize(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.
voidflakeSetMTU(flake::Connection * c, uint16_t mtu)
Override the Maximum Transmission Unit for a connection.
intflakeSetArena(unsigned char * buf, size_t size)
Supply the library's arena backing buffer.
intflakeSetContactInterval(flake::Connection * c, uint32_t seconds)
Announce the client's contact interval with every connect.
intflakeSetContactFlags(flake::Connection * c, uint8_t flags)
Contact flags sent alongside the interval (CONTACT_FLAGS); 0 sends none. See FLAKE_CONTACT_FLAG_NAT.
intflakeAnnounceContactInterval(flake::Connection * c, uint32_t seconds)
Change the interval without reconnecting.
uint32_tflakeAcceptedContactInterval(flake::Connection * c)
Contact interval the router confirmed, in seconds.
intflakeSetLivenessProbe(flake::Connection * c, uint32_t idle_ms, uint8_t retries)
Configure the client's router-liveness probe.
intflakeSetClientPingIdle(flake::Connection * c, uint32_t idle_ms)
Same as flakeSetLivenessProbe(c, idle_ms, 0).
uint32_tflakeLastRxAgeMs(flake::Connection * c)
Milliseconds since the last valid message from the router; safe across the tick wrap. UINT32_MAX for a null c.
uint32_tflakeRxCount(flake::Connection * c)
Valid messages received on the connection since it was created.
uint32_tflakeTxCount(flake::Connection * c)
Messages written to the wire since the connection was created.
unsignedflakePeerSessionsOpen(flake::Connection * c)
Streams peers currently hold open on this client's objects, one per opener and stream.
intflakeSetPeerStreamIdleMs(flake::Connection * c, uint32_t ms)
Idle time after which a peer session no longer counts as open.
intflakeSetStreamTimeoutMs(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_INTERVALflakeSetContactInterval() and its companions are available.
FLAKE_CONTACT_FLAG_NATflakeSetContactFlags bit: the client sits behind NAT.
FLAKE_HAS_LIVENESS_PROBEflakeSetLivenessProbe() and flakeSetClientPingIdle() are available.
FLAKE_HAS_RX_STATSflakeLastRxAgeMs(), flakeRxCount() and flakeTxCount() are available.
FLAKE_HAS_PEER_SESSIONSflakePeerSessionsOpen() and flakeSetPeerStreamIdleMs() are available.
FLAKE_HAS_STREAM_TIMEOUTflakeSetStreamTimeoutMs() 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 buf in bytes; FLAKE_ARENA_SIZE is 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:

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:

Return: E_OK, or E_INVALID_PARAM for a null c.

Macros Documentation ​

define FLAKE_HAS_CONTACT_INTERVAL ​

cpp
#define FLAKE_HAS_CONTACT_INTERVAL 1

flakeSetContactInterval() and its companions are available.

define FLAKE_CONTACT_FLAG_NAT ​

cpp
#define FLAKE_CONTACT_FLAG_NAT 0x01U

flakeSetContactFlags bit: the client sits behind NAT.

define FLAKE_HAS_LIVENESS_PROBE ​

cpp
#define FLAKE_HAS_LIVENESS_PROBE 1

flakeSetLivenessProbe() and flakeSetClientPingIdle() are available.

define FLAKE_HAS_RX_STATS ​

cpp
#define FLAKE_HAS_RX_STATS 1

flakeLastRxAgeMs(), flakeRxCount() and flakeTxCount() are available.

define FLAKE_HAS_PEER_SESSIONS ​

cpp
#define FLAKE_HAS_PEER_SESSIONS 1

flakePeerSessionsOpen() and flakeSetPeerStreamIdleMs() are available.

define FLAKE_HAS_STREAM_TIMEOUT ​

cpp
#define FLAKE_HAS_STREAM_TIMEOUT 1

flakeSetStreamTimeoutMs() 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_ */