C++ SDK

• 1: Classes
• 1.1: Acl::AclLog::FileLocationFormatterFlag
• 1.2: Acl::AclLog::ThreadNameFormatterFlag
• 1.3: Acl::ControlDataAddress
• 1.4: Acl::ControlDataCommon::ConnectionEvent
• 1.5: Acl::ControlDataCommon::Response
• 1.6: Acl::ControlDataCommon::StatusMessage
• 1.7: Acl::ControlDataSender
• 1.8: Acl::ControlDataSender::Settings
• 1.9: Acl::ISystemControllerInterface
• 1.10: Acl::ISystemControllerInterface::Callbacks
• 1.11: Acl::ISystemControllerInterface::Response
• 1.12: Acl::SystemControllerConnection
• 1.13: Acl::SystemControllerConnection::Settings
• 1.14: Acl::UUID
• 1.15: fmt::formatter< Acl::ControlDataAddress >
• 1.16: fmt::formatter< Acl::ControlDataCommon::EventType >
• 1.17: fmt::formatter< Acl::ISystemControllerInterface::StatusCode >
• 1.18: fmt::formatter< Acl::SystemControllerConnection::ComponentType >
• 1.19: fmt::formatter< Acl::UUID >
• 2: Files
• 2.1: include/AclLog.h
• 2.2: include/ControlDataAddress.h
• 2.3: include/ControlDataCommon.h
• 2.4: include/ControlDataSender.h
• 2.5: include/ISystemControllerInterface.h
• 2.6: include/SystemControllerConnection.h
• 2.7: include/UUID.h
• 3: Namespaces
• 3.1: Acl
• 3.2: Acl::AclLog
• 3.3: Acl::ControlDataCommon
• 3.4: fmt
• 3.5: spdlog

1 - Classes

• namespace Acl
  • namespace AclLog
    A namespace for logging utilities.
    • class FileLocationFormatterFlag
      A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.
    • class ThreadNameFormatterFlag
  • class ControlDataAddress
    A class representing an address within the control protocol. The address consists of an internal list of UUIDs, which all represent a component that needs to be passed to reach the final address. An address might end with a wildcard, which is represented by the omni UUID (i.e. all digits set to 0xF) and will then match all addresses with the same UUID sequence in the start.
  • namespace ControlDataCommon
    • struct ConnectionEvent
      A connection related event.
    • struct Response
      A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.
    • struct StatusMessage
      A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.
  • class ControlDataSender
    A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.
    • struct Settings
      Settings for a ControlDataSender.
  • class ISystemControllerInterface
    An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server.
    • struct Callbacks
      A struct containing the callbacks that needs to be registered by the component using this interface.
    • struct Response
      A response to a request, consists of a status code and an (optional) parameters JSON object.
  • class SystemControllerConnection
    An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.
    • struct Settings
      Settings for a SystemControllerConnection.
  • class UUID
    A class holding a UUID, stored as a sequence of bytes. This class only supports version 4 variant 1 of the UUID standard.
• namespace fmt
  • struct formatter< Acl::ControlDataAddress >
  • struct formatter< Acl::ControlDataCommon::EventType >
  • struct formatter< Acl::ISystemControllerInterface::StatusCode >
  • struct formatter< Acl::SystemControllerConnection::ComponentType >
  • struct formatter< Acl::UUID >
• namespace spdlog

1.1 - Acl::AclLog::FileLocationFormatterFlag

Acl::AclLog::FileLocationFormatterFlag Class Reference

A custom flag formatter which logs the source file location between a par of “[]”, in case the location is provided with the log call.

#include <AclLog.h>

Inherits from spdlog::custom_flag_formatter

Public Functions

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & msg,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

1.2 - Acl::AclLog::ThreadNameFormatterFlag

Acl::AclLog::ThreadNameFormatterFlag Class Reference

Inherits from spdlog::custom_flag_formatter

Public Functions

Public Functions Documentation

function format

inline void format(
    const spdlog::details::log_msg & ,
    const std::tm & ,
    spdlog::memory_buf_t & dest
) override

function clone

inline std::unique_ptr< custom_flag_formatter > clone() const override

1.3 - Acl::ControlDataAddress

Acl::ControlDataAddress Class Reference

A class representing an address within the control protocol. The address consists of an internal list of UUIDs, which all represent a component that needs to be passed to reach the final address. An address might end with a wildcard, which is represented by the omni UUID (i.e. all digits set to 0xF) and will then match all addresses with the same UUID sequence in the start.

#include <ControlDataAddress.h>

Public Functions

Friends

Public Functions Documentation

function ControlDataAddress

ControlDataAddress() =default

Default constructor for an empty address.

function ControlDataAddress

explicit ControlDataAddress(
    const UUID & destinationUUID
)

Constructor which creates an address with the final destination UUID.

Parameters:

• destinationUUID The destination UUID of the address

function size

size_t size() const

Returns the number of parts of the address that is currently stored.

Return: The number of parts of the address that is currently stored

function empty

bool empty() const

Check if address is empty or contains any parts.

Return: True if there are no parts left in the address, false otherwise.

function extend

bool extend(
    const UUID & uuid
)

Extend the address with a new UUID that must be passed to get to the next UUID in the address.

Parameters:

• uuid The new UUID to add to the address.

Return: False in case an omni UUID is passed to a non-empty ControlDataAddress

function extend

bool extend(
    const ControlDataAddress & address
)

Extend the address with all UUIDs in another ControlDataAddress. The UUIDs will be added in the same order as in the other ControlDataAddress to the beginning of this ControlDataAddress (i.e. the UUIDs in the other ControlDataAddress must be passed before the UUIDs in this ControlDataAddress to reach the final destination)

