NanoOcp
Minimal AES70 / OCP.1 TCP client/server library for d&b Soundscape devices
Loading...
Searching...
No Matches
NanoOcp1::Variant Class Reference

Type-erased OCA parameter value with built-in marshal/unmarshal support. More...

#include <Variant.h>

Public Member Functions

 Variant (bool v)
 Constructs a Variant holding a boolean value.
 
 Variant (std::int32_t v)
 Constructs a Variant holding a signed 32-bit integer.
 
 Variant (std::uint8_t v)
 Constructs a Variant holding an unsigned 8-bit integer.
 
 Variant (std::uint16_t v)
 Constructs a Variant holding an unsigned 16-bit integer.
 
 Variant (std::uint32_t v)
 Constructs a Variant holding an unsigned 32-bit integer.
 
 Variant (std::uint64_t v)
 Constructs a Variant holding an unsigned 64-bit integer.
 
 Variant (std::float_t v)
 Constructs a Variant holding a 32-bit float.
 
 Variant (std::double_t v)
 Constructs a Variant holding a 64-bit double.
 
 Variant (const std::string &v)
 Constructs a Variant holding a string value.
 
 Variant (const char *v)
 Constructs a Variant holding a string value (C-string overload).
 
 Variant (std::float_t x, std::float_t y, std::float_t z)
 Constructs a Variant holding a 3D position as a 12-byte blob (3 × big-endian float32). This is the preferred way to build a value for SetValueCommand on a dbOcaObjectDef_Positioning_Source_Position.
 
 Variant ()=default
 
 Variant (const std::vector< std::uint8_t > &data, Ocp1DataType type=OCP1DATATYPE_BLOB)
 
virtual ~Variant ()=default
 
bool operator== (const Variant &other) const
 Returns true if both Variants hold the same type and value.
 
bool operator!= (const Variant &other) const
 Returns true if the Variants differ in type or value.
 
bool IsValid () const
 
Ocp1DataType GetDataType () const
 
std::vector< std::uint8_t > ToParamData (Ocp1DataType type=OCP1DATATYPE_NONE, bool *pOk=nullptr) const
 
std::array< std::float_t, 3 > ToPosition (bool *pOk=nullptr) const
 
std::string ToPositionString (bool *pOk=nullptr) const
 
std::array< std::float_t, 6 > ToAimingAndPosition (bool *pOk=nullptr) const
 
std::array< std::float_t, 6 > ToPositionAndRotation (bool *pOk=nullptr) const
 
std::string ToAimingAndPositionString (bool *pOk=nullptr) const
 
std::vector< bool > ToBoolVector (bool *pOk=nullptr) const
 
std::vector< std::string > ToStringVector (bool *pOk=nullptr) const
 
Primitive type conversions

Extract the Variant's value as a specific primitive C++ type.

All methods accept an optional pOk output parameter. If provided, it is set to true on success and false if the conversion is not possible (e.g. the internal type is incompatible with the requested type). On failure a default value (0, false, or empty string) is returned.

Cross-type numeric conversions between primitive types are generally supported but may involve narrowing or signedness changes (e.g. ToUInt8() on a float Variant truncates the fractional part and clamps to [0, 255]).

bool ToBool (bool *pOk=nullptr) const
 Returns the value as bool. Numeric types: non-zero = true.
 
std::int32_t ToInt32 (bool *pOk=nullptr) const
 Returns the value as int32_t. Numeric widening/narrowing applied as needed.
 
std::uint8_t ToUInt8 (bool *pOk=nullptr) const
 Returns the value as uint8_t. Values outside [0, 255] are clamped/truncated.
 
std::uint16_t ToUInt16 (bool *pOk=nullptr) const
 Returns the value as uint16_t.
 
std::uint32_t ToUInt32 (bool *pOk=nullptr) const
 Returns the value as uint32_t.
 
std::uint64_t ToUInt64 (bool *pOk=nullptr) const
 Returns the value as uint64_t.
 
std::float_t ToFloat (bool *pOk=nullptr) const
 Returns the value as float_t (32-bit). Conversion from double loses precision.
 
std::double_t ToDouble (bool *pOk=nullptr) const
 Returns the value as double_t (64-bit).
 
std::string ToString (bool *pOk=nullptr) const
 Returns the value as a std::string. Only succeeds if the internal type is TypeString; numeric types are not auto-converted. For a human-readable representation of numeric types, use ToPositionString() etc.
 

Protected Types

enum  TypeIndex {
  TypeNone = 0 ,
  TypeBool ,
  TypeInt32 ,
  TypeUInt8 ,
  TypeUInt16 ,
  TypeUInt32 ,
  TypeUInt64 ,
  TypeFloat ,
  TypeDouble ,
  TypeString ,
  TypeByteVector
}
 Compact index enum for the internal std::variant alternative types. More...
 
using VariantType = std::variant< std::monostate, bool, std::int32_t, std::uint8_t, std::uint16_t, std::uint32_t, std::uint64_t, std::float_t, std::double_t, std::string, std::vector< std::uint8_t > >
 The underlying std::variant that holds the actual value.
 

Protected Member Functions

std::vector< std::uint8_t > ToByteVector (bool *pOk=nullptr) const
 

Detailed Description

Type-erased OCA parameter value with built-in marshal/unmarshal support.

Variant wraps a std::variant holding one of the native C++ types that map to AES70 base data types. It adds two capabilities beyond a plain std::variant:

  • Mutability / cross-type conversion — A Variant can be constructed with one type and later read as a different primitive type via the To<T>() methods. Cross-type conversions between primitive types (e.g. ToFloat() on a uint16_t Variant) are supported but may involve narrowing or sign changes. Conversions between fundamentally incompatible types (e.g. ToString() on a float Variant) will set *pOk = false and return a default value.
  • OCP.1 marshaling / unmarshaling — A Variant can be constructed directly from a raw ByteVector received in an Ocp1Response or Ocp1Notification, and it can be serialized back to bytes via ToParamData() for use in a SetValueCommand.

Typical usage in NanoOcp

Constructing a value to send (SetValue)

// Set sound-object position to (x=0.5, y=0.5, z=0.0):
NanoOcp1::Variant pos(0.5f, 0.5f, 0.0f);
uint32_t handle;
auto cmd = NanoOcp1::Ocp1CommandResponseRequired(def.SetValueCommand(pos), handle);
client->sendData(cmd.GetSerializedData());
Type-erased OCA parameter value with built-in marshal/unmarshal support.
Definition Variant.h:102
OCA definition for a sound object's 3D position in real-world space (En-Scene).

Decoding a received value (Notification / Response)

// Inside onDataReceived, after UnmarshalOcp1Message():
auto* notif = static_cast<NanoOcp1::Ocp1Notification*>(msg.get());
NanoOcp1::Variant v(notif->GetParameterData(), NanoOcp1::OCP1DATATYPE_BLOB);
// 3D position (source):
auto [x, y, z] = v.ToPosition();
// 6-DOF loudspeaker position:
auto [hor, vert, rot, x, y, z] = v.ToAimingAndPosition();
// Simple scalar:
bool ok;
float gain = v.ToFloat(&ok);
if (!ok) { handleError(); }
@ OCP1DATATYPE_BLOB
Variable-length binary blob; layout is property-specific.

DeviceController (Umsci) pattern

DeviceController::UpdateObjectValue() uses the unmarshaling constructor to decode incoming Ocp1Notification and Ocp1Response parameter data, using the Ocp1DataType stored in the matching Ocp1CommandDefinition to guide deserialization. The resulting Variant is stored in a RemoteObject and delivered to onRemoteObjectReceived on the JUCE message thread.

Supported types

Constructor Internal TypeIndex GetDataType() returns
Variant(bool) TypeBool OCP1DATATYPE_BOOLEAN
Variant(int32_t) TypeInt32 OCP1DATATYPE_INT32
Variant(uint8_t) TypeUInt8 OCP1DATATYPE_UINT8
Variant(uint16_t) TypeUInt16 OCP1DATATYPE_UINT16
Variant(uint32_t) TypeUInt32 OCP1DATATYPE_UINT32
Variant(uint64_t) TypeUInt64 OCP1DATATYPE_UINT64
Variant(float_t) TypeFloat OCP1DATATYPE_FLOAT32
Variant(double_t) TypeDouble OCP1DATATYPE_FLOAT64
Variant(string) TypeString OCP1DATATYPE_STRING
Variant(float x, float y, float z) TypeByteVector OCP1DATATYPE_BLOB
Variant(ByteVector, type) TypeByteVector OCP1DATATYPE_BLOB
Variant() (default) TypeNone OCP1DATATYPE_NONE; invalid until set

