Request represents a single user request/response over a bus. More...

#include <Request.h>

Inheritance diagram for IO::Request:
Collaboration diagram for IO::Request:

Public Types

using OwnedList = OwnedLinkedObjectListTemplate< Request >
 
using Callback = Delegate< void(const Request &request)>
 Per-request callback A request goes through the following states: More...
 
- Public Types inherited from LinkedObjectTemplate< Request >
using Iterator = IteratorTemplate< Request, Request *, Request & >
 
using ConstIterator = IteratorTemplate< const Request, const Request *, const Request & >
 

Public Member Functions

 Request (Device &device)
 
 Request (const Request &)=delete
 
virtual ~Request ()
 
ErrorCode error () const
 Request error code defaults to 'pending' and is set on completion. More...
 
bool isPending () const
 
String caption () const
 Get a descriptive caption for this request. More...
 
virtual ErrorCode parseJson (JsonObjectConst json)
 Fill this request from a JSON description. More...
 
virtual void submit ()
 Submit a request. More...
 
void complete (ErrorCode err)
 
virtual void getJson (JsonObject json) const
 Get result of a completed request in JSON format. More...
 
void setID (const String &value)
 Request identifiers are optional, useful for tracking remote requests. More...
 
void setCommand (Command cmd)
 Set the command code. More...
 
void onComplete (Callback callback)
 Set the request completion callback. More...
 
bool nodeQuery (DevNode node)
 
bool nodeOff (DevNode node)
 
bool nodeOn (DevNode node)
 
bool nodeToggle (DevNode node)
 
virtual bool setNode (DevNode node)
 If nodes are supported, implement this method. More...
 
virtual bool setValue (int value)
 If nodes support values, implement this method. More...
 
virtual DevNode::States getNodeStates (DevNode node)
 Query node status from response. More...
 
virtual bool setNodeState (DevNode node, DevNode::State state)
 
const CStringid () const
 Get the request ID, if there is one. More...
 
Command getCommand () const
 
virtual void handleEvent (Event event)
 Implementations may override this method as required. More...
 
bool nodeSet (DevNode node, int value)
 For nodes supporting analogue state (e.g. brightness) More...
 
bool nodeAdjust (DevNode node, int value)
 
- Public Member Functions inherited from LinkedObjectTemplate< Request >
Request * getNext () const
 
bool insertAfter (Request *object)
 
Iterator begin () const
 
Iterator end () const
 
Iterator cbegin () const
 
Iterator cend () const
 
- Public Member Functions inherited from LinkedObject
virtual ~LinkedObject ()
 
virtual LinkedObjectnext () const
 
bool insertAfter (LinkedObject *object)
 
bool operator== (const LinkedObject &other) const
 
bool operator!= (const LinkedObject &other) const
 

Public Attributes

Devicedevice
 

Detailed Description

Request represents a single user request/response over a bus.

Inherited classes provide additional methods to encapsulate specific commands or functions. Create the appropriate object using new() or the device manager, then configure the request. Finally, call submit(). If submit() is not called then the request object must be deleted. When the request has completed the callback is invoked, after which the request object is destroyed.

Each call to submit() always has a corresponding call to complete(), even if the request is never attempted. This ensures error is reported to the callback and the object released.

In brief, ownership of a request belongs with the user up until submit() is called, which passes ownership to the IO mechanism.

Member Typedef Documentation

◆ Callback

using IO::Request::Callback = Delegate<void(const Request& request)>

Per-request callback A request goes through the following states:

  • submitted request.submit()
  • queued Controller places request on internal queue
  • executed Controller retrieves request from queue
  • completed Request fully handled, status indicates success/failure

A Controller invokes this callback twice, when a request is about to be executed and again when it has completed. Call request.isPending() to determine which.

◆ OwnedList

Constructor & Destructor Documentation

◆ Request() [1/2]

IO::Request::Request ( Device device)
inline

◆ Request() [2/2]

IO::Request::Request ( const Request )
delete

◆ ~Request()

virtual IO::Request::~Request ( )
inlinevirtual

Member Function Documentation

◆ caption()

String IO::Request::caption ( ) const

Get a descriptive caption for this request.

◆ complete()

void IO::Request::complete ( ErrorCode  err)

◆ error()

ErrorCode IO::Request::error ( ) const
inline

Request error code defaults to 'pending' and is set on completion.

◆ getCommand()

Command IO::Request::getCommand ( ) const
inline

◆ getJson()

virtual void IO::Request::getJson ( JsonObject  json) const
virtual

◆ getNodeStates()

virtual DevNode::States IO::Request::getNodeStates ( DevNode  node)
inlinevirtual

Query node status from response.

Reimplemented in IO::Modbus::STM8Relay::Request, and IO::Modbus::R421A::Request.

◆ handleEvent()

virtual void IO::Request::handleEvent ( Event  event)
virtual

Implementations may override this method as required.

◆ id()

const CString& IO::Request::id ( ) const
inline

Get the request ID, if there is one.

◆ isPending()

bool IO::Request::isPending ( ) const
inline

◆ nodeAdjust()

bool IO::Request::nodeAdjust ( DevNode  node,
int  value 
)
inline

◆ nodeOff()

bool IO::Request::nodeOff ( DevNode  node)
inline

◆ nodeOn()

bool IO::Request::nodeOn ( DevNode  node)
inline

◆ nodeQuery()

bool IO::Request::nodeQuery ( DevNode  node)
inline

◆ nodeSet()

bool IO::Request::nodeSet ( DevNode  node,
int  value 
)
inline

For nodes supporting analogue state (e.g. brightness)

◆ nodeToggle()

bool IO::Request::nodeToggle ( DevNode  node)
inline

◆ onComplete()

void IO::Request::onComplete ( Callback  callback)
inline

Set the request completion callback.

◆ parseJson()

virtual ErrorCode IO::Request::parseJson ( JsonObjectConst  json)
virtual

◆ setCommand()

void IO::Request::setCommand ( Command  cmd)
inline

Set the command code.

◆ setID()

void IO::Request::setID ( const String value)
inline

Request identifiers are optional, useful for tracking remote requests.

◆ setNode()

virtual bool IO::Request::setNode ( DevNode  node)
inlinevirtual

◆ setNodeState()

virtual bool IO::Request::setNodeState ( DevNode  node,
DevNode::State  state 
)
inlinevirtual

◆ setValue()

virtual bool IO::Request::setValue ( int  value)
inlinevirtual

If nodes support values, implement this method.

Reimplemented in IO::Modbus::STS::Fan::Request, IO::DMX512::Request, and IO::Custom::Request.

◆ submit()

virtual void IO::Request::submit ( )
virtual

Submit a request.

The request is added to the controller's queue. If the queue is empty, it starts execution immediately. The result of the request is posted to the callback routine.

Reimplemented in IO::DMX512::Request, and IO::Custom::Request.

Member Data Documentation

◆ device

Device& IO::Request::device

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