SOIL C++
C++ Unified Device Interface
SOIL::Variable< T, x, y > Class Template Reference

Variable Class. More...

#include <Variable.h>

Inheritance diagram for SOIL::Variable< T, x, y >:
SOIL::Figure< T, -1, -1 > SOIL::Element HTTP::Resource

Public Member Functions

 Variable (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string unit, std::string ontology="", Range< T > range=Range< T >(), TIME time=TIME(), std::string nonce="")
 Constructor. More...
 
 ~Variable ()
 Destructor. More...
 
Variable< T, x, y > & operator= (const Container< T, x, y > &value)
 Assignment operator. More...
 
HTTP::Json wjson (void) override
 HTTP JSON. More...
 
HTTP::Response handle_get (HTTP::Request message, std::smatch match=std::smatch()) override
 HTTP GET Handler. More...
 
HTTP::Response handle_options (HTTP::Request message, std::smatch match=std::smatch()) override
 HTTP OPTIONS Handler. More...
 
void update (const Container< T, x, y > &value, TIME time, std::string nonce="")
 Update value. More...
 
void set_covariance (Container< T, x, x > covariance)
 Set Covariance. More...
 
std::vector< unsigned char > bytes (void)
 Get bytewise representation. More...
 
std::vector< unsigned char > sha256 (void)
 Calculate SHA256. More...
 
std::vector< unsigned char > sign (std::shared_ptr< SIGN::Signer > signer=NULL)
 Sign the variable data. More...
 
std::vector< unsigned char > fingerprint (std::shared_ptr< SIGN::Signer > signer)
 Calculate RSA fingerprint. More...
 
std::shared_ptr< Variableptr (void)
 Get Pointer. More...
 
bool mqtt (std::shared_ptr< MQTT::Publisher > publisher, int qos=0, bool retain=false)
 Publish to MQTT. More...
 
- Public Member Functions inherited from SOIL::Figure< T, -1, -1 >
 Figure (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string unit, std::string ontology="", Range< T > range=Range< T >(), TIME time=TIME())
 Constructor. More...
 
 ~Figure ()
 Destructor. More...
 
Figure< T, x, y > & operator= (const Container< T, x, y > &value)
 Assignment operator. More...
 
Container< T, x, y > & operator* (void)
 Access Operator. More...
 
bool check_range (const Container< T, x, y > &value) const
 Check range. More...
 
void set_range (Range< T > range)
 Set Range. More...
 
void set_time (TIME time)
 Set Time. More...
 
void set_value (const Container< T, x, y > &value)
 Set Value. More...
 
HTTP::Json wjson (void) override
 HTTP JSON. More...
 
Container< T, x, y > cast (T value)
 Cast to container. More...
 
virtual void update (const Container< T, x, y > &value, TIME time)
 Update. More...
 
- Public Member Functions inherited from SOIL::Element
 Element (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string ontology="")
 Constructor. More...
 
virtual ~Element ()
 Destructor. More...
 
std::vector< std::string > fqid (void)
 FQID. More...
 
std::shared_ptr< Elementoperator[] (std::string fqid)
 Access Operator. More...
 
std::shared_ptr< Elementadd (std::string uuid, std::shared_ptr< Element > child)
 Add Child Element. More...
 
std::shared_ptr< Elementadd (std::string uuid, Element *child)
 Add Child Element. More...
 
bool insert (std::string uuid, std::shared_ptr< Element > child)
 Add Child Element. More...
 
bool insert (std::string uuid, Element *child)
 Add Child Element. More...
 
bool remove (std::string uuid)
 Remove Child element. More...
 
template<typename T >
T * cast (void)
 Get dynamically casted pointer. More...
 
bool is_object (void) const
 Is Object? More...
 
bool is_variable (void) const
 Is Variable? More...
 
bool is_function (void) const
 Is Function? More...
 
bool is_parameter (void) const
 Is Parameter? More...
 
virtual HTTP::Json wjson (void)
 HTTP JSON. More...
 
