file platform/flake/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.
struct	flakeSerialWireCallbacks_t Callback structure for serial-wire connect/disconnect events.

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.
int	flakeInitializeWithRouter(flake::ConnectionSink * sink, flake::Connection ** conn) Initialize the Flake library with a locally running router.
int	flakeInitializeWithRouterAndAuth(flake::ConnectionSink * conn_sink, flake::AuthenticationSink * auth_sink, flake::Connection conn) Initialize the Flake library with a local router and** authentication support.
int	flakeInitializeRouter() Initialize the library as a standalone router (no local client).
int	flakeInitializeRouterWithAuth(flake::AuthenticationSink * auth_sink) Initialize the library as a standalone router with client authentication enabled.
void	flakeUninitialize(flake::Connection * c) Shut down the library and release all resources (client mode).
void	flakeUninitializeRouter(flake::Connection * c) Shut down the library and release all resources (router mode).
int	flakeRouterAddServerWire(flake::ServerWire * w) Add a custom ServerWire to the router.
int	flakeRouterAddTcpServerWire(int port, int use_tls) Convenience: add a TCP (optionally TLS) server wire to the router.
int	flakeRouterAddUdpServerWire(int port) Convenience: add a UDP server wire to the router.
int	flakeRouterAddSerialServerWire(int hdev, flakeSerialWireCallbacks_t * cb) Convenience: add a UART / serial server wire to the router.
int	flakeRouterAddReversedTcpServerWire(const char * host, int port, bool use_tls, const unsigned char * x509_ca_cert, unsigned int x509_ca_cert_len) Convenience: add a reversed TCP server wire for routers behind firewalls.
flake::Wire *	flakeCreateTcpWire(std::string ip, int port) Create a plain TCP client wire.
flake::Wire *	flakeCreateUdpWire(std::string 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	flakeMessagePoolInit(size_t size, std::byte * buf) Initialize the shared pool used for Flake protocol messages.
void	flakeRouterSetMaxClients(int clients) Set the maximum number of concurrent client connections the router will accept.

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 flakeInitializeWithRouter

cpp

int flakeInitializeWithRouter(
    flake::ConnectionSink * sink,
    flake::Connection ** conn
)

Initialize the Flake library with a locally running router.

Parameters:

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.

A router is started in-process and the client connects to it directly (no network transport required).

function flakeInitializeWithRouterAndAuth

cpp

int flakeInitializeWithRouterAndAuth(
    flake::ConnectionSink * conn_sink,
    flake::AuthenticationSink * auth_sink,
    flake::Connection ** conn
)

Initialize the Flake library with a local router and authentication support.

Parameters:

conn_sink Callback for disconnect notifications.
auth_sink Callback for authentication events.
conn Receives a pointer to the newly created Connection.

Return: E_OK on success, or a negative error code.

function flakeInitializeRouter

cpp

int flakeInitializeRouter()

Initialize the library as a standalone router (no local client).

Return: E_OK on success, or a negative error code.

function flakeInitializeRouterWithAuth

cpp

int flakeInitializeRouterWithAuth(
    flake::AuthenticationSink * auth_sink
)

Initialize the library as a standalone router with client authentication enabled.

Parameters:

auth_sink Callback for authenticating connecting clients.

Return: E_OK on success, or a negative error code.

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 flakeUninitializeRouter

cpp

void flakeUninitializeRouter(
    flake::Connection * c
)

Shut down the library and release all resources (router mode).

Parameters:

c The Connection if one was created, or nullptr for a standalone router.

function flakeRouterAddServerWire

cpp

int flakeRouterAddServerWire(
    flake::ServerWire * w
)

Add a custom ServerWire to the router.

Parameters:

w The ServerWire to add (ownership is not transferred).

Return: E_OK on success, or a negative error code.

function flakeRouterAddTcpServerWire

cpp

int flakeRouterAddTcpServerWire(
    int port,
    int use_tls
)

Convenience: add a TCP (optionally TLS) server wire to the router.

Parameters:

port TCP port to listen on.
use_tls Non-zero to enable TLS on this port.

Return: E_OK on success, or a negative error code.

function flakeRouterAddUdpServerWire

cpp

int flakeRouterAddUdpServerWire(
    int port
)

Convenience: add a UDP server wire to the router.

Parameters:

port UDP port to listen on.

Return: E_OK on success, or a negative error code.

function flakeRouterAddSerialServerWire

cpp

int flakeRouterAddSerialServerWire(
    int hdev,
    flakeSerialWireCallbacks_t * cb
)

Convenience: add a UART / serial server wire to the router.

Parameters:

hdev Platform handle for the serial device.
cb Optional connect/disconnect callbacks (may be nullptr).

Return: E_OK on success, or a negative error code.

function flakeRouterAddReversedTcpServerWire

cpp

int flakeRouterAddReversedTcpServerWire(
    const char * host,
    int port,
    bool use_tls,
    const unsigned char * x509_ca_cert,
    unsigned int x509_ca_cert_len
)

Convenience: add a reversed TCP server wire for routers behind firewalls.

Parameters:

host Remote host to connect to.
port Remote port to connect to.
use_tls Non-zero to enable TLS.
x509_ca_cert DER-encoded CA certificate for TLS verification (may be nullptr).
x509_ca_cert_len Length of x509_ca_cert.

Return: E_OK on success, or a negative error code.

In reversed mode the router initiates the outbound TCP connection to the given host/port rather than listening.

function flakeCreateTcpWire

cpp

flake::Wire * flakeCreateTcpWire(
    std::string 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(
    std::string 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 flakeMessagePoolInit

cpp

int flakeMessagePoolInit(
    size_t size,
    std::byte * buf
)

Initialize the shared pool used for Flake protocol messages.

Parameters:

size Size of buf in bytes.
buf Pointer to the memory buffer to use for the pool.

Return: 0 on success, non-zero on failure.

Call this once before any other Flake function if you want to supply your own memory region for message allocation (useful on embedded targets).

function flakeRouterSetMaxClients

cpp

void flakeRouterSetMaxClients(
    int clients
)

Set the maximum number of concurrent client connections the router will accept.

Parameters:

clients Maximum number of clients.

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"
#include "ServerWire.h"



namespace flake
{
    constexpr uint16_t defaultPort = 9986U;

    constexpr uint16_t defaultTLSPort = 9987U;

    class ConnectionImpl;

    struct ConnectionSink
    {
        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;
    };

    struct AuthenticationSink
    {
        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,
                                             int challenge_len, uint8_t* response[], int* response_len) = 0;

        virtual int onAuthChallengeRequested(void* wire, char* challenge_type[],
                                             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;
        Connection(const Connection&) = delete;
        Connection& operator=(const Connection&) = delete;
        Connection(Connection&&) = delete;
        Connection& operator=(Connection&&) = delete;
        virtual ~Connection() noexcept = default;
    public:

        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;

        virtual uint16_t getMTU() const = 0;

        virtual ConnectionImpl* impl()  = 0;
    };

    typedef Connection Device;
}

#if defined (__cplusplus)
extern "C" {
#endif

/* -----------------------------------------------------------------------
 *  Library Initialization / Shutdown
 * ----------------------------------------------------------------------- */

int flakeInitialize(flake::Wire* wire, flake::ConnectionSink* sink, flake::Connection** conn);

int flakeInitializeWithRouter(flake::ConnectionSink* sink, flake::Connection** conn);

int flakeInitializeWithRouterAndAuth(flake::ConnectionSink* conn_sink, flake::AuthenticationSink* auth_sink,
                                     flake::Connection** conn);

int flakeInitializeRouter();

int flakeInitializeRouterWithAuth(flake::AuthenticationSink* auth_sink);

void flakeUninitialize(flake::Connection* c);

void flakeUninitializeRouter(flake::Connection* c);

/* -----------------------------------------------------------------------
 *  Router Wire Management
 * ----------------------------------------------------------------------- */

int flakeRouterAddServerWire(flake::ServerWire* w);

int flakeRouterAddTcpServerWire(int port, int use_tls);

int flakeRouterAddUdpServerWire(int port);

typedef struct flakeSerialWireCallbacks_t
{
    void (*onConnect)(void);    
    void (*onDisconnect)(void); 
} flakeSerialWireCallbacks_t;

int flakeRouterAddSerialServerWire(int hdev, flakeSerialWireCallbacks_t* cb);

int flakeRouterAddReversedTcpServerWire(const char* host, int port, bool use_tls,
                                        const unsigned char* x509_ca_cert, unsigned int x509_ca_cert_len);

/* -----------------------------------------------------------------------
 *  Wire Factory Functions
 * ----------------------------------------------------------------------- */

#if FLAKE_TLS
flake::Wire *flakeCreateTLSWire(std::string ip, int port,unsigned char* x509_ca_cert, unsigned int x509_ca_cert_len);
#endif

#if FLAKE_DTLS
flake::Wire *flakeCreateDTLSWire(std::string ip, int port,unsigned char* x509_ca_cert, unsigned int x509_ca_cert_len);
#endif

flake::Wire* flakeCreateTcpWire(std::string ip, int port);

flake::Wire* flakeCreateUdpWire(std::string ip, int port, int rcv_timeout_s);

const char* flakeFindRouter(int timeout_s);

void flakeSetMTU(flake::Connection* c, uint16_t mtu);

int flakeMessagePoolInit(size_t size, std::byte* buf);

void flakeRouterSetMaxClients(int clients);


#if defined (__cplusplus)
}
#endif

#endif /* CONNECTION_H_ */

file platform/flake/Connection.h ​

Namespaces ​

Namespaces ​

Types ​

Functions Overview ​

Function Details ​

function flakeInitialize ​

function flakeInitializeWithRouter ​

function flakeInitializeWithRouterAndAuth ​

function flakeInitializeRouter ​

function flakeInitializeRouterWithAuth ​

function flakeUninitialize ​

function flakeUninitializeRouter ​

function flakeRouterAddServerWire ​

function flakeRouterAddTcpServerWire ​

function flakeRouterAddUdpServerWire ​

function flakeRouterAddSerialServerWire ​

function flakeRouterAddReversedTcpServerWire ​

function flakeCreateTcpWire ​

function flakeCreateUdpWire ​

function flakeFindRouter ​

function flakeSetMTU ​

function flakeMessagePoolInit ​

function flakeRouterSetMaxClients ​

Source code ​

file platform/flake/Connection.h

Namespaces

Namespaces

Types

Functions Overview

Function Details

function flakeInitialize

function flakeInitializeWithRouter

function flakeInitializeWithRouterAndAuth

function flakeInitializeRouter

function flakeInitializeRouterWithAuth

function flakeUninitialize

function flakeUninitializeRouter

function flakeRouterAddServerWire

function flakeRouterAddTcpServerWire

function flakeRouterAddUdpServerWire

function flakeRouterAddSerialServerWire

function flakeRouterAddReversedTcpServerWire

function flakeCreateTcpWire

function flakeCreateUdpWire

function flakeFindRouter

function flakeSetMTU

function flakeMessagePoolInit

function flakeRouterSetMaxClients

Source code