Parameters:

• address The ControlDataAddress with UUIDs to add to this address.

Return: False in case @address contains an omni UUID

function hasWildcard

bool hasWildcard() const

Return: True if the address ends with a wildcard UUID (the special omni UUID), false otherwise.

function currentUuidIsWildcard

bool currentUuidIsWildcard() const

Return: True if the first UUID in the address is a wildcard UUID (the special omni UUID), false otherwise.

function currentUuidMatch

bool currentUuidMatch(
    const UUID & uuid
) const

Check if the uuid match the first UUID of the address.

Parameters:

• uuid The UUID to match against

Return: True if the UUID is the same as the first UUID in the address, or in case the first UUID of the address is a wildcard UUID, false otherwise.

function fullAddressMatch

bool fullAddressMatch(
    const ControlDataAddress & other
) const

Check if another address matches this address. This check might pass in two ways:

• Both addresses are identical
• At least one of the addresses includes a wildcard, and the other address is identical up to that wildcard otherThe address to match against.

True if the addresses match either because they are equal, or in case they are equal up to a wildcard in either address, false otherwise.

function getCurrentUuid

std::optional< UUID > getCurrentUuid() const

Return: The first UUID of the address, or an empty optional in case there are no more UUIDs in the address.

function moveToAndGetNextUuid

std::optional< UUID > moveToAndGetNextUuid()

Move to the next UUID in the address, by removing the current one, and return the next UUID of the address. In case there was at least one UUID in the address, the size of the address will be decreased by one.

Return: The next UUID of the address, or an empty optional in case there are no more UUIDs in the address.

function pack

std::vector< uint8_t > pack() const

Pack a ControlDataAddress into a byte vector.

Return: A vector with the packed message address.

function toString

std::string toString() const

Return: A string representation of the ControlDataAddress with ‘:’ separated UUIDs.

function operator==

bool operator==(
    const ControlDataAddress & other
) const

Compare this ControlDataAddress for equality to another ControlDataAddress.

Parameters:

• other The other ControlDataAddress to compare this ControlDataAddress to

Return: True if the ControlDataAddresses are identical, false otherwise

function operator!=

bool operator!=(
    const ControlDataAddress & other
) const

Compare this ControlDataAddress for non-equality to another ControlDataAddress.

Parameters:

• other The other ControlDataAddress to compare this ControlDataAddress to

Return: False if the ControlDataAddresses are identical, true otherwise

function unpack

static std::optional< ControlDataAddress > unpack(
    const std::vector< uint8_t >::const_iterator & packedBegin,
    const std::vector< uint8_t >::const_iterator & packedEnd
)

Unpack a packed ControlDataAddress, the size of packedEnd - packedBegin must be a multiple of UUID::kUUIDSize to be able to unpack anything.

Parameters:

• packedBegin Iterator to the start of the vector to unpack.
• packedEnd Iterator to the end of the vector to unpack.

Return: A ControlDataAddress if unpack was successful, std::nullopt if it failed.

function unpack

static std::optional< ControlDataAddress > unpack(
    const uint8_t * packedBegin,
    const uint8_t * packedEnd
)

Unpack a packed ControlDataAddress, the size of packedEnd - packedBegin must be a multiple of UUID::kUUIDSize to be able to unpack anything.

Parameters:

• packedBegin Pointer to the first byte of the address to unpack
• packedEnd Pointer to the last byte of the address to unpack

Return: A ControlDataAddress if unpack was successful, std::nullopt if it failed.

Friends

friend operator«

friend std::ostream & operator<<(
    std::ostream & stream,

    const ControlDataAddress & address
);

Print this ControlDataAddress to an output stream, UUIDs separated with ‘:’.

Parameters:

• stream The stream to print to
• address The address to print

Return: Reference to the output stream

1.4 - Acl::ControlDataCommon::ConnectionEvent

Acl::ControlDataCommon::ConnectionEvent Struct Reference

A connection related event.

#include <ControlDataCommon.h>

Public Attributes

Public Attributes Documentation

variable mEventType

EventType mEventType = EventType::kDisconnect;

variable mAddress

ControlDataAddress mAddress;

The type of event that occurred.

variable mEventNode

UUID mEventNode;

The address of the node that detected the event.

1.5 - Acl::ControlDataCommon::Response

Acl::ControlDataCommon::Response Struct Reference

A response from a ControlDataReceiver to a request. The UUID tells which receiver the response is sent from.

#include <ControlDataCommon.h>

Public Attributes

Public Attributes Documentation

variable mMessage

std::string mMessage;

variable mRequestId

uint64_t mRequestId = 0;

The actual message.

variable mFromUUID

UUID mFromUUID;

The ID of the request this is a response to.

variable mRecipient

ControlDataAddress mRecipient;

The UUID of the responder.

1.6 - Acl::ControlDataCommon::StatusMessage

Acl::ControlDataCommon::StatusMessage Struct Reference

A status message from a ControlDataReceiver. The UUID tells which receiver the message is sent from.

#include <ControlDataCommon.h>

Public Attributes

Public Attributes Documentation

variable mMessage

std::string mMessage;

variable mFromUUID

UUID mFromUUID;

The actual message.

variable mRecipient

ControlDataAddress mRecipient;

The UUID of the sender.

1.7 - Acl::ControlDataSender

Acl::ControlDataSender Class Reference

