Protocol

Comprehensive structured types, utilities, and mechanisms for irsol protocol message exchange. More...

Files
file	assignment.hpp
	Protocol assignment operation representation.
file	binary.hpp
	Protocol binary data types and attributes definitions.
file	command.hpp
	Protocol command representation.
file	error.hpp
	Protocol error message representation.
file	inquiry.hpp
	Protocol inquiry representation.
file	success.hpp
	Protocol success message representation.
file	variants.hpp
	Definitions and utilities for incoming and outgoing protocol messages.
file	parser.hpp
	Parses raw protocol input strings into structured messages.
file	parser_result.hpp
	Encapsulates the result of a protocol parsing operation.
file	serialized_message.hpp
	Defines the SerializedMessage structure representing serialized protocol messages.
file	serializer.hpp
	Serialization utilities for protocol messages and primitive values.

Namespaces
namespace	irsol::protocol
	Core protocol message types, serialization, parsing, and communication utilities for the irsol framework.

Classes
struct	irsol::protocol::Assignment
	Represents an assignment operation in the protocol. More...
struct	irsol::protocol::BinaryDataAttribute
	Represents a single binary data attribute within the protocol. More...
struct	irsol::protocol::internal::BinaryDataBufferName< N >
	Helper to get a descriptive name for binary data buffers by dimensionality. More...
struct	irsol::protocol::internal::BinaryData< NBytes, N >
	Represents a binary data object within the protocol. More...
struct	irsol::protocol::Command
	Represents a command invocation in the protocol. More...
struct	irsol::protocol::Error
	Represents an error response message from the server. More...
struct	irsol::protocol::Inquiry
	Represents a value inquiry in the protocol. More...
struct	irsol::protocol::Success
	Represents a success response message from the server. More...
class	irsol::protocol::Parser
	Parses raw input strings into structured InMessage instances. More...
class	irsol::protocol::internal::ParserResult< T, >
	Wrapper for the result of a protocol parsing attempt. More...
struct	irsol::protocol::internal::SerializedMessage
	Represents a serialized protocol message with header and payload. More...
class	irsol::protocol::Serializer
	Serializes outgoing protocol messages and primitive values. More...

Typedefs
using	irsol::protocol::BinaryDataBuffer = internal::BinaryData< 2, 1 >
	1-dimensional binary data buffer with 2 bytes per element.
using	irsol::protocol::ImageBinaryData = internal::BinaryData< 2, 2 >
	2-dimensional binary data buffer with 2 bytes per element (e.g., grayscale images).
using	irsol::protocol::ColorImageBinaryData = internal::BinaryData< 2, 3 >
	3-dimensional binary data buffer with 2 bytes per element (e.g., color images).
using	irsol::protocol::InMessage = std::variant< Assignment, Inquiry, Command >
	Variant type representing any incoming message.
using	irsol::protocol::OutMessage = std::variant< Success, BinaryDataBuffer, ImageBinaryData, ColorImageBinaryData, Error >
	Variant type representing any outgoing message.

Enumerations
enum class	irsol::protocol::InMessageKind { irsol::protocol::InMessageKind::ASSIGNMENT , irsol::protocol::InMessageKind::INQUIRY , irsol::protocol::InMessageKind::COMMAND }
	Represents the type of an incoming message. More...
enum class	irsol::protocol::OutMessageKind {   irsol::protocol::OutMessageKind::SUCCESS , irsol::protocol::OutMessageKind::BINARY_BUFFER , irsol::protocol::OutMessageKind::BW_IMAGE , irsol::protocol::OutMessageKind::COLOR_IMAGE ,   irsol::protocol::OutMessageKind::ERROR }
	Represents the type of an outgoing message. More...

Functions
constexpr const char *	irsol::protocol::InMessageKindToString (InMessageKind kind)
	Converts an InMessageKind enum to a human-readable string.
constexpr const char *	irsol::protocol::OutMessageKindToString (OutMessageKind kind)
	Converts an OutMessageKind enum to a human-readable string.
std::string	irsol::protocol::toString (const InMessage &msg)
	Converts an incoming message variant to a human-readable string.
std::string	irsol::protocol::toString (const OutMessage &msg)
	Converts an outgoing message variant to a human-readable string.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>
constexpr InMessageKind	irsol::protocol::getInMessageKind (IRSOL_MAYBE_UNUSED const T &msg)
	Returns the InMessageKind enum value corresponding to a given incoming message type.
InMessageKind	irsol::protocol::getInMessageKind (const InMessage &msg)
	Returns the InMessageKind enum value for a given incoming message variant.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>