virtual std::string json (void)
 JSON string. More...
 
HTTP::Response handle (HTTP::Request request, std::smatch match=std::smatch())
 HTTP Handler. More...
 
- Public Member Functions inherited from HTTP::Resource
 Resource ()
 Constructor. More...
 
 ~Resource ()
 Default Destructor. More...
 
virtual Response handle (Request message, std::smatch match=std::smatch())
 HTTP Handler. More...
 
virtual Response handle_get (Request message, std::smatch match=std::smatch())
 HTTP GET Handler. More...
 
virtual Response handle_put (Request message, std::smatch match=std::smatch())
 HTTP PUT Handler. More...
 
virtual Response handle_post (Request message, std::smatch match=std::smatch())
 HTTP POST Handler. More...
 
virtual Response handle_delete (Request message, std::smatch match=std::smatch())
 HTTP DELETE Handler. More...
 
virtual Response handle_patch (Request message, std::smatch match=std::smatch())
 HTTP PATCH Handler. More...
 
virtual Response handle_options (Request message, std::smatch match=std::smatch())
 HTTP OPTIONS Handler. More...
 
virtual Response handle_head (Request message, std::smatch match=std::smatch())
 HTTP HEAD Handler. More...
 
virtual Response handle_exception (Request message, std::exception &exception, std::smatch match=std::smatch())
 HTTP Exception handler. More...
 

Static Public Member Functions

static std::shared_ptr< Variablecreate (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string unit, std::string ontology="", Range< T > range=Range< T >(), TIME time=TIME(), std::string nonce="")
 Create new Variable. More...
 
- Static Public Member Functions inherited from HTTP::Resource
static web::json::value request_info (Request message, std::smatch match=std::smatch())
 Request Info. More...
 

Protected Member Functions

virtual void read (void)
 Read callback. More...
 
virtual void write (void)
 Write callback. More...
 
virtual void read (void)=0
 Read callback. More...
 
virtual void write (void)=0
 Write callback. More...
 
- Protected Member Functions inherited from HTTP::Resource
void apply_headers (Response &response)
 Apply headers. More...
 

Protected Attributes

std::string nonce
 Nonce. More...
 
std::vector< unsigned char > hash
 Checking Hash. More...
 
Container< T, x, x > covariance
 Covariance of the value. More...
 
- Protected Attributes inherited from SOIL::Figure< T, -1, -1 >
TIME time
 Data Timestamp. More...
 
std::string unit
 Unit. More...
 
Container< T, x, y > value
 Value. More...
 
Range< T > range
 Range. More...
 
- Protected Attributes inherited from HTTP::Resource
std::vector< web::http::method > allowed_methods
 Allowed methods. More...
 
std::string content_type
 Content type. More...
 
std::string allowed_origins
 Allowed Origins. More...
 

Additional Inherited Members

- Public Attributes inherited from SOIL::Element
std::map< std::string, std::shared_ptr< Element > > children
 Children Map. More...
 
std::shared_ptr< Elementparent
 Parent Pointer. More...
 
std::shared_ptr< Elementself
 Self Pointer. More...
 
std::string uuid
 Local UUID. More...
 
std::string name
 Name. More...
 
std::string description
 Description. More...
 
std::string ontology
 Ontology identifier. More...
 
std::recursive_mutex mutex
 Element Mutex. More...
 

Detailed Description

template<typename T, int x = -1, int y = -1>
class SOIL::Variable< T, x, y >

This class represents a SOIL Variable. Parameter and Variable share many common properties and therefore both inherit from Figure, such that methods there should be considered in any case. Variables are primarily intended for values that represent any measurement or physical phenomenon outside the immediate control of device. In contrast to parameter, they cannot be set externally and may not be constant. In addition, they contain a custom message (nonce), a hash (for traceability purposes) and a covariance property. The covariance should represent uncertainty as multivariate normal distribution with coverage factor of 1.

Covariance is currently not supported for 2-dimensional data (i.e. which would lead to a 4-dimensional covariance expression)