A ControlDataSender can send control signals to one or more receivers using a network connection. A single ControlDataSender can connect to multiple receivers, all identified by a UUID. The class is controlled using an ISystemControllerInterface; this interface is responsible for setting up connections to receivers. The ControlDataSender can send asynchronous requests to (all) the receivers and get a response back. Each response is identified with a request ID as well as the UUID of the responding receiver. The ControlDataSender can also receive status messages from the receivers.

#include <ControlDataSender.h>

Public Classes

Public Types

Public Functions

Public Types Documentation

enum SendRequestStatus

Public Functions Documentation

function ControlDataSender

ControlDataSender()

Default constructor, creates an empty object.

function ~ControlDataSender

~ControlDataSender()

Destructor. Will disconnect from the connected receivers and close the System controller connection.

function configure

bool configure(
    const std::shared_ptr< ISystemControllerInterface > & controllerInterface,
    const Settings & settings
) const

Configure this ControlDataSender and connect it to the System Controller. This method will fail in case the ISystemControllerInterface has already been connected to the controller by another component, as such interface can only be used by one component.

Parameters:

• controllerInterface The interface to the System controller, used for communicating with this ControlDataSender
• settings The Settings to use for this ControlDataSender

Return: True on success, false otherwise

function sendRequestToReceivers

SendRequestStatus sendRequestToReceivers(
    std::string_view request,
    uint64_t & requestId,
    const UUID & requester =UUID::kNilUUID,
    int8_t hops =-1
) const

Send a request to all the connected ControlDataReceivers asynchronously. The responses will be sent to the response callback.

Parameters:

• request The request message
• requestId The unique identifier of this request. Used to identify the async responses.
• requester UUID that identifies the entity that sent the request, can be used if the ControlDataSender serves multiple clients and need to distinguish between them when receiving responses. A value of the nil UUID indicates that the requester field will not be used.
• hops The number of hops the message should be delivered/forwarded. A value of 1 means to all connected receivers, but not further. A value of 2 means all connected receivers to this sender, and all connected receivers to those, but not further, and so on. A value of -1 means infinity.

Return: True if the request was successfully sent, false otherwise

function getDirectlyConnectedReceivers

std::vector< UUID > getDirectlyConnectedReceivers() const

Get a list of the UUIDs of all receivers that are directly connected to this ControlDataSender. Useful for checking if this ControlDataSender is connected to something that will receive the control commands sent.

Return: A list of all receivers that are connected directly to this ControlDataSender

function ControlDataSender

ControlDataSender(
    ControlDataSender const & 
) =delete

function operator=

ControlDataSender & operator=(
    ControlDataSender const & 
) =delete

function getVersion

static std::string getVersion()

Get application version.

Return: a string with the current version, e.g. “6.0.0-39-g60a35937”

1.8 - Acl::ControlDataSender::Settings

Acl::ControlDataSender::Settings Struct Reference

Settings for a ControlDataSender.

#include <ControlDataSender.h>

Public Attributes

Public Attributes Documentation

variable mResponseCallback

std::function< void(const ControlDataCommon::Response &)> mResponseCallback;

variable mStatusMessageCallback

std::function< void(const ControlDataCommon::StatusMessage &)> mStatusMessageCallback;

variable mConnectionEventCallback

std::function< void(const ControlDataCommon::ConnectionEvent &)> mConnectionEventCallback;

1.9 - Acl::ISystemControllerInterface

Acl::ISystemControllerInterface Class Reference

An ISystemControllerInterface is the interface between a component and the System controller controlling the component. The interface allows for two-way communication between the component and the system controller by means of sending requests and getting responses. Classes deriving from the ISystemControllerInterface should provide the component side implementation of the communication with the system controller. This interface can be inherited and implemented by developers to connect to custom system controllers, or to directly control a component programmatically, without the need for connecting to a remote server.

#include <ISystemControllerInterface.h>

Inherited by Acl::SystemControllerConnection

Public Classes

Public Types

Public Functions

Public Types Documentation

enum StatusCode

Status codes used in JSON response messages for Websockets. These are starting at 3000 since the 1000 - 2000 range is taken up by the Spec: https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1.

Public Functions Documentation

function ~ISystemControllerInterface

virtual ~ISystemControllerInterface() =default

Virtual destructor.

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) =0

Send a message containing a JSON object to the controller.

Parameters:

• messageTitle The title of the status type or request
• parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplemented by: Acl::SystemControllerConnection::sendMessage

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) =0

Register the callbacks to call for events in this class.

Parameters:

• callbacks The callbacks to use when events in this class happen

Return: True on successful registration, false if some callback is not set or if already connected

Reimplemented by: Acl::SystemControllerConnection::registerRequestCallback

function connect

virtual bool connect() =0

Connect to the System controller.

Return: True on successful connection, false on error or if already connected

Reimplemented by: Acl::SystemControllerConnection::connect

function disconnect

virtual bool disconnect() =0

Disconnect from the System controller.

Return: True on successful disconnection, false on error or if not connected

Reimplemented by: Acl::SystemControllerConnection::disconnect

function isConnected

virtual bool isConnected() const =0

Return: True if connected to the System controller, false otherwise

Reimplemented by: Acl::SystemControllerConnection::isConnected

function getUUID

virtual UUID getUUID() const =0

Return: The UUID of this interface to the System controller

Reimplemented by: Acl::SystemControllerConnection::getUUID

1.10 - Acl::ISystemControllerInterface::Callbacks

Acl::ISystemControllerInterface::Callbacks Struct Reference

A struct containing the callbacks that needs to be registered by the component using this interface.

#include <ISystemControllerInterface.h>

Public Attributes

Public Attributes Documentation

variable mRequestCallback

std::function< Response(const std::string &, const nlohmann::json &)> mRequestCallback;

