MessageFormat

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
m
m (Used codes)
Line 64: Line 64:
  
 
= Used codes =
 
= Used codes =
 +
* success
 +
* error.cannot.send.SMS
 +
* error.parameter.missing
 +
* error.command.invalid
 +
* error.command.missing
 +
* error.security.housemodechange
 +
* error.security.invalidpin

Revision as of 15:50, 1 February 2015

Contents

Specification

Request

One request gives one reply on a specific reply-queue.

  • “uuid” which targets device
  • “command” which tells the command
  • optional “data” map with parameters to the command [new]

Reply

  • “error”, containing an error-map, OR
  • “result”, containing a result-map
  • 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

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”

Error map

Sent as part of a Reply or an Event

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

Result map

Sent as part of a Reply

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

Examples

successful with follow-up event

> {uuid:"1234xxx", command: "setlevel", data: {"level": 50}}
< {result: {code: "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}}
< {result: {code: "error.unknown.command"}}

successful with failed follow-up event:

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

* {uuid: "1234xxx", error: {"code": "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
Personal tools