constexpr bool	irsol::protocol::isAssignment (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given incoming message type is an Assignment.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>
constexpr bool	irsol::protocol::isInquiry (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given incoming message type is an Inquiry.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>
constexpr bool	irsol::protocol::isCommand (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given incoming message type is a Command.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr OutMessageKind	irsol::protocol::getOutMessageKind (IRSOL_MAYBE_UNUSED const T &msg)
	Returns the OutMessageKind enum value corresponding to a given outgoing message type.
OutMessageKind	irsol::protocol::getOutMessageKind (const OutMessage &msg)
	Returns the OutMessageKind enum value for a given outgoing message variant.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr bool	irsol::protocol::isSuccess (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given outgoing message type is Success.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr bool	irsol::protocol::isBinaryDataBuffer (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given outgoing message type is BinaryDataBuffer.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr bool	irsol::protocol::isImageBinaryData (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given outgoing message type is ImageBinaryData (black & white).
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr bool	irsol::protocol::isColorImageBinaryData (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given outgoing message type is ColorImageBinaryData.
template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>
constexpr bool	irsol::protocol::isError (IRSOL_MAYBE_UNUSED T &msg)
	Checks if a given outgoing message type is Error.

Detailed Description

Comprehensive structured types, utilities, and mechanisms for irsol protocol message exchange.

The Protocol module encompasses the core abstractions and tools that define, handle, and facilitate client-server communication in the irsol framework.

This includes:

• Structured Message Types: Strongly-typed C++ classes representing all protocol messages exchanged between client and server, categorized into:
  • Incoming Messages (irsol::protocol::InMessage): commands, assignments, and inquiries originating from clients.
  • Outgoing Messages (irsol::protocol::OutMessage): responses, status indications, binary data transmissions, and errors sent by servers.
• Tagged Variants for Polymorphism: Use of std::variant-based discriminated unions to safely encapsulate and dispatch different message types.
• Parsing and Serialization: Facilities to convert raw protocol data streams into validated, typed message instances, and vice versa, including serialization of primitive protocol values and complex message payloads.
• Protocol Traits and Introspection: Compile-time traits and utilities for detecting valid message types, aiding generic programming, static dispatch, and template specialization.
• Protocol Framing and Special Bytes: Constants and conventions (e.g., SOH, STX, ETX markers, message termination sequences) adhering to the Simple Communication Protocol to ensure reliable framing and parsing.
• Binary Data Support: Definitions and serialization support for binary data payloads within messages, including images and color data.
• Robust Error Reporting: Message types dedicated to error signaling with rich diagnostic information to facilitate debugging and recovery.
• Human-Readable String Representations: Methods to produce textual representations of messages for logging, monitoring, and diagnostics.

This module is designed with maintainability and extensibility in mind, enabling the protocol to evolve without breaking existing communication contracts.

Typedef Documentation

BinaryDataBuffer

using irsol::protocol::BinaryDataBuffer = typedef internal::BinaryData<2, 1>

1-dimensional binary data buffer with 2 bytes per element.

Definition at line 196 of file binary.hpp.

ColorImageBinaryData

using irsol::protocol::ColorImageBinaryData = typedef internal::BinaryData<2, 3>

3-dimensional binary data buffer with 2 bytes per element (e.g., color images).

Definition at line 208 of file binary.hpp.

ImageBinaryData

using irsol::protocol::ImageBinaryData = typedef internal::BinaryData<2, 2>

2-dimensional binary data buffer with 2 bytes per element (e.g., grayscale images).

Definition at line 202 of file binary.hpp.

InMessage

using irsol::protocol::InMessage = typedef std::variant<Assignment, Inquiry, Command>

Variant type representing any incoming message.

This variant holds one of the possible incoming message types:

• Assignment
• Inquiry
• Command

Definition at line 86 of file variants.hpp.

OutMessage

using irsol::protocol::OutMessage = typedef std::variant<Success, BinaryDataBuffer, ImageBinaryData, ColorImageBinaryData, Error>

Variant type representing any outgoing message.

This variant holds one of the possible outgoing message types:

• Success
• BinaryDataBuffer
• ImageBinaryData (black & white)
• ColorImageBinaryData
• Error

Definition at line 148 of file variants.hpp.

Enumeration Type Documentation

InMessageKind

enum class irsol::protocol::InMessageKind

strong

Represents the type of an incoming message.

Incoming messages are categorized into three kinds:

• ASSIGNMENT: Messages that assign values or configurations.
• INQUIRY: Messages that request information.
• COMMAND: Messages that trigger actions.

Enumerator
ASSIGNMENT
INQUIRY
COMMAND

Definition at line 44 of file variants.hpp.

{
  ASSIGNMENT,
  INQUIRY,
  COMMAND
};

OutMessageKind

enum class irsol::protocol::OutMessageKind

strong

Represents the type of an outgoing message.

Outgoing messages are categorized into:

• SUCCESS: Acknowledgement of successful operation.
• BINARY_BUFFER: Raw binary data payload.
• BW_IMAGE: Black & White image data.
• COLOR_IMAGE: Color image data.
• ERROR: Error message.

Enumerator
SUCCESS
BINARY_BUFFER
BW_IMAGE
COLOR_IMAGE
ERROR

Definition at line 99 of file variants.hpp.

{
  SUCCESS,
  BINARY_BUFFER,
  BW_IMAGE,
  COLOR_IMAGE,
  ERROR
};

Function Documentation

getInMessageKind() [1/2]

InMessageKind irsol::protocol::getInMessageKind

(

const InMessage &

msg

)

Returns the InMessageKind enum value for a given incoming message variant.

Parameters

msg	The incoming message variant.

Returns

The corresponding InMessageKind value.

Definition at line 53 of file variants.cpp.

{
  return std::visit(
    [](auto&& value) -> InMessageKind {
      using T = std::decay_t<decltype(value)>;
      return getInMessageKind<T>(value);
    },
    msg);
}

getInMessageKind() [2/2]

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>

constexpr InMessageKind irsol::protocol::getInMessageKind ( IRSOL_MAYBE_UNUSED const T &  msg )

constexpr

Returns the InMessageKind enum value corresponding to a given incoming message type.

Template Parameters

T	The concrete incoming message type.

Parameters

msg	The incoming message instance (unused).

Returns

The corresponding InMessageKind value.

Note

This function is constexpr and uses SFINAE to constrain T to be one of the InMessage variant types.

Definition at line 178 of file variants.hpp.

{
  if constexpr(std::is_same_v<T, Assignment>)
    return InMessageKind::ASSIGNMENT;
  else if constexpr(std::is_same_v<T, Inquiry>)
    return InMessageKind::INQUIRY;
  else if constexpr(std::is_same_v<T, Command>)
    return InMessageKind::COMMAND;
  else
    IRSOL_MISSING_TEMPLATE_SPECIALIZATION(T, "getInMessageKind()");
}

getOutMessageKind() [1/2]

OutMessageKind irsol::protocol::getOutMessageKind

(

const OutMessage &

msg

)

Returns the OutMessageKind enum value for a given outgoing message variant.

Parameters

msg	The outgoing message variant.

Returns

The corresponding OutMessageKind value.

Definition at line 82 of file variants.cpp.

{
  return std::visit(
    [](auto&& value) -> OutMessageKind {
      using T = std::decay_t<decltype(value)>;
      return getOutMessageKind<T>(value);
    },
    msg);
}

getOutMessageKind() [2/2]

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr OutMessageKind irsol::protocol::getOutMessageKind ( IRSOL_MAYBE_UNUSED const T &  msg )

constexpr

Returns the OutMessageKind enum value corresponding to a given outgoing message type.

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance (unused).

Returns

The corresponding OutMessageKind value.

Note

This function is constexpr and uses SFINAE to constrain T to be one of the OutMessage variant types.

Definition at line 254 of file variants.hpp.

{
  if constexpr(std::is_same_v<T, Success>)
    return OutMessageKind::SUCCESS;
  else if constexpr(std::is_same_v<T, Error>)
    return OutMessageKind::ERROR;
  else if constexpr(std::is_same_v<T, BinaryDataBuffer>)
    return OutMessageKind::BINARY_BUFFER;
  else if constexpr(std::is_same_v<T, ImageBinaryData>)
    return OutMessageKind::BW_IMAGE;
  else if constexpr(std::is_same_v<T, ColorImageBinaryData>)
    return OutMessageKind::COLOR_IMAGE;
  else
    IRSOL_MISSING_TEMPLATE_SPECIALIZATION(T, "getOutMessageKind()");
}

InMessageKindToString()

constexpr const char * irsol::protocol::InMessageKindToString ( InMessageKind  kind )

constexpr

Converts an InMessageKind enum to a human-readable string.

Parameters

kind	The InMessageKind value to convert.

Returns

A string representation of the given InMessageKind.

Note

This function is constexpr and can be used in compile-time contexts.

Definition at line 59 of file variants.hpp.

{
  switch(kind) {
    case InMessageKind::ASSIGNMENT:
      return "ASSIGNMENT";
    case InMessageKind::INQUIRY:
      return "INQUIRY";
    case InMessageKind::COMMAND:
      return "COMMAND";
  }
  IRSOL_UNREACHABLE();
}

isAssignment()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>

constexpr bool irsol::protocol::isAssignment ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given incoming message type is an Assignment.

Template Parameters

T	The concrete incoming message type.

Parameters

msg	The incoming message instance.

Returns

True if T is Assignment, false otherwise.

Definition at line 207 of file variants.hpp.

{
  return std::is_same_v<T, Assignment>;
}

isBinaryDataBuffer()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr bool irsol::protocol::isBinaryDataBuffer ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given outgoing message type is BinaryDataBuffer.

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance.

Returns

True if T is BinaryDataBuffer, false otherwise.

Definition at line 302 of file variants.hpp.

{
  return std::is_same_v<T, BinaryDataBuffer>;
}

isColorImageBinaryData()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr bool irsol::protocol::isColorImageBinaryData ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given outgoing message type is ColorImageBinaryData.

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance.

Returns

True if T is ColorImageBinaryData, false otherwise.

Definition at line 332 of file variants.hpp.

{
  return std::is_same_v<T, ColorImageBinaryData>;
}

isCommand()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>

constexpr bool irsol::protocol::isCommand ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given incoming message type is a Command.

Template Parameters

T	The concrete incoming message type.

Parameters

msg	The incoming message instance.

Returns

True if T is Command, false otherwise.

Definition at line 237 of file variants.hpp.

{
  return std::is_same_v<T, Command>;
}

isError()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr bool irsol::protocol::isError ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given outgoing message type is Error.

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance.

Returns

True if T is Error, false otherwise.

Definition at line 347 of file variants.hpp.

{
  return std::is_same_v<T, Error>;
}

isImageBinaryData()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr bool irsol::protocol::isImageBinaryData ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given outgoing message type is ImageBinaryData (black & white).

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance.

Returns

True if T is ImageBinaryData, false otherwise.

Definition at line 317 of file variants.hpp.

{
  return std::is_same_v<T, ImageBinaryData>;
}

isInquiry()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, InMessage >, int > = 0>

constexpr bool irsol::protocol::isInquiry ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given incoming message type is an Inquiry.

Template Parameters

T	The concrete incoming message type.

Parameters

msg	The incoming message instance.

Returns

True if T is Inquiry, false otherwise.

Definition at line 222 of file variants.hpp.

{
  return std::is_same_v<T, Inquiry>;
}

isSuccess()

template<typename T , std::enable_if_t< irsol::traits::is_type_in_variant_v< T, OutMessage >, int > = 0>

constexpr bool irsol::protocol::isSuccess ( IRSOL_MAYBE_UNUSED T &  msg )

constexpr

Checks if a given outgoing message type is Success.

Template Parameters

T	The concrete outgoing message type.

Parameters

msg	The outgoing message instance.

Returns

True if T is Success, false otherwise.

Definition at line 287 of file variants.hpp.

{
  return std::is_same_v<T, Success>;
}

OutMessageKindToString()

constexpr const char * irsol::protocol::OutMessageKindToString ( OutMessageKind  kind )

constexpr

Converts an OutMessageKind enum to a human-readable string.

Parameters

kind	The OutMessageKind value to convert.

Returns

A string representation of the given OutMessageKind.

Note

This function is constexpr and can be used in compile-time contexts.

Definition at line 116 of file variants.hpp.

{
  switch(kind) {
    case OutMessageKind::SUCCESS:
      return "SUCCESS";
    case OutMessageKind::BINARY_BUFFER:
      return "BINARY_BUFFER";
    case OutMessageKind::BW_IMAGE:
      return "BW_IMAGE";
    case OutMessageKind::COLOR_IMAGE:
      return "COLOR_IMAGE";
    case OutMessageKind::ERROR:
      return "ERROR";
  }
  IRSOL_UNREACHABLE();
}

toString() [1/2]

std::string irsol::protocol::toString

(

const InMessage &

msg

)

Converts an incoming message variant to a human-readable string.

Parameters

msg	The incoming message variant.

Returns

A string representation of the contained message.

Definition at line 19 of file variants.cpp.

{
  if(isAssignment(msg)) {
    return std::get<Assignment>(msg).toString();
  } else if(isInquiry(msg)) {
    return std::get<Inquiry>(msg).toString();
  } else if(isCommand(msg)) {
    return std::get<Command>(msg).toString();
  } else {
    IRSOL_ASSERT_FALSE("Unknown in message type");
    throw std::invalid_argument("Unknown in message type");
  }
}

toString() [2/2]

std::string irsol::protocol::toString

(

const OutMessage &

msg

)

Converts an outgoing message variant to a human-readable string.

Parameters

msg	The outgoing message variant.

Returns

A string representation of the contained message.

Definition at line 34 of file variants.cpp.

{
  if(isSuccess(msg)) {
    return std::get<Success>(msg).toString();
  } else if(isError(msg)) {
    return std::get<Error>(msg).toString();
  } else if(isBinaryDataBuffer(msg)) {
    return std::get<BinaryDataBuffer>(msg).toString();
  } else if(isImageBinaryData(msg)) {
    return std::get<ImageBinaryData>(msg).toString();
  } else if(isColorImageBinaryData(msg)) {
    return std::get<ColorImageBinaryData>(msg).toString();
  } else {
    IRSOL_ASSERT_FALSE("Unknown out message type");
    throw std::invalid_argument("Unknown out message type");
  }
}