variable mConnectionClosedCallback

std::function< void(uint32_t, const std::string &, const std::error_code &)> mConnectionClosedCallback;

1.11 - Acl::ISystemControllerInterface::Response

Acl::ISystemControllerInterface::Response Struct Reference

A response to a request, consists of a status code and an (optional) parameters JSON object.

#include <ISystemControllerInterface.h>

Public Attributes

Public Attributes Documentation

variable mCode

StatusCode mCode;

variable mParameters

nlohmann::json mParameters;

1.12 - Acl::SystemControllerConnection

Acl::SystemControllerConnection Class Reference

An implementation of the ISystemControllerInterface for a System controller residing in a remote server. The connection to the server uses a Websocket.

#include <SystemControllerConnection.h>

Inherits from Acl::ISystemControllerInterface

Public Classes

Public Types

Public Functions

Additional inherited members

Public Classes inherited from Acl::ISystemControllerInterface

Public Types inherited from Acl::ISystemControllerInterface

Public Functions inherited from Acl::ISystemControllerInterface

Public Types Documentation

enum ComponentType

Enumeration of component types the component using this SystemControllerConnection can tell the System Controller to be seen as.

Public Functions Documentation

function SystemControllerConnection

SystemControllerConnection()

function ~SystemControllerConnection

~SystemControllerConnection() override

function configure

bool configure(
    const Settings & settings
)

Configure this connection. This method should be called before calling.

Parameters:

• settings The settings to use when connecting to the server

See: connect.

Return: True if successfully configured, false otherwise

function connect

virtual bool connect() override

Connect to the server using the settings set with the.

See: configure method.

Return: True if connection was successful, false otherwise

Reimplements: Acl::ISystemControllerInterface::connect

function isConnected

virtual bool isConnected() const override

Return: True if this class is connected to the server, false otherwise

Reimplements: Acl::ISystemControllerInterface::isConnected

function getUUID

virtual UUID getUUID() const override

Return: The UUID of this interface to the System controller

Reimplements: Acl::ISystemControllerInterface::getUUID

function sendMessage

virtual std::optional< std::string > sendMessage(
    const std::string & messageTitle,
    const nlohmann::json & parameters
) override

Send a message containing a JSON object to the system controller server.

Parameters:

• messageTitle The title of the status type or request
• parameters The parameters part of the JSON message

Return: Optional containing an error message on error, else nullopt in case the message was successfully sent

Reimplements: Acl::ISystemControllerInterface::sendMessage

function disconnect

virtual bool disconnect() override

Disconnect from the server.

Return: True if successfully disconnected, false on internal error

Reimplements: Acl::ISystemControllerInterface::disconnect

function registerRequestCallback

virtual bool registerRequestCallback(
    const Callbacks & callbacks
) override

Register callbacks to call when getting requests from the server or the server connection is lost.

Parameters:

• callbacks The callbacks to set

Return: True if successfully registered, false if a callback is not set, or if already connected to the server

Reimplements: Acl::ISystemControllerInterface::registerRequestCallback

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection const & 
) =delete

function SystemControllerConnection

SystemControllerConnection(
    SystemControllerConnection && 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection const & 
) =delete

function operator=

SystemControllerConnection & operator=(
    SystemControllerConnection && 
) =delete

1.13 - Acl::SystemControllerConnection::Settings

Acl::SystemControllerConnection::Settings Struct Reference

Settings for a SystemControllerConnection.

#include <SystemControllerConnection.h>

Public Attributes

Public Attributes Documentation

variable mSystemControllerIP

std::string mSystemControllerIP;

variable mSystemControllerPort

uint16_t mSystemControllerPort;

variable mSystemControllerPostfix

std::string mSystemControllerPostfix;

variable mPSK

std::string mPSK;

variable mUUID

UUID mUUID;

variable mType

ComponentType mType;

variable mName

std::string mName;

variable mMyIP

std::string mMyIP;

variable mConnectTimeout

std::chrono::milliseconds mConnectTimeout {
            3000};

variable mEnableHTTPS

bool mEnableHTTPS;

variable mInsecureHTTPS

bool mInsecureHTTPS;

variable mCustomCaCertFile

std::string mCustomCaCertFile;

1.14 - Acl::UUID

Acl::UUID Class Reference

A class holding a UUID, stored as a sequence of bytes. This class only supports version 4 variant 1 of the UUID standard.

#include <UUID.h>

Public Functions

Public Attributes

Public Functions Documentation

function UUID

UUID()

Default constructor, returns a nil UUID.

function UUID

inline explicit constexpr UUID(
    const std::array< uint8_t, kUUIDSize > & bytes
)

Construct a UUID from a sequence of bytes.

Note: This will accept UUIDs that are not valid version 4 UUIDs.

function toString

std::string toString() const

Return: A string representation of the UUID formatted as hex values

function toBitString

std::string toBitString() const

Return: A string representation of the UUID formatted as bits

function operator==

bool operator==(
    const UUID & other
) const

Compare this UUID to another UUID.

Parameters:

• other The other UUID to compare this UUID to

Return: True if the UUIDs are identical, false otherwise

function operator!=

bool operator!=(
    const UUID & other
) const

Compare this UUID to another UUID for inequality.

Parameters:

• other The other UUID to compare this UUID to

Return: True if the UUIDs are not equal, false in case they are identical

function operator<

bool operator<(
    const UUID & other
) const

Less than operator implementation.

Parameters:

• other The other UUID to compare this UUID to

Return: True if this UUID should be sorted before the other UUID

function begin

