MessageFormat

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
Line 1: Line 1:
 
Agocontrol applications communicate using broadcasted requests, which shall produce a single reply (Request-reply pattern), and broadcasted events.
 
Agocontrol applications communicate using broadcasted requests, which shall produce a single reply (Request-reply pattern), and broadcasted events.
 
These are sent on the Qpid/AMQP messaging bus.
 
These are sent on the Qpid/AMQP messaging bus.
 +
 +
= Draft =
 +
The commandHandler response is a map. Depending on success or failure, it has the following structure
 +
== Success ===
 +
=== Mandatory fields ===
 +
"identifier" - hold a success identifier string value. Defaults to "success".
 +
=== Optional fields ===
 +
"message" - holds an optional verbose success message.
 +
"data" - holds a map of arbitrary data which will be returned by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component)
 +
=== JSON-RPC encapsulation ===
 +
When a success result is being sent over JSON-RPC transport (via agorpc), the map is passed 1:1 as "result" key in JSON-RPC. So it looks like the following:
 +
<pre>
 +
{
 +
    jsonrpc: 2.0,
 +
    id: null,
 +
    result: {
 +
        identifier: "success",
 +
        message: "the command did success, happy hippos",
 +
        data: {
 +
            agorpc: {
 +
                ucpu: 0
 +
                scpu: 0
 +
                ...
 +
            },
 +
            agolua: {
 +
                ucpu: 0
 +
                scpu: 0
 +
                ...
 +
            },
 +
            ...
 +
        }
 +
    }
 +
}
 +
</pre>
 +
 +
 +
 +
 +
 +
  
 
= Event =
 
= Event =

Revision as of 15:32, 9 April 2015

Agocontrol applications communicate using broadcasted requests, which shall produce a single reply (Request-reply pattern), and broadcasted events. These are sent on the Qpid/AMQP messaging bus.

Contents

Draft

The commandHandler response is a map. Depending on success or failure, it has the following structure

Success =

Mandatory fields

"identifier" - hold a success identifier string value. Defaults to "success".

Optional fields

"message" - holds an optional verbose success message. "data" - holds a map of arbitrary data which will be returned by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component)

JSON-RPC encapsulation

When a success result is being sent over JSON-RPC transport (via agorpc), the map is passed 1:1 as "result" key in JSON-RPC. So it looks like the following:

{
    jsonrpc: 2.0,
    id: null,
    result: {
        identifier: "success",
        message: "the command did success, happy hippos",
        data: {
            agorpc: {
                ucpu: 0
                scpu: 0
                ...
            },
            agolua: {
                ucpu: 0
                scpu: 0
                ...
            },
            ...
        }
    }
}




Event

An event can be sent at any time from a device, either externally triggered or triggered by a Agocontrol request. If triggered by previous request, a “ref” field shall always be set. This can also be used to indicate failure to execute the request.

  • “uuid”, the originating device
  • “event”, event string code, OR
  • “error”, an error-map in case we failed to execute a command (“ref” required)
  • optionally “data”, event-specific parameters, only if “event” is set
  • optionally “ref”, if set this shall be a previously issued “event-ref”

TODO: update above

Request-reply

Request

One request gives one reply, which is sent to a temporary reply-queue. The message content is a Variant map with the following fields:

  • “uuid” - String which contains targets device uuid
  • “command” which tells the command (string)
  • optional “data” map with parameters to the command [new]

Reply

  • “result”, containing a result-map
  • “error”, containing an error-map

Error map

Sent as part of a Reply or an Event. The format

  • “message”, a standardized code in the format “error.<describing string>”, re-use is encouraged, will be translated and used as error message.
  • "data", an optional map with more specific error information.

The only reserved key in the "data" map is:

  • “description”, an optional human readable debug message in english.

Result map

Sent as part of a Reply

  • “identifier”, a standardized code in the format “success.<describing string>”, re-use is encouraged, will be translated and used as informative notice, if appropriate
  • “description”, an optional human readable debug message in english.

Examples

successful with follow-up event

> {uuid:"1234xxx", command: "setlevel", data: {"level": 50}}
< {result: {identifier: "success.queued"}, "event-ref": "99random99"}

* {uuid: "1234xxx", event:"event.device.statechanged", "data": {"level": "50", "unit": ""}, 
"ref":"99random99"}

immediately failed:

> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}}
< {error: {message: "error.unknown.command", data: { description: "Command disabled for this device"} } }}

successful with failed follow-up event:

> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}}
< {result: {identifier: "success.queued"}, "event-ref": "99random99"}

* {uuid: "1234xxx", error: {"identifier": "error.call.failed"}, "ref":"99random99"}

externally triggered change:

* {uuid: "1234xxx", event:"event.device.statechanged", "data": {"level": "255", "unit": ""}}

Used codes

  • success
  • error.cannot.send.SMS
  • error.parameter.missing
  • error.command.invalid
  • error.command.missing
  • error.security.housemodechange
  • error.security.invalidpin
  • error.security.housemodenotset
  • error.security.alarmthreadfailed
  • error.security.alarmthreadcancelfailed
  • error.security.invalidmap
  • error.security.setzones
  • error.device.invalid


Redacted

This was moved from Reply... to be decided if we want and how:


TODO

  • optionally “data” with extra reply data (only allowed together with “result”)
  • optionally “event-ref” with a random string, used for any subsequent events triggered by this request
Personal tools