m |
m (→Optional fields) |
||
Line 9: | Line 9: | ||
=== Optional fields === | === Optional fields === | ||
"message" - holds an optional verbose success message. | "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) | "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 === | === 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: | 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: |
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 |
The commandHandler response is a map. Depending on success or failure, it has the following structure:
"identifier" - hold a success identifier string value. Defaults to "success".
"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)
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 ... }, ... } } }
"identifier" - holds an error identifier string which is used for translation (e.g. "error.subsystem.badthingshappened"). These should be kept generic to facilitate translation and keep effort low. "message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff").
"data" - holds optional map data
When an error result is being sent over JSON-RPC transport (via agorpc), the result map is passed 1:1 as "data" key of the error struct in JSON-RPC. "code" is set to our application specific code -31999. Message is set to "command returned error". So it looks like the following:
{ jsonrpc: 2.0, id: null, error: { code: -31999, message: "command returned error", data: { identifier: "error.subsystem.badthingshappened", message: "something really bad happened when trying to do stuff", data: { agorpc: { ucpu: 0 scpu: 0 ... }, }, } } }
INTENTIONALLY LEFT BLANK
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.
TODO: update above
One request gives one reply, which is sent to a temporary reply-queue. The message content is a Variant map with the following fields:
Sent as part of a Reply or an Event. The format
The only reserved key in the "data" map is:
Sent as part of a Reply
> {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"}
> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}} < {error: {message: "error.unknown.command", data: { description: "Command disabled for this device"} } }}
> {command: "setlevel", uuid:"1234xxx", data: {"level": 50}} < {result: {identifier: "success.queued"}, "event-ref": "99random99"} * {uuid: "1234xxx", error: {"identifier": "error.call.failed"}, "ref":"99random99"}
* {uuid: "1234xxx", event:"event.device.statechanged", "data": {"level": "255", "unit": ""}}
This was moved from Reply... to be decided if we want and how:
TODO