Commit 6fd63eba authored by Peter Waher's avatar Peter Waher

Editing nodes

parent 576b27ca
......@@ -135,6 +135,24 @@ The following table lists defined operations. It also suggests what types of con
operations might be unnecessary to implement for smaller concentrators. Clients supporting both large and small concentratorsr can iterate the singular
operation over the set of nodes, for concentrators not supporting the plural versions.
Errors
----------------
Error management in all IoT Harmonization requests, are handled by the XMPP layer. If an operation fails, a corresponding XMPP error is returned in an
`iq error` stanza, using the error elements defined in [RFC 6120](https://tools.ietf.org/html/rfc6120). Common errors:
* An item (node, source, etc.) was not found. This results in an `item-not-found` error.
* Access rights are lacking, results in a `forbidden` error.
* Badly formed requests result in `bad-requesst` errors.
* Trying to create something that already exists, results in a `conflict` error.
* Unsupported actions result in `feature-not-implemented` errors.
Localization
------------------
It's optional to support localization. Concentratosr supporting localization return localized content based on the value of the `xml:lang` attribute available
in the stanza element, as defined in [RFC 6121](https://tools.ietf.org/html/rfc6121).
Sources
----------------
......@@ -502,28 +520,205 @@ Managing Nodes
### getNodeParametersForEdit
Gets the parameters for a node, for editing. The `getNodeParametersForEdit` element is sent in an `iq get` to the concentrator, which returns a data form
containing the editable node parameters.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `getNodeParametersForEdit` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `xs:x` | | | | | Contains a data form with editable node parameters. |
Some useful extensions related to data forms in XMPP:
* [XEP-0004: Data Forms](https://xmpp.org/extensions/xep-0004.html)
* [XEP-0122: Data Forms Validation](https://xmpp.org/extensions/xep-0122.html)
* [XEP-0141: Data Forms Layout](https://xmpp.org/extensions/xep-0141.html)
* [XEP-0221: Data Forms Media Element](https://xmpp.org/extensions/xep-0221.html)
* [XEP-0331: Data Forms - Color Field Types](https://xmpp.org/extensions/xep-0331.html)
* [XEP-0336: Data Forms - Dynamic Forms](https://xmpp.org/extensions/xep-0336.html)
### setNodeParametersAfterEdit
Sets the parameters for a node, after editing. The `setNodeParametersForEdit` element is sent in an `iq set` to the concentrator, which returns a `nodeinfo`
element (in an `iq result`) if the parameters could be set, or a data form (in an `iq error`) containing the editable node parameters and any error messages,
if the operation could not be completed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `setNodeParametersForEdit` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `xs:x` | | | | | Contains a data form with edited node parameters. |
**Note**: The form might be partial, i.e. only contain a subset of the parameters available on the node. Paramters not referenced, should keep their
values unchanged.
### getCommonNodeParametersForEdit
To get a set of parameters that are common to a set of nodes, the `getCommonNodeParametersForEdit` element is sent in an `iq get` to the concentrator. Each
node is referenced by a separate `nd` child element. The response is a data form, in which all parameters that do not exist in at least one of the referenced
nodes have been removed. Parameters that have different values in the different referenced nodes should report the value of the first node, and then mark
the field with the `xdd:notSame` element, as defined in [XEP-0336](https://xmpp.org/extensions/xep-0336.html#sect-idm45589980289936).
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `getCommonNodeParametersForEdit` | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `nd` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| `xs:x` | | | | | Contains a data form with edited node parameters. |
### setCommonNodeParametersAfterEdit
Sets the parameters for a set of nodes, after editing. The `setCommonNodeParametersAfterEdit` element is sent in an `iq set` to the concentrator, which
returns with an empty response (in an `iq result`) if the parameters could be set, or a data form (in an `iq error`) containing the editable node parameters
and any error messages, if the operation could not be completed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `setNodeParametersForEdit` | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `nd` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| `xs:x` | | | | | Contains a data form with edited node parameters. |
**Note**: The form might be partial, i.e. only contain a subset of the parameters available on the node. Paramters not referenced, should keep their
values unchanged.
### getAddableNodeTypes
Gets the types of nodes that can be added to a given node in a concentrator. It is sent in a `iq get` to the concentrator, who responds with a `nodeTypes`
element. This element contains a sequence of `nodeType` elements, each one describing a node type.
| Element | Attribute | Type | Use | Default | Description |
|:----------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `getAddableNodeTypes` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `nodeTypes` | | | | | Array of node type. |
| `nodeType` | `type` | `xs:string` | required | | Machine-readable, and concentrator specific, node type. |
| | `name` | `xs:string` | required | | Human-readable, localized, name of node type. |
### getParametersForNewNode
Gets editable parameters for the creation of a new node. The `getParametersForNewNode` element is sent in an `iq get` to the concentrator, which returns a
data form containing the editable node parameters. The node referenced in the request, is the node that will receive the new created node as a child.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `getParametersForNewNode` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| | `type` | `xs:string` | optional | | Machine-readable, and concentrator specific, node type. |
| `xs:x` | | | | | Contains a data form with editable node parameters. |
### createNewNode
Creates a new node. The `createNewNode` element is sent in an `iq set` to the concentrator, which returns a `nodeinfo` element (in an `iq result`) if the
node could be created, or a data form (in an `iq error`) containing the editable node parameters and any error messages, if the operation could not be
completed. The node referenced in the request, is the node that will receive the new created node as a child.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `createNewNode` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| | `type` | `xs:string` | optional | | Machine-readable, and concentrator specific, node type. |
| `xs:x` | | | | | Contains a data form with edited node parameters. |
### destroyNode
Destroys a new node. The `destroyNode` element is sent in an `iq set` to the concentrator, which returns an empty response (in an `iq result`) if the
node was destroyed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `destroyNode` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
### moveNodeUp
Moves a node up one step among its siblings. The `moveNodeUp` element is sent in an `iq set` to the concentrator, which returns an empty response
(in an `iq result`) if the operation was performed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `moveNodeUp` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
### moveNodeDown
Moves a node down one step among its siblings. The `moveNodeDown` element is sent in an `iq set` to the concentrator, which returns an empty response
(in an `iq result`) if the operation was performed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `moveNodeDown` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
| | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
### moveNodesUp
Moves a set of nodes up one step among its siblings. The `moveNodesUp` element references the nodes to move in separate `nd` child elements, and is sent
in an `iq set` to the concentrator, which returns an empty response (in an `iq result`) if the operation was performed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `moveNodesUp` | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `nd` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
### moveNodesDown
Moves a set of nodes down one step among its siblings. The `moveNodesDown` element references the nodes to move in separate `nd` child elements, and is sent
in an `iq set` to the concentrator, which returns an empty response (in an `iq result`) if the operation was performed.
| Element | Attribute | Type | Use | Default | Description |
|:---------------------------|:------------------|:--------------|:---------|:---------|:--------------------------------------------------------------------------------------------------------------------|
| `moveNodesDown` | `dt` | `xs:string` | optional | | Device token(s). |
| | `st` | `xs:string` | optional | | Service token(s). |
| | `ut` | `xs:string` | optional | | User token(s). |
| `nd` | `id` | `xs:string` | required | | Node identity. |
| | `src` | `xs:string` | optional | | Source identity. |
| | `pt` | `xs:string` | optional | | Partition. |
Commands
--------------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment