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

Parameter Class. More...

#include <Parameter.h>

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

Public Member Functions

 Parameter (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string unit, bool constant=false, std::string ontology="", Range< T > range=Range< T >(), TIME time=TIME())
 Constructor. More...
 
 ~Parameter ()
 Destructor. More...
 
Parameter< 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_patch (HTTP::Request message, std::smatch match=std::smatch()) override
 HTTP PATCH Handler. More...
 
std::shared_ptr< Parameterptr (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< Parametercreate (std::shared_ptr< Element > parent, std::string uuid, std::string name, std::string description, std::string unit, bool constant=false, std::string ontology="", Range< T > range=Range< T >(), TIME time=TIME())
 Create new Parameter. 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

bool constant
 Constant flag. 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::Parameter< T, x, y >

This class represents a SOIL Parameter. Parameter and Variable share many common properties and therefore both inherit from Figure, such that methods there should be considered in any case. Parameters are primarily intended for values that do not represent any measurement or physical phenomenon outside the immediate control of device. In contrast to variables, they can be set externally to control the device and do not posses a measurement uncertainty. Parametery may be constant. In lightweight scenarios, this class may be instantiated directly, for more specific scenarios, it shouls be subclassed and override the implementations of read() and write().

A parameter supports HTTP GET (read) and HTTP PATCH (set) 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 34 of file Parameter.h.

Constructor & Destructor Documentation

◆ Parameter()

template<typename T , int x = -1, int y = -1>
SOIL::Parameter< T, x, y >::Parameter ( std::shared_ptr< Element parent,
std::string  uuid,
std::string  name,
std::string  description,
std::string  unit,
bool  constant = false,
std::string  ontology = "",
Range< T >  range = Range<T>(),
TIME  time = TIME() 
)

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]constantBoolean flag whether this value is cosnstant
[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

Definition at line 202 of file Parameter.h.

◆ ~Parameter()

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

Default destructor, without custom effort.

Definition at line 213 of file Parameter.h.

Member Function Documentation

◆ create()

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

Create a new Parameter 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]constantBoolean flag whether this value is cosnstant
[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

Definition at line 218 of file Parameter.h.

◆ handle_get()

template<typename T , int x, int y>
HTTP::Response SOIL::Parameter< 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 Parameter and its current value to the requesting party. It should not be overridden directly in subclasses, instead the read() function should be overriden.

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 254 of file Parameter.h.

◆ handle_patch()

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

Handler that is called by the server on HTTP requests on a PATCH method. This function updates the value of a parameter. The request must at least contain a It should not be overridden directly in subclasses, instead the write() function should be overriden.

If an update is not not foreseen, you may consider overriding allowed_methods without PATCH. This is not enforced by default through the constant flag. The minimum requirement to the body is that it contains a value to assign. If a timestamp is provided, it will be set, otherwise the current server time is taken.

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 268 of file Parameter.h.

◆ mqtt()

template<typename T , int x, int y>
bool SOIL::Parameter< 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 300 of file Parameter.h.

◆ operator=()

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

Assigns the value provided as container on the right hand side to the parameter. 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 Parameter

Definition at line 225 of file Parameter.h.

◆ ptr()

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

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

Returns
Casted pointer

Definition at line 166 of file Parameter.h.

◆ read()

template<typename T , int x, int y>
void SOIL::Parameter< 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. Declared virtual to make sure the derived method is called first. Does nothing be default.

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

Definition at line 243 of file Parameter.h.

◆ wjson()

template<typename T , int x, int y>
HTTP::Json SOIL::Parameter< 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 233 of file Parameter.h.

◆ write()

template<typename T , int x, int y>
void SOIL::Parameter< T, x, y >::write ( void  )
inlineprotectedvirtual

Write callback that can be implemented by deriving classes to perform custom build logic on write actions, e.g.set a value to an external system. Declared virtual to make sure the derived method is called first. Does nothing be default.

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

Definition at line 248 of file Parameter.h.

Member Data Documentation

◆ constant

template<typename T , int x = -1, int y = -1>
bool SOIL::Parameter< T, x, y >::constant
protected

Boolean flag whether this parameter should be considered as constant.

Definition at line 46 of file Parameter.h.


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