aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorJosé Bollo <jose.bollo@iot.bzh>2018-08-03 15:10:53 +0200
committerJose Bollo <jose.bollo@iot.bzh>2018-10-19 14:13:02 +0200
commit24f0c203cc62f478b2759b184f1b4ed7a1c093ca (patch)
treeccf80589aea5d29ac6e0e810ba1a62737f949324 /docs
parent9e1d25b1ca04cf381a3a4fc96197c5545e55fc27 (diff)
Add the ability to access binding through tcp
This commit introduce "tcp", a new type of provided/required api. It appears in the config.xml as below: <urn:AGL:widget:provided-api> <param "name"="HOST:PORT/API" "value"="tcp"> <urn:AGL:widget:required-api> <param "name"="HOST:PORT/API" "value"="tcp"> This implementation is a draft. The service exposed can not start automatically. Use it with the permission urn:AGL:permission::system:run-by-default. Change-Id: Ic593f0d891692ca0c777c49057ec54c37fc55cc0 Signed-off-by: José Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'docs')
-rw-r--r--docs/2.2-config.xml.md106
1 files changed, 59 insertions, 47 deletions
diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md
index 2be9371..de0b8d7 100644
--- a/docs/2.2-config.xml.md
+++ b/docs/2.2-config.xml.md
@@ -71,7 +71,7 @@ Values for *version* are any non empty string containing only latin letters,
arabic digits, and the three characters '.' (dot), '-' (dash) and
'\_' (underscore).
-Version values are dot separated fields MAJOR.MINOR.REVISION.
+Version values are dot separated fields MAJOR.MINOR.REVISION.
Such version would preferably follow guidelines of
[semantic versioning][semantic-version].
@@ -101,18 +101,18 @@ the features are of important use to:
- declare the exported apis
The specification of [widgets][widgets] is intended to describe
-only one application.
-In the present case, we expect to describe more than just an application.
+only one application.
+In the present case, we expect to describe more than just an application.
For example, a publisher could provide a widget containing a service,
-an application for tuning that service, an application that
-leverage the service.
+an application for tuning that service, an application that
+leverage the service.
Here, the term of service means a background application that
runs without IHM and whose public api can be accessed by other
applications.
So the features are used to describe each of the possible
-units of widgets.
-The "standard" unit in the meaning of [widgets][widgets]
+units of widgets.
+The "standard" unit in the meaning of [widgets][widgets]
is called the "main" unit.
### required-api: feature name="urn:AGL:widget:required-api"
@@ -145,7 +145,7 @@ This will be *virtually* translated for mustaches to the JSON
OPTIONAL
Declares the name of the unit requiring the listed apis.
-Only one instance of the param "#target" is allowed.
+Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.
@@ -153,7 +153,7 @@ the target main was specified.
The name is the name of the required API.
-The value describes how to connect to the required api.
+The value describes how to connect to the required api.
It is either:
- local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
@@ -162,19 +162,25 @@ It is either:
In that case, the name is the relative path of the
shared object to be loaded.
-- auto:
+- auto:
The framework set automatically the kind of
the connection to the API
-- ws:
+- ws:
The framework connect using internal websockets
-- dbus:
+- dbus: [OBSOLETE, shouldn't be used currently]
The framework connect using internal dbus
-- cloud: [PROPOSAL - NOT IMPLEMENTED]
- The framework connect externally using websock.
- In that case, the name includes data to access the service.
+- tcp:
+ In that case, the name is the URI to access the service.
+ The framework connect using a URI of type
+ HOST:PORT/API
+ API gives the name of the imported api.
+
+- cloud: [PROPOSAL - NOT IMPLEMENTED]
+ The framework connect externally using websock.
+ In that case, the name includes data to access the service.
Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
### required-binding: feature name="urn:AGL:widget:required-binding"
@@ -215,7 +221,7 @@ The value describes how to connect to the required binding.
It is either:
- local:
- The binding is a local shared object.
+ The binding is a local shared object.
In that case, the name is the relative path of the
shared object to be loaded.
@@ -288,8 +294,8 @@ This will be *virtually* translated for mustaches to the JSON
OPTIONAL
-Declares the name of the unit requiring the listed permissions.
-Only one instance of the param "#target" is allowed.
+Declares the name of the unit requiring the listed permissions.
+Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.
@@ -304,7 +310,7 @@ The value is either:
### provided-unit: feature name="urn:AGL:widget:provided-unit"
This feature is made for declaring new units
-for the widget.
+for the widget.
Using this feature, a software publisher
can provide more than one application in the same widget.
@@ -338,12 +344,12 @@ This will be *virtually* translated for mustaches to the JSON
REQUIRED
Declares the name of the unit. The default unit, the unit
-of the main of the widget, has the name "main".
-The value given here must be unique within the widget file.
+of the main of the widget, has the name "main".
+The value given here must be unique within the widget file.
It will be used in other places of the widget config.xml file to
designate the unit.
-Only one instance of the param "#target" is allowed.
+Only one instance of the param "#target" is allowed.
The value can't be "main".
#### provided-unit: param name="content.type"
@@ -402,8 +408,8 @@ This will be *virtually* translated for mustaches to the JSON
OPTIONAL
-Declares the name of the unit exporting the listed apis.
-Only one instance of the param "#target" is allowed.
+Declares the name of the unit exporting the listed apis.
+Only one instance of the param "#target" is allowed.
When there is not instance of this param, it behave as if
the target main was specified.
@@ -413,15 +419,21 @@ The name give the name of the api that is exported.
The value is one of the following values:
-- ws:
+- ws:
export the api using UNIX websocket
-- dbus:
+- dbus: [OBSOLETE, shouldn't be used currently]
export the API using dbus
-- auto:
+- auto:
export the api using the default method(s).
+- tcp:
+ In that case, the name is the URI used for exposing the service.
+ The URI is of type
+ HOST:PORT/API
+ API gives the name of the exported api.
+
### file-properties: feature name="urn:AGL:widget:file-properties"
Use this feature for setting properties to files of the widget.
@@ -451,20 +463,20 @@ how to create systemd units for widgets.
Known types for the type of content are:
-- ***text/html***:
- HTML application,
+- ***text/html***:
+ HTML application,
content.src designates the home page of the application
-- ***application/vnd.agl.native***
- AGL compatible native,
+- ***application/vnd.agl.native***
+ AGL compatible native,
content.src designates the relative path of the binary.
-- ***application/vnd.agl.service***:
+- ***application/vnd.agl.service***:
AGL service, content.src is not used.
-- ***application/x-executable***:
- Native application,
- content.src designates the relative path of the binary.
+- ***application/x-executable***:
+ Native application,
+ content.src designates the relative path of the binary.
For such application, only security setup is made.
Adding more types is easy, it just need to edit the configuration
@@ -473,7 +485,7 @@ file ***afm-unit.conf***.
### Older content type currently not supported at the moment
This types were defined previously when the framework was not
-leveraging systemd.
+leveraging systemd.
The transition to systemd let these types out at the moment.
- ***application/vnd.agl.url***
@@ -493,8 +505,8 @@ of the installed widgets.
This configuration file named `afm-unit.conf` installed
on the system with the path `/etc/afm/afm-unit.conf`
describes how to generate all units from the *config.xml*
-configuration files of widgets.
-The description uses an extended version of the templating
+configuration files of widgets.
+The description uses an extended version of the templating
formalism of [mustache][] to describes all the units.
Let present how it works using the following diagram that
@@ -506,7 +518,7 @@ file of the widget `config.xml`:
In a first step, and because [mustache][] is intended
to work on JSON representations, the configuration file is
-translated to an internal JSON representation.
+translated to an internal JSON representation.
This representation is shown along the examples of the documentation
of the config files of widgets.
@@ -519,9 +531,9 @@ extensions:
- test of values with = or =!
In a third step, the result of instantiating `afm-unit.conf`
-for the widget is split in units.
-To achieve that goal, the lines containing specific directives are searched.
-Any directive occupy one full line.
+for the widget is split in units.
+To achieve that goal, the lines containing specific directives are searched.
+Any directive occupy one full line.
The directives are:
- %nl
@@ -534,7 +546,7 @@ The directives are:
Tells the kind of unit (user/system)
- %systemd-unit service NAME
- %systemd-unit socket NAME
- Gives the name and type (service or socket) of the unit.
+ Gives the name and type (service or socket) of the unit.
The extension is automatically computed from the type
and must not be set in the name.
- %systemd-unit wanted-by NAME
@@ -544,14 +556,14 @@ Then the computed units are then written to the filesystem
and inserted in systemd.
The generated unit files will contain variables for internal
-use of the framework.
-These variables are starting with `X-AFM-`.
+use of the framework.
+These variables are starting with `X-AFM-`.
The variables starting with `X-AFM-` but not with `X-AFM--` are
-the public variables.
+the public variables.
These variables will be returned by the
framework as the details of an application (see **afm-util detail ...**).
-Variables starting with `X-AFM--` are private to the framework.
+Variables starting with `X-AFM--` are private to the framework.
By example, the variable `X-AFM--http-port` is used to
record the allocated port for applications.