Definition at line 101 of file Variant.h.

Member Typedef Documentation

◆ VariantType

using NanoOcp1::Variant::VariantType = std::variant<std::monostate, bool, std::int32_t, std::uint8_t, std::uint16_t, std::uint32_t, std::uint64_t, std::float_t, std::double_t, std::string, std::vector<std::uint8_t> >
protected

The underlying std::variant that holds the actual value.

The active alternative is identified by the TypeIndex enum. std::monostate (TypeNone) is the default; constructing a Variant() with no arguments leaves it in this state. IsValid() returns false in that state.

Definition at line 318 of file Variant.h.

Member Enumeration Documentation

◆ TypeIndex

Compact index enum for the internal std::variant alternative types.

Mirrors Ocp1DataType but is contiguous (no gaps) as required by std::variant. GetDataType() maps from TypeIndex back to the corresponding Ocp1DataType. Used internally by ToByteVector() and ToParamData() to select the correct serialization path.

Enumerator
TypeNone 

Default / unset state (std::monostate). IsValid() returns false.

TypeBool 

bool

TypeInt32 

std::int32_t

TypeUInt8 

std::uint8_t

TypeUInt16 

std::uint16_t

TypeUInt32 

std::uint32_t

TypeUInt64 

std::uint64_t

TypeFloat 

std::float_t (32-bit IEEE 754)

TypeDouble 

std::double_t (64-bit IEEE 754)

TypeString 

std::string (OCA string: 2-byte length prefix + UTF-8 bytes)

TypeByteVector 

std::vector<uint8_t> — used for blobs and multi-float spatial types

Definition at line 296 of file Variant.h.

Constructor & Destructor Documentation

◆ Variant() [1/13]

NanoOcp1::Variant::Variant ( bool  v)

Constructs a Variant holding a boolean value.

Definition at line 27 of file Variant.cpp.

◆ Variant() [2/13]

NanoOcp1::Variant::Variant ( std::int32_t  v)

Constructs a Variant holding a signed 32-bit integer.

Definition at line 28 of file Variant.cpp.

◆ Variant() [3/13]

NanoOcp1::Variant::Variant ( std::uint8_t  v)

Constructs a Variant holding an unsigned 8-bit integer.

Definition at line 29 of file Variant.cpp.

◆ Variant() [4/13]

NanoOcp1::Variant::Variant ( std::uint16_t  v)

Constructs a Variant holding an unsigned 16-bit integer.

Definition at line 30 of file Variant.cpp.

◆ Variant() [5/13]

NanoOcp1::Variant::Variant ( std::uint32_t  v)

Constructs a Variant holding an unsigned 32-bit integer.

Definition at line 31 of file Variant.cpp.

◆ Variant() [6/13]

NanoOcp1::Variant::Variant ( std::uint64_t  v)

Constructs a Variant holding an unsigned 64-bit integer.

Definition at line 32 of file Variant.cpp.

◆ Variant() [7/13]

NanoOcp1::Variant::Variant ( std::float_t  v)

Constructs a Variant holding a 32-bit float.

Definition at line 33 of file Variant.cpp.

◆ Variant() [8/13]

NanoOcp1::Variant::Variant ( std::double_t  v)

Constructs a Variant holding a 64-bit double.

Definition at line 34 of file Variant.cpp.

◆ Variant() [9/13]

NanoOcp1::Variant::Variant ( const std::string &  v)

Constructs a Variant holding a string value.

Definition at line 35 of file Variant.cpp.

◆ Variant() [10/13]

NanoOcp1::Variant::Variant ( const char *  v)

Constructs a Variant holding a string value (C-string overload).

Definition at line 36 of file Variant.cpp.

◆ Variant() [11/13]

NanoOcp1::Variant::Variant ( std::float_t  x,
std::float_t  y,
std::float_t  z 
)