std::array< uint8_t, kUUIDSize >::const_iterator begin() const

Return: Begin iterator for the UUID byte sequence

function end

std::array< uint8_t, kUUIDSize >::const_iterator end() const

Return: End iterator for the UUID byte sequence

function size

inline constexpr size_t size() const

Return: The size in bytes of the UUID. Will always return 16

function generateRandom

static UUID generateRandom()

Create a new, randomly generated UUID.

Return: A new, randomly generated UUID

function fromString

static std::optional< UUID > fromString(
    const std::string & uuid
)

Parse a UUID from a string.

Parameters:

• uuid The string representation of the UUID

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

function fromVector

static std::optional< UUID > fromVector(
    const std::vector< uint8_t >::const_iterator & start,
    const std::vector< uint8_t >::const_iterator & end
)

Read a UUID from a vector of uint8s.

Parameters:

• start Start iterator to read the UUID from
• end End iterator to read the UUID from, must be 16 bytes after start

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

function fromPointer

static std::optional< UUID > fromPointer(
    const uint8_t * start,
    const uint8_t * end
)

Read a UUID from a pointer.

Parameters:

• start Start pointer to read the UUID from
• end End pointer to read the UUID from, must be 16 bytes after start

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

Public Attributes Documentation

variable kUUIDSize

static constexpr size_t kUUIDSize = 16;

variable kNilUUID

static const UUID kNilUUID;

variable kOmniUUID

static const UUID kOmniUUID;

1.15 - fmt::formatter< Acl::ControlDataAddress >

fmt::formatter< Acl::ControlDataAddress > Struct Reference

Inherits from formatter< std::string >

Public Functions

Public Functions Documentation

function format

template <typename FormatContext >
inline auto format(
    const Acl::ControlDataAddress & address,
    FormatContext & ctx
)

1.16 - fmt::formatter< Acl::ControlDataCommon::EventType >

fmt::formatter< Acl::ControlDataCommon::EventType > Struct Reference

Inherits from formatter< std::string >

Public Functions

Public Functions Documentation

function format

template <typename FormatContext >
inline auto format(
    const Acl::ControlDataCommon::EventType type,
    FormatContext & ctx
)

1.17 - fmt::formatter< Acl::ISystemControllerInterface::StatusCode >

fmt::formatter< Acl::ISystemControllerInterface::StatusCode > Struct Reference

Inherits from formatter< std::uint32_t >

Public Functions

Public Functions Documentation

function format

template <typename FormatContext >
inline auto format(
    Acl::ISystemControllerInterface::StatusCode code,
    FormatContext & ctx
)

1.18 - fmt::formatter< Acl::SystemControllerConnection::ComponentType >

fmt::formatter< Acl::SystemControllerConnection::ComponentType > Struct Reference

Inherits from formatter< std::string >

Public Functions

Public Functions Documentation

function format

template <typename FormatContext >
inline auto format(
    Acl::SystemControllerConnection::ComponentType type,
    FormatContext & ctx
)

1.19 - fmt::formatter< Acl::UUID >

fmt::formatter< Acl::UUID > Struct Reference

Inherits from formatter< std::string >

Public Functions

Public Functions Documentation

function format

template <typename FormatContext >
inline auto format(
    const Acl::UUID & uuid,
    FormatContext & ctx
)

2 - Files

• dir build
  • dir install
    • dir include
      • file include/AclLog.h
      • file include/ControlDataAddress.h
      • file include/ControlDataCommon.h
      • file include/ControlDataSender.h
      • file include/ISystemControllerInterface.h
      • file include/SystemControllerConnection.h
      • file include/UUID.h

2.1 - include/AclLog.h

include/AclLog.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <filesystem>
#include <string>

#include <spdlog/details/log_msg.h>
#include <spdlog/fmt/fmt.h>
#include <spdlog/formatter.h>
#include <spdlog/pattern_formatter.h>
#include <sys/prctl.h>

namespace Acl {

namespace AclLog {

enum class Level {
    kTrace,    // Detailed diagnostics (for development only)
    kDebug,    // Messages intended for debugging only
    kInfo,     // Messages about normal behavior (default log level)
    kWarning,  // Warnings (functionality intact)
    kError,    // Recoverable errors (functionality impaired)
    kCritical, // Unrecoverable errors (application must stop)
    kOff       // Turns off all logging
};

void init(const std::string& name);

void initControlMessagesLog(const std::string& name);

void setLevel(Level level);

void logControlMessage(const std::string& origin, const std::string& controlMessage);

AclLog::Level getLogLevel();

size_t getMaxFileSize();

size_t getMaxLogRotations();

std::filesystem::path getLogFileFullPath(const std::string& name);

inline std::string getThreadName() {
    static const size_t RECOMMENDED_BUFFER_SIZE = 20;
    static thread_local std::string name;

    if (name.empty()) {
        char buffer[RECOMMENDED_BUFFER_SIZE];
        int retval = prctl(PR_GET_NAME, buffer);
        if (retval == -1) {
            throw spdlog::spdlog_ex("Failed to get thread name: ", errno);
        }
        name = std::string(buffer);
    }
    return name;
}

class ThreadNameFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg&, const std::tm&, spdlog::memory_buf_t& dest) override {
        std::string threadName = getThreadName();
        dest.append(threadName.data(), threadName.data() + threadName.size());
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<ThreadNameFormatterFlag>();
    }
};

