SOIL C++
C++ Unified Device Interface
|
#include <Variable.h>
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< Variable > | ptr (void) |
Get Pointer. More... | |
bool | mqtt (std::shared_ptr< MQTT::Publisher > publisher, int qos=0, bool retain=false) |
Publish to MQTT. More... | |
![]() | |
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... | |
![]() | |
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< Element > | operator[] (std::string fqid) |
Access Operator. More... | |
std::shared_ptr< Element > | add (std::string uuid, std::shared_ptr< Element > child) |
Add Child Element. More... | |
std::shared_ptr< Element > | add (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... | |
![]() | |
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< Variable > | 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="") |
Create new Variable. More... | |
![]() | |
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... | |
![]() | |
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... | |
![]() | |
TIME | time |
Data Timestamp. More... | |
std::string | unit |
Unit. More... | |
Container< T, x, y > | value |
Value. More... | |
Range< T > | range |
Range. More... | |
![]() | |
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 | |
![]() | |
std::map< std::string, std::shared_ptr< Element > > | children |
Children Map. More... | |
std::shared_ptr< Element > | parent |
Parent Pointer. More... | |
std::shared_ptr< Element > | self |
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... | |
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.
T | Type of the data. |
x | First dimension of the data. -1 means unused, 0 means arbitray size. Cannot be -1 if y is not -1. |
y | Second dimension of the data. -1 means unused, 0 means arbitray size. Must be -1 for x to be -1. |
Definition at line 41 of file Variable.h.
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.
[in] | parent | Shared pointer to parent object. |
[in] | uuid | Locally Unique identifier |
[in] | name | Human-readable name |
[in] | description | Human-readable description |
[in] | unit | UNECE unit code, e.g. MTR |
[in] | ontology | Ontology reference, is set to null if an empty string is passed |
[in] | range | Allowed range for the variable values, defaults to an empty object, i.e. allowing all values |
[in] | time | Timestamp for the initial value, defaults to unset |
[in] | nonce | Custom message to add to the variable, defaults to unset |
Definition at line 312 of file Variable.h.
SOIL::Variable< T, x, y >::~Variable |
Default destructor, without custom effort.
Definition at line 323 of file Variable.h.
|
inline |
Get a bytewise representation of the variable. This is constructed in the following order:
This function is mainly used for hashing and signing purposes. It does not write to an internal attribute.
Definition at line 387 of file Variable.h.
|
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.
[in] | parent | Shared pointer to parent object. |
[in] | uuid | Locally Unique identifier |
[in] | name | Human-readable name |
[in] | description | Human-readable description |
[in] | unit | UNECE unit code, e.g. MTR |
[in] | ontology | Ontology reference, is set to null if an empty string is passed |
[in] | range | Allowed range for the variable values, defaults to an empty object, i.e. allowing all values |
[in] | time | Timestamp for the initial value, defaults to unset |
[in] | nonce | Custom message to add to the variable, defaults to unset |
Definition at line 328 of file Variable.h.
|
inline |
Signs the sha256 hash with the private key managed by the passed instance of SIGN::Signer. Does not write to an internal attribute.
[in] | signer | Reference to a SIGN::Signer object holding the private key to use |
Definition at line 424 of file Variable.h.
|
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.
[in] | message | Incoming HTTP request as preprocessed by cpprestsdk |
[in] | match | Match result of the request path that led to this resource |
Reimplemented from HTTP::Resource.
Definition at line 452 of file Variable.h.
|
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.
[in] | message | Incoming HTTP request as preprocessed by cpprestsdk |
[in] | match | Match result of the request path that led to this resource |
Reimplemented from HTTP::Resource.
Definition at line 464 of file Variable.h.
|
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.
[in] | publisher | Reference to the publisher to use |
[in] | qos | Quality of service to choose for MQTT message |
[in] | retain | Flag whether to retain the message on the server. |
Definition at line 444 of file Variable.h.
|
inline |
Assigns the value provided as container on the right hand side to the variable. Immediately resorts to the implementation in Figure internally.
std::range_error | Throws an exception if the value to assign is outside the allowed range. |
[in] | value | Value to assign |
Definition at line 335 of file Variable.h.
|
inline |
Return a shared pointer casted to the Parameter type to element itself.
Definition at line 277 of file Variable.h.
|
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.
|
inline |
Set the covariance corresponding to the value. This is a separate call as the following three scenarios are foreseen:
update()
.[in] | covariance | Covariance provided as container object |
Definition at line 380 of file Variable.h.
|
inline |
Calculates the sha256 hash of the bytestring representation. Internally calls bytes()
, but does not write to any value.
Definition at line 417 of file Variable.h.
|
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.
hash
attribute is automatically updated by this call.[in] | signer | Reference to a SIGN::Signer object holding the private key to use |
Definition at line 430 of file Variable.h.
|
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.
[in] | value | Value to set |
[in] | time | Timestamp to set as corresponidng to the value |
[in] | nonce | Nonce to set as corresponding to the value |
Definition at line 474 of file Variable.h.
|
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.
Reimplemented from SOIL::Element.
Definition at line 343 of file Variable.h.
|
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.
|
protected |
Covariance of the value expressed as multidimensional normal distribution with coverage factor 1. The dimensionality depends on the dimensionality of the value:
Note that the second template argument of the Container is x
in this case.
Definition at line 74 of file Variable.h.
|
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.
Definition at line 61 of file Variable.h.
|
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.