Constructs a Variant holding a 3D position as a 12-byte blob (3 × big-endian float32). This is the preferred way to build a value for SetValueCommand on a dbOcaObjectDef_Positioning_Source_Position.

Parameters
xNormalised X position [0.0, 1.0].
yNormalised Y position [0.0, 1.0].
zNormalised Z position [0.0, 1.0].

Definition at line 38 of file Variant.cpp.

◆ Variant() [12/13]

NanoOcp1::Variant::Variant ( )
default

Default constructor. Type-less and value-less per default, and will return FALSE on IsValid as such.

◆ Variant() [13/13]

◆ ~Variant()

virtual NanoOcp1::Variant::~Variant ( )
virtualdefault

Member Function Documentation

◆ GetDataType()

◆ IsValid()

bool NanoOcp1::Variant::IsValid ( ) const

Check if this Variant has a valid value and type, i.e. different than the default TypeNone (std::monostate).

Note
A Variant has no value or type per default.
Returns
True if this Variant is valid.

Definition at line 135 of file Variant.cpp.

References TypeNone.

◆ operator!=()

bool NanoOcp1::Variant::operator!= ( const Variant other) const

Returns true if the Variants differ in type or value.

Definition at line 130 of file Variant.cpp.

◆ operator==()

bool NanoOcp1::Variant::operator== ( const Variant other) const

Returns true if both Variants hold the same type and value.

Definition at line 125 of file Variant.cpp.

◆ ToAimingAndPosition()

std::array< std::float_t, 6 > NanoOcp1::Variant::ToAimingAndPosition ( bool *  pOk = nullptr) const

Convenience helper method to extract x, y, z, horizontal angle (yaw), vertical angle (pitch) and rotation angle (roll) float values from a Variant.

Note
The aiming angles are unmarshaled first and the position second, to keep in line with the CdbOcaAimingAndPosition::Unmarshal method.
Parameters
[in]pOkOptional parameter to verify if the conversion was successful.
Returns
The contained values in the order: hor, ver, rot, x, y, z.

Definition at line 675 of file Variant.cpp.

References NanoOcp1::DataToFloat(), and TypeByteVector.

Referenced by ToAimingAndPositionString(), and ToPositionAndRotation().

◆ ToAimingAndPositionString()

std::string NanoOcp1::Variant::ToAimingAndPositionString ( bool *  pOk = nullptr) const

Calls ToAimingAndPosition and returns a human-readable string with the result.

Parameters
[in]pOkOptional parameter to verify if the ToAimingAndPosition call was successful.
Returns
A string in the format: "hor, ver, rot, x, y, z".

Definition at line 714 of file Variant.cpp.

References ToAimingAndPosition().

◆ ToBool()

bool NanoOcp1::Variant::ToBool ( bool *  pOk = nullptr) const

Returns the value as bool. Numeric types: non-zero = true.

Definition at line 161 of file Variant.cpp.

