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].
- 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"
List of the api required by the widget.
-Each required api must be explicited using a `<param>` entry.
+Each required api must be explicit using a `<param>` entry.
Example:
```xml
<feature name="urn:AGL:widget:required-api">
- <param name="#target" value="main" />>
+ <param name="#target" value="main" />
<param name="gps" value="auto" />
<param name="afm-main" value="link" />
</feature>
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.
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, PROVIDED FOR COMPATIBILITY
+- local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY
+ Use the feature **urn:AGL:widget:required-binding** instead.
The binding is a local shared object.
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"
+
+List of the bindings required by the widget.
+
+Note: Since AGL 6 (FF - Funky Flounder),
+the binder implements bindings version 3 that allow the declaration
+of 0, 1 or more APIs by one binding. In other words, the equivalency
+one binding = one API is lost. At the same time the framework added
+the ability to use bindings exported by other widgets.
+
+Each required binding must be explicit using a `<param>` entry.
+
+Example:
+
+```xml
+<feature name="urn:AGL:widget:required-binding">
+ <param name="libexec/binding-gps.so" value="local" />
+ <param name="extra" value="extern" />
+</feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+"required-binding": [
+ { "name": "libexec/binding-gps.so", "value": "local" },
+ { "name": "extra", "value": "extern" }
+ ]
+```
+
#### required-binding: param name=[name or path]
The name or the path of 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.
The binding is external. The name is the exported binding name.
See provided-binding.
+### provided-binding: feature name="urn:AGL:widget:provided-binding"
+
+This feature allows to export a binding to other binders.
+The bindings whose relative name is given as value is exported to
+other binders under the given name.
+
+Each provided binding must be explicit using a `<param>` entry.
+
+Example:
+
+```xml
+<feature name="urn:AGL:widget:provided-binding">
+ <param name="extra" value="export/binding-gps.so" />
+</feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+"provided-binding": [
+ { "name": "extra", "value": "export/binding-gps.so" }
+ ]
+```
+
#### provided-binding: param name=[exported name]
Exports a local binding to other applications.
List of the permissions required by the unit.
-Each required permission must be explicited using a `<param>` entry.
+Each required permission must be explicit using a `<param>` entry.
Example:
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.
### 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.
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"
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.
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.
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
### 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***
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
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.
- 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
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
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.