diff options
Diffstat (limited to 'docs/3_Developer_Guides/1_Application_Framework/4_Widget_configuration_file.md')
| -rw-r--r-- | docs/3_Developer_Guides/1_Application_Framework/4_Widget_configuration_file.md | 589 |
1 files changed, 0 insertions, 589 deletions
diff --git a/docs/3_Developer_Guides/1_Application_Framework/4_Widget_configuration_file.md b/docs/3_Developer_Guides/1_Application_Framework/4_Widget_configuration_file.md deleted file mode 100644 index f7acb23..0000000 --- a/docs/3_Developer_Guides/1_Application_Framework/4_Widget_configuration_file.md +++ /dev/null @@ -1,589 +0,0 @@ ---- -title: Widget configuration file ---- - -# Configuration file - config.xml - -The widgets are described by the W3C's technical recommendations -[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for -Widgets][widgets-digsig] -that specifies the configuration file **config.xml**. - -## Overview - -The file **config.xml** describes important data of the application -to the framework: - -- the unique identifier of the application -- the name of the application -- the type of the application -- the icon of the application -- the permissions linked to the application -- the services and dependencies of the application - -The file MUST be at the root of the widget and MUST be case sensitively name -***config.xml***. - -The file **config.xml** is a XML file described by the document -[widgets]. - -Here is the example of the config file for the QML application SmartHome. - -```xml -<?xml version="1.0" encoding="UTF-8"?> -<widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1"> - <name>SmartHome</name> - <icon src="smarthome.png"/> - <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/> - <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an -automated house. The user interface is completely done with QML.</description> - <author>Qt team</author> - <license>GPL</license> -</widget> -``` - -The most important items are: - -- **<widget id="......"\>**: gives the id of the widget. It must be unique. - -- **<widget version="......"\>**: gives the version of the widget - -- **<icon src="..."\>**: gives a path to the icon of the application - (can be repeated with different sizes) - -- **<content src="..." type="..."\>**: this indicates the entry point and its type. - -## Standard elements of "config.xml" - -### The element widget - -#### the attribute id of widget - -The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'\_' (underscore). - -Authors can use a mnemonic id or can pick a unique id using -command **uuid** or **uuidgen**. - -### the attribute version of widget - -The attribute *version* is mandatory (for version 2.x, blowfish). - -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. -Such version would preferably follow guidelines of -[semantic versioning][semantic-version]. - -### The element content - -The element *content* is mandatory (for version 2.x, blowfish) and must designate a file -(subject to localization) with its attribute *src*. - -The content designed depends on its type. See below for the known types. - -### The element icon - -The element *icon* is mandatory (for version 2.x, blowfish) and must -be unique. It must designate an image file with its attribute *src*. - -## AGL features - -The AGL framework uses the feature tag for specifying security and binding -requirement of the widget. - -Since the migration of the framework to leverage systemd power, -the features are of important use to: - -- declare more than just an application -- declare the expected dependencies -- declare the expected permissions -- 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. -For example, a publisher could provide a widget containing a 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] -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 explicit using a `<param>` entry. - -Example: - -```xml -<feature name="urn:AGL:widget:required-api"> - <param name="#target" value="main" /> - <param name="gps" value="auto" /> - <param name="afm-main" value="link" /> -</feature> -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"required-api": [ - { "name": "gps", "value": "auto" }, - { "name": "afm-main", "value": "link" } - ] -``` - -#### required-api: param name="#target" - -OPTIONAL - -Declares the name of the unit requiring 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. - -#### required-api: param name=[required api name] - -The name is the name of the required API. - -The value describes how to connect to the required api. -It is either: - -- 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: - The framework set automatically the kind of - the connection to the API - -- ws: - The framework connect using internal websockets - -- dbus: [OBSOLETE, shouldn't be used currently] - The framework connect using internal dbus - -- 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. - -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 `<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. - -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 explicit using a `<param>` entry. - -Example: - -```xml - <feature name="urn:AGL:widget:required-permission"> - <param name="#target" value="geoloc" /> - <param name="urn:AGL:permission:real-time" value="required" /> - <param name="urn:AGL:permission:syscall:*" value="required" /> - </feature> -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"required-permission":{ - "urn:AGL:permission:real-time":{ - "name":"urn:AGL:permission:real-time", - "value":"required" - }, - "urn:AGL:permission:syscall:*":{ - "name":"urn:AGL:permission:syscall:*", - "value":"required" - } -} -``` - -#### required-permission: param name="#target" - -OPTIONAL - -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. - -#### required-permission: param name=[required permission name] - -The value is either: - -- required: the permission is mandatorily needed except if the feature - isn't required (required="false") and in that case it is optional. -- optional: the permission is optional - -### provided-unit: feature name="urn:AGL:widget:provided-unit" - -This feature is made for declaring new units -for the widget. -Using this feature, a software publisher -can provide more than one application in the same widget. - -Example: - -```xml - <feature name="urn:AGL:widget:provided-unit"> - <param name="#target" value="geoloc" /> - <param name="description" value="binding of name geoloc" /> - <param name="content.src" value="index.html" /> - <param name="content.type" value="application/vnd.agl.service" /> - </feature> -``` - -This will be *virtually* translated for mustaches to the JSON - -```json - { - "#target":"geoloc", - "description":"binding of name geoloc", - "content":{ - "src":"index.html", - "type":"application\/vnd.agl.service" - }, - ... - } -``` - -#### provided-unit: param name="#target" - -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. -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. -The value can't be "main". - -#### provided-unit: param name="content.type" - -REQUIRED - -The mimetype of the provided unit. - -#### provided-unit: param name="content.src" - -A path to the source - -#### other parameters - -The items that can be set for the main unit -can also be set using the params if needed. - -- description -- name.content -- name.short -- ... - -### provided-api: feature name="urn:AGL:widget:provided-api" - -Use this feature for exporting one or more API of a unit -to other widgets of the platform. - -This feature is an important feature of the framework. - -Example: - -```xml - <feature name="urn:AGL:widget:provided-api"> - <param name="#target" value="geoloc" /> - <param name="geoloc" value="auto" /> - <param name="moonloc" value="auto" /> - </feature> -``` - -This will be *virtually* translated for mustaches to the JSON - -```json - "provided-api":[ - { - "name":"geoloc", - "value":"auto" - }, - { - "name":"moonloc", - "value":"auto" - } - ], -``` - -#### provided-api: param name="#target" - -OPTIONAL - -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. - -#### provided-api: param name=[name of exported api] - -The name give the name of the api that is exported. - -The value is one of the following values: - -- ws: - export the api using UNIX websocket - -- dbus: [OBSOLETE, shouldn't be used currently] - export the API using dbus - -- 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 - <feature name="urn:AGL:widget:file-properties"> - <param name="flite" value="executable" /> - <param name="jtalk" value="executable" /> - </feature> -``` - -#### 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 -how to create systemd units for widgets. - -Known types for the type of content are: - -- ***text/html***: - HTML application, - content.src designates the home page of the application - -- ***application/vnd.agl.native*** - AGL compatible native, - content.src designates the relative path of the binary. - -- ***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. - For such application, only security setup is made. - -Adding more types is easy, it just need to edit the configuration -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. -The transition to systemd let these types out at the moment. - -- ***application/vnd.agl.url*** -- ***text/vnd.qt.qml***, ***application/vnd.agl.qml*** -- ***application/vnd.agl.qml.hybrid*** -- ***application/vnd.agl.html.hybrid*** - -## The configuration file afm-unit.conf - -The integration of the framework with systemd -mainly consists of creating the systemd unit -files corresponding to the need and requirements -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 -formalism of [mustache][] to describes all the units. - -Let present how it works using the following diagram that -describes graphically the workflow of creating the unit -files for systemd `afm-unit.conf` from the configuration -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. -This representation is shown along the examples of the documentation -of the config files of widgets. - -In a second step, the mustache template `afm-unit.conf` -is instantiated using the C library [mustach][] that follows -the rules of [mustache][mustache] and with all its available -extensions: - -- use of colon (:) for explicit substitution -- 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. -The directives are: - -- %nl - Produce an empty line at the end -- %begin systemd-unit -- %end systemd-unit - Delimit the produced unit, its begin and its end -- %systemd-unit user -- %systemd-unit system - 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. - The extension is automatically computed from the type - and must not be set in the name. -- %systemd-unit wanted-by NAME - Tells to install a link to the unit in the wants of NAME - -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-`. -The variables starting with `X-AFM-` but not with `X-AFM--` are -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. -By example, the variable `X-AFM--http-port` is used to -record the allocated port for applications. - -[mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache" -[mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" -[semantic-version]: http://semver.org/ "Semantic versioning" |