References NanoOcp1::DataToBool(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToBoolVector()

std::vector< bool > NanoOcp1::Variant::ToBoolVector ( bool *  pOk = nullptr) const

Convenience helper method to extract a std::vector<bool> from a from a Variant. The Variant's contents need to be marshalled as an OcaList<OcaBoolean>.

Parameters
[in]pOkOptional parameter to verify if the conversion was successful.
Returns
The resulting OcaList<OcaBoolean> as a std::vector<bool>.

Definition at line 735 of file Variant.cpp.

References NanoOcp1::DataToBool(), NanoOcp1::DataToUint16(), and TypeByteVector.

◆ ToByteVector()

ByteVector NanoOcp1::Variant::ToByteVector ( bool *  pOk = nullptr) const
protected

Marshals the Variant into a byte vector using a format based on the Variant's native type.

Parameters
[in]pOkOptional parameter to verify if the conversion was successful.
Returns
The Variant's byte vector representation.

Definition at line 534 of file Variant.cpp.

References NanoOcp1::DataFromBool(), NanoOcp1::DataFromDouble(), NanoOcp1::DataFromFloat(), NanoOcp1::DataFromInt32(), NanoOcp1::DataFromString(), NanoOcp1::DataFromUint16(), NanoOcp1::DataFromUint32(), NanoOcp1::DataFromUint64(), NanoOcp1::DataFromUint8(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToDouble()

std::double_t NanoOcp1::Variant::ToDouble ( bool *  pOk = nullptr) const

Returns the value as double_t (64-bit).

Definition at line 412 of file Variant.cpp.

References NanoOcp1::DataToDouble(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToFloat()

std::float_t NanoOcp1::Variant::ToFloat ( bool *  pOk = nullptr) const

Returns the value as float_t (32-bit). Conversion from double loses precision.

Definition at line 455 of file Variant.cpp.

References NanoOcp1::DataToFloat(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToInt32()

std::int32_t NanoOcp1::Variant::ToInt32 ( bool *  pOk = nullptr) const

Returns the value as int32_t. Numeric widening/narrowing applied as needed.

Definition at line 197 of file Variant.cpp.

References NanoOcp1::DataToInt32(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToParamData()

◆ ToPosition()

std::array< std::float_t, 3 > NanoOcp1::Variant::ToPosition ( bool *  pOk = nullptr) const

Convenience helper method to extract x, y, and z float values from a Variant. The Variant should internally contain the values as 3 x 4 bytes.

Parameters
[in]pOkOptional parameter to verify if the conversion was successful.
Returns
The contained x, y, and z values.

Definition at line 619 of file Variant.cpp.

References NanoOcp1::DataToFloat(), and TypeByteVector.

Referenced by ToPositionString().

◆ ToPositionAndRotation()

std::array< std::float_t, 6 > NanoOcp1::Variant::ToPositionAndRotation ( bool *  pOk = nullptr) const

Definition at line 670 of file Variant.cpp.

References ToAimingAndPosition().

◆ ToPositionString()

std::string NanoOcp1::Variant::ToPositionString ( bool *  pOk = nullptr) const

Calls ToPosition and returns a human-readable string with the result.

Parameters
[in]pOkOptional parameter to verify if the ToPosition call was successful.
Returns
A string in the format "x, y, z".

Definition at line 650 of file Variant.cpp.

References ToPosition().

◆ ToString()

std::string NanoOcp1::Variant::ToString ( bool *  pOk = nullptr) const

Returns the value as a std::string. Only succeeds if the internal type is TypeString; numeric types are not auto-converted. For a human-readable representation of numeric types, use ToPositionString() etc.

Definition at line 498 of file Variant.cpp.

References NanoOcp1::DataToString(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToStringVector()

std::vector< std::string > NanoOcp1::Variant::ToStringVector ( bool *  pOk = nullptr) const

Convenience helper method to extract a std::vector<std::string> from a from a Variant. The Variant's contents need to be marshalled as an OcaList<OcaString>.

Parameters
[in]pOkOptional parameter to verify if the conversion was successful.
Returns
The resulting OcaList<OcaBoolean> as a std::vector<bool>.

Definition at line 775 of file Variant.cpp.

References NanoOcp1::DataToUint16(), and TypeByteVector.

◆ ToUInt16()

std::uint16_t NanoOcp1::Variant::ToUInt16 ( bool *  pOk = nullptr) const

Returns the value as uint16_t.

Definition at line 283 of file Variant.cpp.

References NanoOcp1::DataToUint16(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToUInt32()

std::uint32_t NanoOcp1::Variant::ToUInt32 ( bool *  pOk = nullptr) const

Returns the value as uint32_t.

Definition at line 326 of file Variant.cpp.

References NanoOcp1::DataToUint32(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToUInt64()

std::uint64_t NanoOcp1::Variant::ToUInt64 ( bool *  pOk = nullptr) const

Returns the value as uint64_t.

Definition at line 369 of file Variant.cpp.

References NanoOcp1::DataToUint64(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().

◆ ToUInt8()

std::uint8_t NanoOcp1::Variant::ToUInt8 ( bool *  pOk = nullptr) const

Returns the value as uint8_t. Values outside [0, 255] are clamped/truncated.

Definition at line 240 of file Variant.cpp.

References NanoOcp1::DataToUint8(), TypeBool, TypeByteVector, TypeDouble, TypeFloat, TypeInt32, TypeString, TypeUInt16, TypeUInt32, TypeUInt64, and TypeUInt8.

Referenced by ToParamData().


The documentation for this class was generated from the following files: