X-Git-Url: https://gerrit.automotivelinux.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2F2.2-config.xml.md;h=de0b8d7abaa1a09f857d7e4c7ac8449a6a90c4ff;hb=7553044c59814c33763bb4b1c34664dceed68735;hp=f6c88abdd9f9ae8a51898d6a369701dc351637b2;hpb=8c08f5f678660d27420d548cf8b3100bb24aebd9;p=src%2Fapp-framework-main.git
diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md
index f6c88ab..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,31 +101,31 @@ 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"
List of the api required by the widget.
-Each required api must be explicited using a `` entry.
+Each required api must be explicit using a `` entry.
Example:
```xml
- >
+
@@ -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,37 +153,117 @@ 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:
+- 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
-- link:
- The framework connect in memory by dynamically linking
+- 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.
+- cloud: [PROPOSAL - NOT IMPLEMENTED]
+ The framework connect externally using websock.
+ In that case, the name includes data to access the service.
Example: ``
+### 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 `` entry.
+
+Example:
+
+```xml
+
+
+
+
+```
+
+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.
+
+The value describes how to connect to the required binding.
+It is either:
+
+- local:
+ The binding is a local shared object.
+ In that case, the name is the relative path of the
+ shared object to be loaded.
+
+- extern:
+ 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 `` entry.
+
+Example:
+
+```xml
+
+
+
+```
+
+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.
+
+The value must contain the path to the exported binding.
+
### required-permission: feature name="urn:AGL:widget:required-permission"
List of the permissions required by the unit.
-Each required permission must be explicited using a `` entry.
+Each required permission must be explicit using a `` entry.
Example:
@@ -214,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.
@@ -230,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.
@@ -264,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"
@@ -328,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.
@@ -339,15 +419,43 @@ 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.
+At this time, this feature only allows to set executable flag
+for making companion program executable explicitly.
+
+Example:
+
+```xml
+
+
+
+
+```
+
+#### file-properties: param name="path"
+
+The name is the relative path of the file whose property
+must be set.
+
+The value must be "executable" to make the file executable.
+
## Known content types
The configuration file ***/etc/afm/afm-unit.conf*** defines
@@ -355,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
@@ -377,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***
@@ -397,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
@@ -410,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.
@@ -423,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
@@ -438,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
@@ -448,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.