class FileLocationFormatterFlag : public spdlog::custom_flag_formatter {
public:
    void format(const spdlog::details::log_msg& msg, const std::tm&, spdlog::memory_buf_t& dest) override {
        if (!msg.source.empty()) {
            using namespace spdlog::details;

            dest.push_back('[');
            const char* filename = short_filename_formatter<null_scoped_padder>::basename(msg.source.filename);
            fmt_helper::append_string_view(filename, dest);
            dest.push_back(':');
            fmt_helper::append_int(msg.source.line, dest);
            dest.push_back(']');
        }
    }

    [[nodiscard]] std::unique_ptr<custom_flag_formatter> clone() const override {
        return spdlog::details::make_unique<FileLocationFormatterFlag>();
    }
};

} // namespace AclLog

} // namespace Acl

2.2 - include/ControlDataAddress.h

include/ControlDataAddress.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <cstdint>
#include <sstream>
#include <string>
#include <vector>

#include <fmt/format.h>

#include "UUID.h"

namespace Acl {

class ControlDataAddress final {
public:
    ControlDataAddress() = default;

    explicit ControlDataAddress(const UUID& destinationUUID);

    [[nodiscard]] size_t size() const;

    [[nodiscard]] bool empty() const;

    bool extend(const UUID& uuid);

    bool extend(const ControlDataAddress& address);

    [[nodiscard]] bool hasWildcard() const;

    [[nodiscard]] bool currentUuidIsWildcard() const;

    [[nodiscard]] bool currentUuidMatch(const UUID& uuid) const;

    [[nodiscard]] bool fullAddressMatch(const ControlDataAddress& other) const;

    [[nodiscard]] std::optional<UUID> getCurrentUuid() const;

    std::optional<UUID> moveToAndGetNextUuid();

    [[nodiscard]] std::vector<uint8_t> pack() const;

    static std::optional<ControlDataAddress> unpack(const std::vector<uint8_t>::const_iterator& packedBegin,
                                                    const std::vector<uint8_t>::const_iterator& packedEnd);

    static std::optional<ControlDataAddress> unpack(const uint8_t* packedBegin, const uint8_t* packedEnd);

    [[nodiscard]] std::string toString() const;

    bool operator==(const ControlDataAddress& other) const;

    bool operator!=(const ControlDataAddress& other) const;

    friend std::ostream& operator<<(std::ostream& stream, const ControlDataAddress& address);

private:
    std::vector<UUID> mAddress;
};

std::ostream& operator<<(std::ostream& stream, const ControlDataAddress& address);

} // namespace Acl

template <> struct fmt::formatter<Acl::ControlDataAddress> : formatter<std::string> {
    template <typename FormatContext> auto format(const Acl::ControlDataAddress& address, FormatContext& ctx) {
        return formatter<std::string>::format(address.toString(), ctx);
    }
};

2.3 - include/ControlDataCommon.h

include/ControlDataCommon.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <cstdint>
#include <string>
#include <vector>

#include "ControlDataAddress.h"
#include "UUID.h"

namespace Acl::ControlDataCommon {

struct Response {
    std::string mMessage;          
    uint64_t mRequestId = 0;       
    UUID mFromUUID;                
    ControlDataAddress mRecipient; 
};

struct StatusMessage {
    std::string mMessage;          
    UUID mFromUUID;                
    ControlDataAddress mRecipient; 
};

enum class EventType : uint8_t {
    kDisconnect, 
    kConnect     
};

struct ConnectionEvent {
    EventType mEventType = EventType::kDisconnect; 
    ControlDataAddress mAddress;                   
    UUID mEventNode;                               
};

} // namespace Acl::ControlDataCommon

template <> struct fmt::formatter<Acl::ControlDataCommon::EventType> : formatter<std::string> {
    template <typename FormatContext> auto format(const Acl::ControlDataCommon::EventType type, FormatContext& ctx) {
        std::string value;
        switch (type) {
        case Acl::ControlDataCommon::EventType::kDisconnect:
            value = "disconnect";
            break;
        case Acl::ControlDataCommon::EventType::kConnect:
            value = "connect";
            break;
        }
        return formatter<std::string>::format(value, ctx);
    }
};

2.4 - include/ControlDataSender.h

include/ControlDataSender.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <functional>
#include <memory>
#include <vector>

#include <ISystemControllerInterface.h>

#include "ControlDataCommon.h"

namespace Acl {

class ControlDataSender final {
public:
    enum class SendRequestStatus {
        kSuccess,             
        kFailed,              
        kSendFailedForSome,   
        kSenderNotConfigured, 
        kNoConnectedReceiver, 
        kInternalError        
    };

    struct Settings {
        std::function<void(const ControlDataCommon::Response&)>
            mResponseCallback; // Callback for response messages from receivers
        std::function<void(const ControlDataCommon::StatusMessage&)>
            mStatusMessageCallback; // Callback for status messages from receivers
        std::function<void(const ControlDataCommon::ConnectionEvent&)>
            mConnectionEventCallback; // Callback for connection events that has been detected by the sender, or passed
                                      // to it from a connected receiver
    };

    ControlDataSender();

    ~ControlDataSender();

    [[nodiscard]] bool configure(const std::shared_ptr<ISystemControllerInterface>& controllerInterface,
                                 const Settings& settings) const;

    SendRequestStatus sendRequestToReceivers(std::string_view request,
                                             uint64_t& requestId,
                                             const UUID& requester = UUID::kNilUUID,
                                             int8_t hops = -1) const;

    [[nodiscard]] std::vector<UUID> getDirectlyConnectedReceivers() const;

    static std::string getVersion();