In lightweight scenarios, this class may be instantiated directly, for more specific scenarios, it shouls be subclassed and override the implementation of read().

A parameter supports HTTP GET (read) and HTTP OPTIONS (read without updating value) verbs.

The data management of Figure and hence Parameter relies on Container, such that the same templating logic is used.

Template Parameters
TType of the data.
xFirst dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1.
ySecond dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1.
Todo:
The HTTP handlers may be moved to protected if HTTP::Server is declared as friend class. Currently this is not done to alllow for greater flexibility.

Definition at line 41 of file Variable.h.

Constructor & Destructor Documentation

◆ Variable()

template<typename T , int x, int y>
SOIL::Variable< T, x, y >::Variable ( std::shared_ptr< Element parent,
std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
std::string  ontology = "",
Range< T >  range = Range<T>(),
TIME  time = TIME(),
std::string  nonce = "" 
)

Standard constructor intialiazing the values. If subclassed, it should be called from the subclass constructor.

Parameters
[in]parentShared pointer to parent object.
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]unitUNECE unit code, e.g. MTR
[in]ontologyOntology reference, is set to null if an empty string is passed
[in]rangeAllowed range for the variable values, defaults to an empty object, i.e. allowing all values
[in]timeTimestamp for the initial value, defaults to unset
[in]nonceCustom message to add to the variable, defaults to unset

Definition at line 312 of file Variable.h.

◆ ~Variable()

template<typename T , int x, int y>
SOIL::Variable< T, x, y >::~Variable

Default destructor, without custom effort.

Definition at line 323 of file Variable.h.

Member Function Documentation

◆ bytes()

template<typename T , int x, int y>
std::vector< unsigned char > SOIL::Variable< T, x, y >::bytes ( void  )
inline

Get a bytewise representation of the variable. This is constructed in the following order:

  • Dimensions in declared order
  • Value in row-major order
  • Covariane in row-major-order (cannot be null!)
  • Unit directly taken from UTF-8 chars
  • Timestamp (cf. explanation there)
  • Nonce as UTF-8 string

This function is mainly used for hashing and signing purposes. It does not write to an internal attribute.

Returns
Constructucted bytestring

Definition at line 387 of file Variable.h.

◆ create()

template<typename T , int x, int y>
std::shared_ptr< SOIL::Variable< T, x, y > > SOIL::Variable< T, x, y >::create ( std::shared_ptr< Element parent,
std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
std::string  ontology = "",
Range< T >  range = Range<T>(),
TIME  time = TIME(),
std::string  nonce = "" 
)
inlinestatic

Create a new Variable using the default constructor and return a shared pointer reference. This is the preferred method for manual creation with consistent lifecycle handling.

Parameters
[in]parentShared pointer to parent object.
[in]uuidLocally Unique identifier
[in]nameHuman-readable name
[in]descriptionHuman-readable description
[in]unitUNECE unit code, e.g. MTR
[in]ontologyOntology reference, is set to null if an empty string is passed
[in]rangeAllowed range for the variable values, defaults to an empty object, i.e. allowing all values
[in]timeTimestamp for the initial value, defaults to unset
[in]nonceCustom message to add to the variable, defaults to unset

Definition at line 328 of file Variable.h.

◆ fingerprint()

template<typename T , int x, int y>
std::vector< unsigned char > SOIL::Variable< T, x, y >::fingerprint ( std::shared_ptr< SIGN::Signer signer)
inline

Signs the sha256 hash with the private key managed by the passed instance of SIGN::Signer. Does not write to an internal attribute.

Precondition
The SIGN::Signer instance must be instialized elsewhere and have an apropriate lifecycle.
Parameters
[in]signerReference to a SIGN::Signer object holding the private key to use
Returns
Signature bytestring

Definition at line 424 of file Variable.h.

◆ handle_get()

template<typename T , int x, int y>
HTTP::Response SOIL::Variable< T, x, y >::handle_get ( HTTP::Request  message,
std::smatch  match = std::smatch() 
)
inlineoverridevirtual

