MessageFormat

From ago control wiki
(Difference between revisions)
Jump to: navigation, search
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.
  
−
= Draft =
+
= 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:
−
== Success ==
+
== 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 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 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. So it looks like the following:
+
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 to facilitate translation and keep effort low.
+
"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 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:
+
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: "command returned error",  
+
         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: {
−
                 agorpc: {
+
                 faulty_data: 0,
−
                    ucpu: 0
+
                ...
−
                    scpu: 0
+
−
                    ...
+
−
                },
+
−
 
+
 
             },
 
             },
 
         }
 
         }
Line 68: Line 114:
 
</pre>
 
</pre>
  
−
= DRAFT END =
 
−
<pre>
 
  
  
−
 
−
 
−
 
−
INTENTIONALLY LEFT BLANK
 
−
 
−
 
−
 
−
 
−
 
−
</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 “ref” field shall always be set. This can also be used to indicate failure to execute the request.
+
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 “ref”, if set this shall be a previously issued “event-ref”
+
* optionally “event-ref”, if set this shall be a previously issued “event-ref”
  
−
TODO: update above
+
== 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]]
  
−
= Request-reply =
+
= Used identifiers =
−
== Request ==
+
== Successful ==
−
 
+
* success
−
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
+
== 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
  
−
* “message”, a standardized code in the format “error.<describing string>”, re-use is encouraged, will be translated and used as error message.  
+
* error.device.invalid - ?? Can this ever be sent? If the device is not known, nothing will handle the command..?
−
* "data", an optional map with more specific error information.
+
  
−
The only reserved key in the "data" map is:
+
* error.cannot.send.sms
−
* “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 ===
+
−
 
+
−
<pre>&gt; {uuid:&quot;1234xxx&quot;, command: &quot;setlevel&quot;, data: {&quot;level&quot;: 50}}
+
−
&lt; {result: {identifier: &quot;success.queued&quot;}, &quot;event-ref&quot;: &quot;99random99&quot;}
+
−
 
+
−
* {uuid: &quot;1234xxx&quot;, event:&quot;event.device.statechanged&quot;, &quot;data&quot;: {&quot;level&quot;: &quot;50&quot;, &quot;unit&quot;: &quot;&quot;},
+
−
&quot;ref&quot;:&quot;99random99&quot;}</pre>
+
−
=== immediately failed: ===
+
−
 
+
−
<pre>&gt; {command: &quot;setlevel&quot;, uuid:&quot;1234xxx&quot;, data: {&quot;level&quot;: 50}}
+
−
&lt; {error: {message: &quot;error.unknown.command&quot;, data: { description: "Command disabled for this device"} } }}</pre>
+
−
 
+
−
=== successful with failed follow-up event: ===
+
−
 
+
−
<pre>&gt; {command: &quot;setlevel&quot;, uuid:&quot;1234xxx&quot;, data: {&quot;level&quot;: 50}}
+
−
&lt; {result: {identifier: &quot;success.queued&quot;}, &quot;event-ref&quot;: &quot;99random99&quot;}
+
−
 
+
−
* {uuid: &quot;1234xxx&quot;, error: {&quot;identifier&quot;: &quot;error.call.failed&quot;}, &quot;ref&quot;:&quot;99random99&quot;}</pre>
+
−
=== externally triggered change: ===
+
−
 
+
−
<pre>* {uuid: &quot;1234xxx&quot;, event:&quot;event.device.statechanged&quot;, &quot;data&quot;: {&quot;level&quot;: &quot;255&quot;, &quot;unit&quot;: &quot;&quot;}}</pre>
+
−
 
+
−
= Used codes =
+
−
* success
+
−
* error.cannot.send.SMS
+
−
* error.parameter.missing
+
−
* error.command.invalid
+
−
* error.command.missing
+
 
* 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
−
* 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
 

Latest revision as of 10:07, 11 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

[edit] commandHandler response

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:

[edit] Result

[edit] Mandatory fields

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

[edit] Optional fields

"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"

[edit] Example 

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

[edit] JSON-RPC encapsulation

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
                ...
            },
            ...
        }
    }
}

[edit] Error

[edit] Mandatory fields

"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)

[edit] Optional fields

"data" - holds optional map with arbitrary data

[edit] Example 

{
    error: {
        identifier: "error.subsystem.badthingshappened",
        message: "something really bad happened when trying to do stuff",
        data: {
            faulty_data: 0,
            ...
        },
    }
}

[edit] JSON-RPC encapsulation

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,
                ...
            },
        }
    }
}


[edit] 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 “event-ref” field shall always be set. This can also be used to indicate failure to execute the request.

[edit] Mandatory fields

  • “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 “event-ref”, if set this shall be a previously issued “event-ref”

[edit] 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

[edit] Used identifiers

[edit] Successful

  • success

[edit] 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.security.housemodechange
  • error.security.invalidpin
  • error.security.housemodenotset
  • error.security.alarmthreadfailed
  • error.security.alarmthreadcancelfailed
  • error.security.invalidmap
  • error.security.setzones
Retrieved from "http://wiki.agocontrol.com/index.php?title=MessageFormat&oldid=862"
Personal tools