    // ControlDataSender is not copyable
    ControlDataSender(ControlDataSender const&) = delete;            // Copy construct
    ControlDataSender& operator=(ControlDataSender const&) = delete; // Copy assign

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

} // namespace Acl

2.5 - include/ISystemControllerInterface.h

include/ISystemControllerInterface.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <functional>
#include <json.hpp>
#include <optional>
#include <string>

#include <fmt/format.h>

#include "UUID.h"

namespace Acl {

class ISystemControllerInterface {
public:
    enum class StatusCode : uint32_t {
        SUCCESS = 3001, // Accept / Success

        TOO_MANY_REQUESTS = 3101, // Too many requests, try again later

        UUID_ALREADY_REGISTERED = 3201, // UUID is already registered
        FORMAT_ERROR = 3202,            // Message formatting error
        ALREADY_CONFIGURED = 3203,      // The requested thing to configure is already configured
        OUT_OF_RESOURCES = 3204,  // Out of resources (CPU/GPU close to max utilization, all available slots used, etc.)
        NOT_FOUND = 3205,         // The requested thing was not found
        INTERNAL_ERROR = 3206,    // Internal error when trying to serve the request
        CONNECTION_FAILED = 3207, // Connection failure
        TIMEOUT_EXCEEDED = 3208,  // Timeout exceeded
        KEY_MISMATCH = 3209,      // Key mismatch (might be a timeout, 3007 in the future)
        UNKNOWN_REQUEST = 3210,   // The name of the request was not known
        MALFORMED_REQUEST = 3211, // The request is not correctly formatted
        ALREADY_IN_USE = 3212,    // The requested resource is already in use
        VERSION_MISMATCH = 3213,  // The version of the request is not supported

        // None, yet
    };

    struct Response {
        StatusCode mCode;
        nlohmann::json mParameters; // Can be empty
    };

    struct Callbacks {
        std::function<Response(const std::string&, const nlohmann::json&)>
            mRequestCallback; // Callback called when then controller has sent a request
        std::function<void(uint32_t, const std::string&, const std::error_code&)>
            mConnectionClosedCallback; // Callback called when the connection to the controller is closed
    };

    virtual ~ISystemControllerInterface() = default;

    virtual std::optional<std::string> sendMessage(const std::string& messageTitle,
                                                   const nlohmann::json& parameters) = 0;

    virtual bool registerRequestCallback(const Callbacks& callbacks) = 0;

    virtual bool connect() = 0;

    virtual bool disconnect() = 0;

    [[nodiscard]] virtual bool isConnected() const = 0;

    [[nodiscard]] virtual UUID getUUID() const = 0;
};

} // namespace Acl

template <> struct fmt::formatter<Acl::ISystemControllerInterface::StatusCode> : formatter<std::uint32_t> {
    template <typename FormatContext>
    auto format(Acl::ISystemControllerInterface::StatusCode code, FormatContext& ctx) {
        return formatter<std::uint32_t>::format(static_cast<uint32_t>(code), ctx);
    }
};

2.6 - include/SystemControllerConnection.h

include/SystemControllerConnection.h File Reference

Namespaces

Classes

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <chrono>

#include "ISystemControllerInterface.h"
#include "json.hpp"

namespace Acl {

class SystemControllerConnection final : public ISystemControllerInterface {
public:
    enum class ComponentType : uint32_t {
        kIngest,
        kPipeline,
        kControlPanel,
    };

    struct Settings {
        std::string mSystemControllerIP;      // IP of the server
        uint16_t mSystemControllerPort;       // Port of the server
        std::string mSystemControllerPostfix; // Postfix of the address that the backend uses if any
        std::string mPSK;    // The pre shared key used for authorization with the system controller server
        UUID mUUID;          // The UUID of the device using this library
        ComponentType mType; // The component type of the component using this SystemControllerConnection
        std::string mName;   // The component name (optional)
        std::string mMyIP;   // The external IP of the system the component is running on. Will be sent to the system
                             // controller server in the announce message (optional)
        std::chrono::milliseconds mConnectTimeout{
            3000};           // Max time to wait on an announcement response from the server during connection
        bool mEnableHTTPS;   // Enable the communication between the system controller and a component encrypted
        bool mInsecureHTTPS; // Disable the verification of the TLS certificate if requested.
        std::string mCustomCaCertFile; // Custom CA certificate
    };

    SystemControllerConnection();
    ~SystemControllerConnection() override;

    bool configure(const Settings& settings);

    bool connect() override;

    [[nodiscard]] bool isConnected() const override;

    [[nodiscard]] UUID getUUID() const override;

    std::optional<std::string> sendMessage(const std::string& messageTitle, const nlohmann::json& parameters) override;

    bool disconnect() override;

    bool registerRequestCallback(const Callbacks& callbacks) override;