Handler that is called by the server on HTTP requests on a GET method. This function returns a representation of the Variable and its current value to the requesting party. It should not be overridden directly in subclasses, instead the read() function should be overriden. It is an expected behaviour that read() calls an external method to update the value and may take some time to return. Please note that the default timeout in cpprestsdk is 120s, which is already very long. Consider an asynchronous update model if your devices takes longer to measure.

Parameters
[in]messageIncoming HTTP request as preprocessed by cpprestsdk
[in]matchMatch result of the request path that led to this resource
Returns
Outgoing HTTP response to be processed by cpprestdsk

Reimplemented from HTTP::Resource.

Definition at line 452 of file Variable.h.

◆ handle_options()

template<typename T , int x, int y>
HTTP::Response SOIL::Variable< T, x, y >::handle_options ( HTTP::Request  message,
std::smatch  match = std::smatch() 
)
inlineoverridevirtual

Handler that is called by the server on HTTP requests on a OPTIONS method. This function returns a representation of the Variable and its current stored value to the requesting party. In contrast to GET, the read() function is not called such that there are no side effects if a requesting party just wants to obtain informtion about the variable's metadata in the first place.

Parameters
[in]messageIncoming HTTP request as preprocessed by cpprestsdk
[in]matchMatch result of the request path that led to this resource
Returns
Outgoing HTTP response to be processed by cpprestdsk

Reimplemented from HTTP::Resource.

Definition at line 464 of file Variable.h.

◆ mqtt()

template<typename T , int x, int y>
bool SOIL::Variable< T, x, y >::mqtt ( std::shared_ptr< MQTT::Publisher publisher,
int  qos = 0,
bool  retain = false 
)
inline

Publish the current JSON representation under the FQID as topic using a given MQTT publisher. This function must be explicitly called from the user's code as otherwise the update cycle would depend on the publisher and the user will be left without control to call other methods before publishing.

A good pattern is to have a reference to an MQTT publisher in a sublcassing implementation and implement a complete update cycle there.

Precondition
An MQTT::Publisher must be instantiated elsewhere and have a valid lifecycle.
Parameters
[in]publisherReference to the publisher to use
[in]qosQuality of service to choose for MQTT message
[in]retainFlag whether to retain the message on the server.
Returns
Boolean flag whether the message was accepted in the message queue.
Todo:
Currently the implementation of this function is redundant in Variable and Parameter. It is deliberately not moved to Figure as different implementations may occur in the future, but would be a valid option.

Definition at line 444 of file Variable.h.

◆ operator=()

template<typename T , int x, int y>
SOIL::Variable< T, x, y > & SOIL::Variable< T, x, y >::operator= ( const Container< T, x, y > &  value)
inline

Assigns the value provided as container on the right hand side to the variable. Immediately resorts to the implementation in Figure internally.

Exceptions
std::range_errorThrows an exception if the value to assign is outside the allowed range.
Parameters
[in]valueValue to assign
Returns
Reference to the current Variable

Definition at line 335 of file Variable.h.

◆ ptr()

template<typename T , int x = -1, int y = -1>
std::shared_ptr< Variable > SOIL::Variable< T, x, y >::ptr ( void  )
inline

Return a shared pointer casted to the Parameter type to element itself.

Returns
Casted pointer

Definition at line 277 of file Variable.h.

◆ read()

template<typename T , int x, int y>
void SOIL::Variable< T, x, y >::read ( void  )
protectedvirtual

Read callback that can be implemented by deriving classes to perform custom build logic on read actions, e.g. update the value from an external storage. Be careful when including long-running queries as they will block the HTTP call. Declared virtual to make sure the derived method is called first. Does nothing be default.

Implements SOIL::Figure< T, -1, -1 >.

Definition at line 370 of file Variable.h.

◆ set_covariance()

template<typename T , int x, int y>
void SOIL::Variable< T, x, y >::set_covariance ( Container< T, x, x >  covariance)
inline

Set the covariance corresponding to the value. This is a separate call as the following three scenarios are foreseen:

  • The covariance is set in the user defined update cycle, so this call can directly follow update().
  • The covariance is estimated constant for all measurements, so there is no need for updating it
  • The covariance is not available, thus set to null.
Parameters
[in]covarianceCovariance provided as container object

Definition at line 380 of file Variable.h.

◆ sha256()

template<typename T , int x, int y>
std::vector< unsigned char > SOIL::Variable< T, x, y >::sha256 ( void  )
inline

Calculates the sha256 hash of the bytestring representation. Internally calls bytes(), but does not write to any value.

Returns
SHA256 hash as bytestring

Definition at line 417 of file Variable.h.

◆ sign()

template<typename T , int x, int y>
std::vector< unsigned char > SOIL::Variable< T, x, y >::sign ( std::shared_ptr< SIGN::Signer signer = NULL)
inline

Sign the measurement data. If an pointer to an instance of SIGN::Signer is passed, the fingerprint() function is used to sign the sha256 hash with the managed private key. Otherwise, the sha256() function is used.

In both cases, the resulting bytestring is stored to the internal hash attribute and returned.

Precondition
The SIGN::Signer instance must be instialized elsewhere and have an apropriate lifecycle.
Postcondition
The hash attribute is automatically updated by this call.
Parameters
[in]signerReference to a SIGN::Signer object holding the private key to use
Returns
Signature bytestring

Definition at line 430 of file Variable.h.

◆ update()

template<typename T , int x, int y>
void SOIL::Variable< T, x, y >::update ( const Container< T, x, y > &  value,
TIME  time,
std::string  nonce = "" 
)
inline

Update the value of the variable. As value, time and nonce are expected to change with each value update, the three components are passed at the same time.

Parameters
[in]valueValue to set
[in]timeTimestamp to set as corresponidng to the value
[in]nonceNonce to set as corresponding to the value

Definition at line 474 of file Variable.h.

◆ wjson()

template<typename T , int x, int y>
HTTP::Json SOIL::Variable< T, x, y >::wjson ( void  )
overridevirtual

Get a HTTP JSON object corresponding to the current state of the Parameter. This function provides a SOIL-conformant JSON representation the parameter. It internally extends the method of Figure.

Returns
JSON object

Reimplemented from SOIL::Element.

Definition at line 343 of file Variable.h.

◆ write()

template<typename T , int x, int y>
void SOIL::Variable< T, x, y >::write ( void  )
protectedvirtual

This is an empty implementation of the write() function which is needed to avoid that Variable becomes abstract. It is never called.

Implements SOIL::Figure< T, -1, -1 >.

Definition at line 375 of file Variable.h.

Member Data Documentation

◆ covariance

template<typename T , int x = -1, int y = -1>
Container<T, x, x> SOIL::Variable< T, x, y >::covariance
protected

Covariance of the value expressed as multidimensional normal distribution with coverage factor 1. The dimensionality depends on the dimensionality of the value:

  • For scalar data, the covariance is a scalar corresponding to the variance.
  • For data expanding along one dimension with length n the covariance is a matrix with dimension (n,n)
  • For data expanding along two dimensions, covariance is currently not supported.

Note that the second template argument of the Container is x in this case.

Definition at line 74 of file Variable.h.

◆ hash

template<typename T , int x = -1, int y = -1>
std::vector<unsigned char> SOIL::Variable< T, x, y >::hash
protected

Hash that is calculated from a defined binary representation of the variable and may be signed with private_key such that the integrity of the data can be verified. Is null if not explicitly set.

Todo:
This is still error prone across different languages and platforms as endianess and memory layout need to be considered.

Definition at line 61 of file Variable.h.

◆ nonce

template<typename T , int x = -1, int y = -1>
std::string SOIL::Variable< T, x, y >::nonce
protected

Nonce with is considered as arbitrary message that the user may add to the measurement. This could be JOB-IDs or similar.

Definition at line 51 of file Variable.h.


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