diff options
Diffstat (limited to 'docs/2.2-config.xml.md')
| -rw-r--r-- | docs/2.2-config.xml.md | 106 |
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. |