m (→Optional fields) |
|||
(28 intermediate revisions by 2 users not shown) | |||
Line 2: | Line 2: | ||
These are sent on the Qpid/AMQP messaging bus. | These are sent on the Qpid/AMQP messaging bus. | ||
− | = | + | = commandHandler response = |
− | The commandHandler response is a map. Depending on success or failure, it has the following structure: | + | The commandHandler response is a map. Depending on success or failure, it either contains a "result" or an "error" map, which has the following structure: |
− | == | + | == Result == |
=== Mandatory fields === | === Mandatory fields === | ||
"identifier" - hold a success identifier string value. Defaults to "success". | "identifier" - hold a success identifier string value. Defaults to "success". | ||
+ | |||
=== 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 | + | "data" - holds a map of arbitrary data provided by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component) |
+ | |||
+ | "event-ref" - optional ID string, if an event will be sent as a result of this command being executed, the event will have a matching "event-ref" | ||
+ | |||
+ | === Example === | ||
+ | <pre> | ||
+ | { | ||
+ | result: { | ||
+ | identifier: "success", | ||
+ | message: "the command did success, happy hippos", | ||
+ | data: { | ||
+ | agorpc: { | ||
+ | ucpu: 0 | ||
+ | scpu: 0 | ||
+ | ... | ||
+ | }, | ||
+ | agolua: { | ||
+ | ucpu: 0 | ||
+ | scpu: 0 | ||
+ | ... | ||
+ | }, | ||
+ | ... | ||
+ | } | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
=== 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. | + | When a success result is being sent over JSON-RPC transport (via agorpc), the result map is passed 1:1 as "result" key in JSON-RPC. |
+ | |||
+ | Example: | ||
<pre> | <pre> | ||
{ | { | ||
Line 37: | Line 65: | ||
} | } | ||
</pre> | </pre> | ||
+ | |||
== Error == | == Error == | ||
=== Mandatory fields === | === Mandatory fields === | ||
− | "identifier" - holds an error identifier string which is used for translation (e.g. "error.subsystem.badthingshappened"). These should be kept generic | + | "identifier" - holds an error identifier string which is used for translation (e.g. "error.subsystem.badthingshappened"). These should be kept generic and reuse is encouraged. These identifiers MAY also be used to alter application logic depending on error, thus be careful if you are changing existing error identifiers. |
− | "message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff") | + | |
+ | "message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff"), mainly to aid in debugging (the main error message shall be translated from the identifier) | ||
+ | |||
=== Optional fields === | === Optional fields === | ||
− | "data" - holds optional map data | + | "data" - holds optional map with arbitrary data |
+ | |||
+ | === Example === | ||
+ | <pre> | ||
+ | { | ||
+ | error: { | ||
+ | identifier: "error.subsystem.badthingshappened", | ||
+ | message: "something really bad happened when trying to do stuff", | ||
+ | data: { | ||
+ | faulty_data: 0, | ||
+ | ... | ||
+ | }, | ||
+ | } | ||
+ | } | ||
+ | </pre> | ||
+ | |||
=== JSON-RPC encapsulation === | === JSON-RPC encapsulation === | ||
− | When an error result is being sent over JSON-RPC transport (via agorpc), the | + | When an error result is being sent over JSON-RPC transport (via agorpc), the error map is passed 1:1 as "data" value of the JSON-RPC error struct. |
+ | "code" is set to our application specific code -31999. Message is set to "Command returned error". | ||
+ | |||
+ | Example: | ||
+ | |||
<pre> | <pre> | ||
{ | { | ||
Line 51: | Line 101: | ||
error: { | error: { | ||
code: -31999, | code: -31999, | ||
− | message: " | + | message: "Command returned error", |
data: { | data: { | ||
identifier: "error.subsystem.badthingshappened", | identifier: "error.subsystem.badthingshappened", | ||
message: "something really bad happened when trying to do stuff", | message: "something really bad happened when trying to do stuff", | ||
data: { | data: { | ||
− | + | faulty_data: 0, | |
− | + | ... | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
}, | }, | ||
} | } | ||
Line 68: | Line 114: | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
= Event = | = 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 | + | 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 “event-ref” field shall always be set. This can also be used to indicate failure to execute the request. |
+ | == Mandatory fields == | ||
* “uuid”, the originating device | * “uuid”, the originating device | ||
* “event”, event string code, OR | * “event”, event string code, OR | ||
* “error”, an error-map in case we failed to execute a command (“ref” required) | * “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 “data”, event-specific parameters, only if “event” is set | ||
− | * optionally | + | * optionally “event-ref”, if set this shall be a previously issued “event-ref” |
− | + | == JSON-RPC Encapsulation == | |
+ | To obtain events through the JSON-RPC interface, the caller must use the subscription mechanism and poll the "getevent" method. For more details, see [[RPC#subscribe]] | ||
− | = | + | = Used identifiers = |
− | == | + | == Successful == |
− | + | * success | |
− | + | ||
− | + | ||
− | * | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | == Failed == | |
+ | * error.failed - Failed to execute the command | ||
+ | * error.unknown.command - The targeted device does not support this command | ||
+ | * error.parameter.missing - Bad call, parameter missing. Message shall indicate which parameter is missing | ||
+ | * error.parameter.invalid - Bad call, unacceptable parameter. Message shall indicate which parameter is invalid, and why | ||
− | * | + | * error.device.invalid - ?? Can this ever be sent? If the device is not known, nothing will handle the command..? |
− | + | ||
− | + | * error.cannot.send.sms | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | * error.cannot.send. | + | |
− | + | ||
− | + | ||
− | + | ||
* error.security.housemodechange | * error.security.housemodechange | ||
* error.security.invalidpin | * error.security.invalidpin | ||
Line 161: | Line 149: | ||
* error.security.invalidmap | * error.security.invalidmap | ||
* error.security.setzones | * error.security.setzones | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
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 either contains a "result" or an "error" map, which 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 provided by the command handler. Examples are different maps returned by components (e.g the scenario map for the getscenario command of the scenario component)
"event-ref" - optional ID string, if an event will be sent as a result of this command being executed, the event will have a matching "event-ref"
{ result: { identifier: "success", message: "the command did success, happy hippos", data: { agorpc: { ucpu: 0 scpu: 0 ... }, agolua: { ucpu: 0 scpu: 0 ... }, ... } } }
When a success result is being sent over JSON-RPC transport (via agorpc), the result map is passed 1:1 as "result" key in JSON-RPC.
Example:
{ 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 and reuse is encouraged. These identifiers MAY also be used to alter application logic depending on error, thus be careful if you are changing existing error identifiers.
"message" - descriptive error message string in english language (e.g. "something really bad happened when trying to do stuff"), mainly to aid in debugging (the main error message shall be translated from the identifier)
"data" - holds optional map with arbitrary data
{ error: { identifier: "error.subsystem.badthingshappened", message: "something really bad happened when trying to do stuff", data: { faulty_data: 0, ... }, } }
When an error result is being sent over JSON-RPC transport (via agorpc), the error map is passed 1:1 as "data" value of the JSON-RPC error struct. "code" is set to our application specific code -31999. Message is set to "Command returned error".
Example:
{ 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: { faulty_data: 0, ... }, } } }
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 “event-ref” field shall always be set. This can also be used to indicate failure to execute the request.
To obtain events through the JSON-RPC interface, the caller must use the subscription mechanism and poll the "getevent" method. For more details, see RPC#subscribe