    SystemControllerConnection(SystemControllerConnection const&) = delete;            // Copy construct
    SystemControllerConnection(SystemControllerConnection&&) = delete;                 // Move construct
    SystemControllerConnection& operator=(SystemControllerConnection const&) = delete; // Copy assign
    SystemControllerConnection& operator=(SystemControllerConnection&&) = delete;      // Move assign

private:
    class Impl;
    std::unique_ptr<Impl> pImpl;
};

} // namespace Acl

template <> struct fmt::formatter<Acl::SystemControllerConnection::ComponentType> : formatter<std::string> {
    template <typename FormatContext>
    auto format(Acl::SystemControllerConnection::ComponentType type, FormatContext& ctx) {
        std::string value;
        switch (type) {
        case Acl::SystemControllerConnection::ComponentType::kIngest:
            value = "ingest";
            break;
        case Acl::SystemControllerConnection::ComponentType::kPipeline:
            value = "pipeline";
            break;
        case Acl::SystemControllerConnection::ComponentType::kControlPanel:
            value = "controlpanel";
            break;
        }

        return formatter<std::string>::format(value, ctx);
    }
};

2.7 - include/UUID.h

include/UUID.h File Reference

Namespaces

Classes

Functions

Attributes

Functions Documentation

function UUID

UUID()

Default constructor, returns a nil UUID.

function UUID

explicit constexpr UUID(
    const std::array< uint8_t, kUUIDSize > & bytes
)

Construct a UUID from a sequence of bytes.

Note: This will accept UUIDs that are not valid version 4 UUIDs.

function generateRandom

static UUID generateRandom()

Create a new, randomly generated UUID.

Return: A new, randomly generated UUID

function fromString

static std::optional< UUID > fromString(
    const std::string & uuid
)

Parse a UUID from a string.

Parameters:

• uuid The string representation of the UUID

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

function fromVector

static std::optional< UUID > fromVector(
    const std::vector< uint8_t >::const_iterator & start,
    const std::vector< uint8_t >::const_iterator & end
)

Read a UUID from a vector of uint8s.

Parameters:

• start Start iterator to read the UUID from
• end End iterator to read the UUID from, must be 16 bytes after start

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

function fromPointer

static std::optional< UUID > fromPointer(
    const uint8_t * start,
    const uint8_t * end
)

Read a UUID from a pointer.

Parameters:

• start Start pointer to read the UUID from
• end End pointer to read the UUID from, must be 16 bytes after start

Return: An optional containing the UUID on success, or nullopt in case the parsing failed

function toString

std::string toString() const

Return: A string representation of the UUID formatted as hex values

function toBitString

std::string toBitString() const

Return: A string representation of the UUID formatted as bits

function operator==

bool operator==(
    const UUID & other
) const

Compare this UUID to another UUID.

Parameters:

• other The other UUID to compare this UUID to

Return: True if the UUIDs are identical, false otherwise

function operator!=

bool operator!=(
    const UUID & other
) const

Compare this UUID to another UUID for inequality.

Parameters:

• other The other UUID to compare this UUID to

Return: True if the UUIDs are not equal, false in case they are identical

function operator<

bool operator<(
    const UUID & other
) const

Less than operator implementation.

Parameters:

• other The other UUID to compare this UUID to

Return: True if this UUID should be sorted before the other UUID

function begin

std::array< uint8_t, kUUIDSize >::const_iterator begin() const

Return: Begin iterator for the UUID byte sequence

function end

std::array< uint8_t, kUUIDSize >::const_iterator end() const

Return: End iterator for the UUID byte sequence

function size

constexpr size_t size() const

Return: The size in bytes of the UUID. Will always return 16

Attributes Documentation

variable kUUIDSize

static constexpr size_t kUUIDSize = 16;

variable kNilUUID

static const UUID kNilUUID;

variable kOmniUUID

static const UUID kOmniUUID;

Source code

// Copyright (c) 2024, Ateliere. All rights reserved.

#pragma once

#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <vector>

#include <fmt/format.h>

namespace Acl {

class UUID {
public:
    static constexpr size_t kUUIDSize = 16;
    // Predefined UUID values
    static const UUID kNilUUID;
    static const UUID kOmniUUID;

    UUID();

    constexpr explicit UUID(const std::array<uint8_t, kUUIDSize>& bytes)
        : mUUID{bytes} {
    }

    static UUID generateRandom();

    static std::optional<UUID> fromString(const std::string& uuid);

    static std::optional<UUID> fromVector(const std::vector<uint8_t>::const_iterator& start,
                                          const std::vector<uint8_t>::const_iterator& end);

    static std::optional<UUID> fromPointer(const uint8_t* start, const uint8_t* end);

    [[nodiscard]] std::string toString() const;

    [[nodiscard]] std::string toBitString() const;

    bool operator==(const UUID& other) const;

    bool operator!=(const UUID& other) const;

    bool operator<(const UUID& other) const;

    [[nodiscard]] std::array<uint8_t, kUUIDSize>::const_iterator begin() const;

    [[nodiscard]] std::array<uint8_t, kUUIDSize>::const_iterator end() const;

    [[nodiscard]] constexpr size_t size() const {
        return mUUID.size();
    }

private:
    std::array<uint8_t, kUUIDSize> mUUID{};
} __attribute__((packed));

static_assert(sizeof(UUID) == 16, "UUID has unexpected size");

std::ostream& operator<<(std::ostream& stream, const UUID& uuid);

} // namespace Acl

template <> struct fmt::formatter<Acl::UUID> : formatter<std::string> {
    template <typename FormatContext> auto format(const Acl::UUID& uuid, FormatContext& ctx) {
        return formatter<std::string>::format(uuid.toString(), ctx);
    }
};

3 - Namespaces

• namespace Acl
  • namespace AclLog
    A namespace for logging utilities.
  • namespace ControlDataCommon
• namespace fmt
• namespace spdlog

3.1 - Acl

Acl Namespace Reference

Namespaces

Classes

Functions

Functions Documentation

function operator«

std::ostream & operator<<(
    std::ostream & stream,
    const ControlDataAddress & address
)

Print this ControlDataAddress to an output stream, UUIDs separated with ‘:’.

Parameters:

• stream The stream to print to
• address The address to print

Return: Reference to the output stream

function operator«

std::ostream & operator<<(
    std::ostream & stream,
    const UUID & uuid
)

Print this UUID to an output stream.

Parameters:

• stream The stream to print to

Return: Reference to the output stream

3.2 - Acl::AclLog

Acl::AclLog Namespace Reference A namespace for logging utilities.

Classes

Types

Functions