Appearance
file Object.h
Namespaces
| Name |
|---|
| flake |
Namespaces
| Name |
|---|
| flake |
Types
| Name | |
|---|---|
| class | flake::Indication Represents an incoming indication (server → client notification). |
| class | flake::Confirmation Represents the reply (confirmation) to a previously sent request. |
| class | flake::IndicationSink Callback interface for receiving Indication messages. |
| class | flake::ConfirmationSink Callback interface for receiving Confirmation messages. |
| class | flake::ConnectedObject An object that is connected to the Flake bus and has an address. |
| class | flake::Stream Byte-oriented read/write stream associated with an Object property. |
| struct | flake::ReportFill Fill level of an object's pending report. |
| class | flake::Object Client-side proxy for a Flake object. |
| class | flake::ObjectDelegate Interface to be implemented by the application to expose a custom Flake object. |
Defines
| Name | |
|---|---|
| EMPTY_ADDR | Sentinel address value indicating "no address". |
| TYPE_UUID_SERVICE | UUID string that identifies the built-in object-discovery type (used by Connection::queryObjects and the router's directory). The macro name keeps the _SERVICE suffix for source compatibility with older releases; the API itself has spoken in terms of Object since 1.4.x. |
| FLAKE_HAS_REPORT | Object::setPriority(), setHistoryClass(), setRecordSamples(), flushReport() and reportFill() are available. |
| FLAKE_HAS_REPORT_FLUSH | Object::flushReport() is available (subset of FLAKE_HAS_REPORT). |
Macros Documentation
define EMPTY_ADDR
cpp
#define EMPTY_ADDR UINT16_C(0xFFFFU)Sentinel address value indicating "no address".
define TYPE_UUID_SERVICE
cpp
#define TYPE_UUID_SERVICE "00000000-0000-0000-0000-000000000000"UUID string that identifies the built-in object-discovery type (used by Connection::queryObjects and the router's directory). The macro name keeps the _SERVICE suffix for source compatibility with older releases; the API itself has spoken in terms of Object since 1.4.x.
define FLAKE_HAS_REPORT
cpp
#define FLAKE_HAS_REPORT 1Object::setPriority(), setHistoryClass(), setRecordSamples(), flushReport() and reportFill() are available.
define FLAKE_HAS_REPORT_FLUSH
cpp
#define FLAKE_HAS_REPORT_FLUSH 1Object::flushReport() is available (subset of FLAKE_HAS_REPORT).
Source code
cpp
/*******************************************************************************
* @file Object.h
* @brief Core object model: Indication, Confirmation, Object, Stream
* and their associated sink / delegate interfaces.
* @details In the Flake architecture every addressable entity is an Object.
* Objects have typed properties, can be subscribed to, and
* communicate via Indications (server → client) and Confirmations
* (client → server reply).
*
* This header is part of the **public API**. Implementers use
* ObjectDelegate to expose custom objects, and consumers use
* Object to interact with remote 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 FLAKE_OBJECT_H_
#define FLAKE_OBJECT_H_
#include "FlakeTypes.h"
#include <functional>
#define EMPTY_ADDR UINT16_C(0xFFFFU)
#define TYPE_UUID_SERVICE "00000000-0000-0000-0000-000000000000"
#include <FlakeLimits.h>
#define FLAKE_HAS_REPORT 1
#define FLAKE_HAS_REPORT_FLUSH 1
namespace flake
{
class Table;
class ObjectImpl;
/* ===================================================================
* Indication
* =================================================================== */
class Indication
{
public:
Indication(const Indication&) = delete;
Indication& operator=(const Indication&) = delete;
Indication(Indication&&) = delete;
Indication& operator=(Indication&&) = delete;
Indication() = default;
virtual ~Indication() noexcept = default;
[[nodiscard]] virtual uint8_t
type() const = 0;
[[nodiscard]] virtual addr_t
source() const = 0;
[[nodiscard]] virtual addr_t
destination() const = 0;
[[nodiscard]] virtual const PropArray&
getData() const = 0;
virtual void
ack(int8_t result, const PropArray& va = PropArray()) const = 0;
[[nodiscard]] virtual bool
acknowledged() const = 0;
};
using Token = uint16_t;
/* ===================================================================
* Confirmation
* =================================================================== */
class Confirmation
{
public:
Confirmation(const Confirmation&) = delete;
Confirmation& operator=(const Confirmation&) = delete;
Confirmation(Confirmation&&) = delete;
Confirmation& operator=(Confirmation&&) = delete;
Confirmation() = default;
virtual ~Confirmation() noexcept = default;
[[nodiscard]] virtual uint8_t
type() const = 0;
[[nodiscard]] virtual addr_t
source() const = 0;
[[nodiscard]] virtual addr_t
destination() const = 0;
[[nodiscard]] virtual const PropArray&
getData() const = 0;
[[nodiscard]] virtual int8_t
result() const = 0;
[[nodiscard]] virtual Token
token() const = 0;
};
/* ===================================================================
* Sink Interfaces
* =================================================================== */
class IndicationSink
{
public:
IndicationSink(const IndicationSink&) = delete;
IndicationSink& operator=(const IndicationSink&) = delete;
IndicationSink(IndicationSink&&) = delete;
IndicationSink& operator=(IndicationSink&&) = delete;
protected:
IndicationSink() = default;
~IndicationSink() = default;
public:
virtual void
onIndication(const Indication& indication) = 0;
};
class ConfirmationSink
{
public:
ConfirmationSink(const ConfirmationSink&) = delete;
ConfirmationSink& operator=(const ConfirmationSink&) = delete;
ConfirmationSink(ConfirmationSink&&) = delete;
ConfirmationSink& operator=(ConfirmationSink&&) = delete;
protected:
ConfirmationSink() = default;
~ConfirmationSink() = default;
public:
virtual void
onConfirmation(const Confirmation& confirmation) = 0;
};
/* ===================================================================
* ConnectedObject
* =================================================================== */
class ConnectedObject : public IndicationSink, public ConfirmationSink
{
public:
ConnectedObject(const ConnectedObject&) = delete;
ConnectedObject& operator=(const ConnectedObject&) = delete;
ConnectedObject(ConnectedObject&&) = delete;
ConnectedObject& operator=(ConnectedObject&&) = delete;
protected:
ConnectedObject() = default;
~ConnectedObject() noexcept = default;
public:
[[nodiscard]] virtual addr_t addr() const = 0;
[[nodiscard]] virtual addr_t broadcastAddr() const = 0;
[[nodiscard]] virtual addr_t parentAddr() const = 0;
};
/* ===================================================================
* Stream
* =================================================================== */
class Stream
{
public:
Stream(const Stream&) = delete;
Stream& operator=(const Stream&) = delete;
Stream(Stream&&) = delete;
Stream& operator=(Stream&&) = delete;
protected:
Stream() = default;
~Stream() noexcept = default;
public:
constexpr static uint8_t FLAG_LIVE = 0x01U;
// NOLINTNEXTLINE(modernize-avoid-c-arrays) - low-level byte/POD storage; std::array adds no benefit here
virtual int write(uint8_t data[], unsigned int len) = 0;
virtual int read(uint8_t* data, unsigned int* len, unsigned int max_len) = 0;
virtual int seek(unsigned int pos) = 0;
virtual unsigned int pos() = 0;
virtual int close() = 0;
virtual uint32_t streamId() = 0;
};
/* ===================================================================
* Report storage: priorities, history classes, fill level
* =================================================================== */
constexpr uint8_t FLAKE_PRIO_NORMAL = 0U;
constexpr uint8_t FLAKE_PRIO_IMMEDIATE = 1U;
constexpr uint8_t FLAKE_HISTORY_CONDENSABLE = 0U;
constexpr uint8_t FLAKE_HISTORY_COMPLETE = 1U;
constexpr uint8_t FLAKE_HISTORY_LATEST = 2U;
constexpr uint8_t FLAKE_HISTORY_STAGE_NORMAL = 0U;
constexpr uint8_t FLAKE_HISTORY_STAGE_TIGHT = 1U;
constexpr uint8_t FLAKE_HISTORY_STAGE_OVER = 2U;
constexpr uint8_t FLAKE_HISTORY_STAGE_HOLD = 3U;
struct ReportFill
{
uint32_t bytes;
uint32_t samples;
uint32_t oldestTimestamp;
uint8_t percent;
uint32_t droppedSamples;
uint32_t droppedTimestamps;
uint32_t droppedOversize;
uint32_t condensedSamples;
};
/* ===================================================================
* Object (client-side proxy)
* =================================================================== */
class Object
{
friend class ConnectionImpl;
public:
Object(const Object&) = delete;
Object& operator=(const Object&) = delete;
Object(Object&&) = delete;
Object& operator=(Object&&) = delete;
protected:
Object() = default;
~Object() noexcept = default;
virtual ObjectImpl* impl() = 0;
public:
virtual int
registered() = 0;
virtual int
invoke(const char* command, PropArray& params,
bool blocking, PropArray& reply) = 0;
virtual int
broadcast(const char* command, PropArray& params) = 0;
virtual int
getProperties(PropArray& properties) = 0;
virtual int
setProperties(PropArray& properties) = 0;
virtual int
setProperty(const Property& property) = 0;
virtual void
getProperty(Property& property) = 0;
virtual int
openProperty(const uint32_t propTag, Stream** stream) = 0;
virtual int
// NOLINTNEXTLINE(performance-unnecessary-value-param) - signature is the public subscription API; copy is one-shot at registration
subscribe(std::function<void (const Indication&)> f) = 0;
virtual void
unsubscribe() = 0;
virtual int
sync(unsigned timeout_ms, bool block) = 0;
virtual void
defer() = 0;
virtual int
syncDeferred(unsigned timeout_ms, bool block) = 0;
virtual bool
hasDeferred() = 0;
virtual void
clear() = 0;
/* ---------------------------------------------------------------
* Reports (datagram wires). Non-virtual: they reach the
* implementation through impl() and leave the vtable as it was.
* Only meaningful on objects registered by this client.
* --------------------------------------------------------------- */
int setPriority(uint16_t idFirst, uint16_t idLast, uint8_t prio);
uint8_t priority(uint32_t tag);
bool hasUrgentPending();
int setHistoryClass(uint16_t idFirst, uint16_t idLast, uint8_t cls);
void setHistoryStage(uint8_t stage);
void setRecordSamples(bool on);
int flushReport(unsigned timeout_ms);
int reportFill(ReportFill* out);
virtual void
ref(FLAKE_REFLOC_DECL) = 0;
virtual void
unref(FLAKE_REFLOC_DECL) = 0;
};
/* ===================================================================
* ObjectDelegate (server-side implementation interface)
* =================================================================== */
class ObjectDelegate
{
public:
ObjectDelegate(const ObjectDelegate&) = delete;
ObjectDelegate& operator=(const ObjectDelegate&) = delete;
ObjectDelegate(ObjectDelegate&&) = delete;
ObjectDelegate& operator=(ObjectDelegate&&) = delete;
protected:
ObjectDelegate() = default;
public:
virtual ~ObjectDelegate() = default;
virtual Object* handle() = 0;
virtual int8_t
handleCustomMessage(const char* name, const PropArray& data, PropArray& outProps) = 0;
virtual int8_t
handleStreamOpen(Stream* s) = 0;
virtual int8_t
handleStreamClose(Stream* s) = 0;
virtual int8_t
handleStreamWrite(Stream* s, uint8_t* cb, uint16_t len) = 0;
virtual int8_t
handleStreamRead(Stream* s, uint8_t* cb, uint16_t* len, uint16_t max_len) = 0;
virtual int
setPropertyRequested(uint32_t tag, Property& value, const PropArray& transaction, bool internal) = 0;
virtual int
getPropertyRequested(uint32_t tag, Property& value) = 0;
virtual void
propertyChanged(const Property&) = 0;
virtual void
onInitialized() = 0;
virtual void
onUrgentPending() {}
virtual void
onReportPressure(uint8_t percent) { (void)percent; }
virtual void
onPeerSessionChanged(uint32_t streamTag, bool open) { (void)streamTag; (void)open; }
};
}
#endif /* FLAKE_OBJECT_H */