docs/config.xml.md

   1 The configuration file config.xml
   2 ===========
   3
   4 The widgets are described by the W3C's technical recommendations
   5 [Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig]
   6  that specifies the configuration file **config.xml**.
   7
   8 Overview
   9 --------
  10
  11 The file **config.xml** describes important data of the application
  12 to the framework:
  13
  14 - the unique identifier of the application
  15 - the name of the application
  16 - the type of the application
  17 - the icon of the application
  18 - the permissions linked to the application
  19 - the services and dependancies of the application
  20
  21 The file MUST be at the root of the widget and MUST be case sensitively name
  22 ***config.xml***.
  23
  24 The file **config.xml** is a XML file described by the document
  25 [widgets].
  26
  27 Here is the example of the config file for the QML application SmartHome.
  28
  29 ```xml
  30 <?xml version="1.0" encoding="UTF-8"?>
  31 <widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
  32   <name>SmartHome</name>
  33   <icon src="smarthome.png"/>
  34   <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
  35   <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
  36 automated house. The user interface is completely done with QML.</description>
  37   <author>Qt team</author>
  38   <license>GPL</license>
  39 </widget>
  40 ```
  41
  42 The most important items are:
  43
  44 - **<widget id="......"\>**: gives the id of the widget. It must be unique.
  45
  46 - **<widget version="......"\>**: gives the version of the widget
  47
  48 - **<icon src="..."\>**: gives a path to the icon of the application
  49   (can be repeated with different sizes)
  50
  51 - **<content src="..." type="..."\>**: this indicates the entry point and its type.
  52
  53 Standard elements of "config.xml"
  54 ---------------------------------
  55
  56 ### The element widget
  57
  58 #### the attribute id of widget
  59
  60 The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
  61
  62 Values for *id* are any non empty string containing only latin letters,
  63 arabic digits, and the three characters '.' (dot), '-' (dash) and
  64 '_' (underscore).
  65
  66 Authors can use a mnemonic id or can pick a unique id using
  67 command **uuid** or **uuidgen**.
  68
  69 ### the attribute version of widget
  70
  71 The attribute *version* is mandatory (for version 2.x, blowfish).
  72
  73 Values for *version* are any non empty string containing only latin letters,
  74 arabic digits, and the three characters '.' (dot), '-' (dash) and
  75 '_' (underscore).
  76
  77 Version values are dot separated fields MAJOR.MINOR.REVISION.
  78 Such version would preferabily follow guidelines of
  79 [semantic versionning][semantic-version].
  80
  81 ### The element content
  82
  83 The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
  84 (subject to localisation) with its attribute *src*.
  85
  86 The content designed depends on its type. See below for the known types.
  87
  88 ### The element icon
  89
  90 The element *icon* is mandatory (for version 2.x, blowfish) and must
  91 be unique. It must designate an image file with its attribute *src*.
  92
  93 AGL features
  94 ------------
  95
  96 The AGL framework uses the feature tag for specifying security and binding
  97 requirement of the widget.
  98
  99 The current version of AGL (up to 2.0.1, blowfish) has no fully implemented
 100 features.
 101
 102 The features planned to be implemented are described below.
 103
 104 ### feature name="urn:AGL:widget:required-api"
 105
 106 List of the api required by the widget.
 107
 108 Each required api must be explicited using a <param> entry.
 109
 110 Example:
 111 ```xml
 112 <feature name="urn:AGL:widget:required-api">
 113   <param name="urn:AGL:permission:A" value="required" />
 114   <param name="urn:AGL:permission:B" value="optional" />
 115 </feature>
 116 ```
 117
 118 This will be *virtually* translated for mustaches to the JSON
 119 ```json
 120 "required-api": {
 121   "param": [
 122       { "name": "urn:AGL:permission:A", "value": "required", "required": true },
 123       { "name": "urn:AGL:permission:A", "value": "optional", "optional": true }
 124     ],
 125   "urn:AGL:permission:A": { "name": "urn:AGL:permission:A", "value": "required", "required": true },
 126   "urn:AGL:permission:B": { "name": "urn:AGL:permission:B", "value": "optional", "optional": true }
 127 }
 128 ```
 129
 130 #### param name="#target"
 131
 132 Declares the name of the component requiring the listed bindings.
 133 Only one instance of the param "#target" is allowed.
 134 When there is not instance of the param
 135 The value is either:
 136
 137 - required: the binding is mandatorily needed except if the feature
 138 isn't required (required="false") and in that case it is optional.
 139 - optional: the binding is optional
 140
 141 #### param name=[required api name]
 142
 143 The value is either:
 144
 145 - required: the binding is mandatorily needed except if the feature
 146 isn't required (required="false") and in that case it is optional.
 147 - optional: the binding is optional
 148
 149 ### feature name="urn:AGL:widget:required-permission"
 150
 151 List of the permissions required by the widget.
 152
 153 Each required permission must be explicited using a <param> entry.
 154
 155 #### param name=[required permission name]
 156
 157 The value is either:
 158
 159 - required: the permission is mandatorily needed except if the feature
 160 isn't required (required="false") and in that case it is optional.
 161 - optional: the permission is optional
 162
 163 ### feature name="urn:AGL:widget:provided-api"
 164
 165 Use this feature for each provided api of the widget.
 166 The parameters are:
 167
 168 #### param name="subid"
 169
 170 REQUIRED
 171
 172 The value is the string that must match the binding prefix.
 173 It must be unique.
 174
 175 #### param name="name"
 176
 177 REQUIRED
 178
 179 The value is the string that must match the binding prefix.
 180 It must be unique.
 181
 182 #### param name="src"
 183
 184 REQUIRED
 185
 186 The value is the path of the shared library for the binding.
 187
 188 #### param name="type"
 189
 190 REQUIRED
 191
 192 Currently it must be ***application/vnd.agl.binding.v1***.
 193
 194
 195 #### param name="scope"
 196
 197 REQUIRED
 198
 199 The value indicate the availability of the binidng:
 200
 201 - private: used only by the widget
 202 - public: available to allowed clients as a remote service (requires permission+)
 203 - inline: available to allowed clients inside their binding (unsafe, requires permission+++)
 204
 205 #### param name="needed-binding"
 206
 207 OPTIONAL
 208
 209 The value is a space separated list of binding's names that the binding needs.
 210
 211 ### feature name="urn:AGL:widget:defined-permission"
 212
 213 Each required permission must be explicited using a <param> entry.
 214
 215 #### param name=[defined permission name]
 216
 217 The value is the level of the defined permission.
 218 Standard levels are:
 219
 220 - system
 221 - platform
 222 - partner
 223 - tiers
 224 - public
 225
 226 This level defines the level of accreditation required to get the given
 227 permission. The accreditions are given by signatures of widgets.
 228
 229 Known content types
 230 -------------------
 231
 232 The configuration file ***/etc/afm/afm-unit.conf*** defines the types
 233 of widget known and how to launch it.
 234
 235 Known types for the type of content are (for version 2.x, blowfish):
 236
 237 - ***text/html***:
 238    HTML application,
 239    content.src designates the home page of the application
 240
 241 - ***application/x-executable***:
 242    Native application,
 243    content.src designates the relative path of the binary
 244
 245 - ***application/vnd.agl.url***:
 246    Internet url,
 247    content.src designates the url to be used
 248
 249 - ***application/vnd.agl.service***:
 250    AGL service defined as a binder,
 251    content.src designates the directory of provided binders,
 252    http content, if any, must be put in the subdirectory ***htdocs*** of the widget
 253
 254 - ***application/vnd.agl.native***:
 255    Native application with AGL service defined as a binder,
 256    content.src designates the relative path of the binary,
 257    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 258    http content, if any, must be put in the subdirectory ***htdocs*** of the widget
 259
 260 - ***text/vnd.qt.qml***, ***application/vnd.agl.qml***:
 261    QML application,
 262    content.src designate the relative path of the QML root,
 263    imports must be put in the subdirectory ***imports*** of the widget
 264
 265 - ***application/vnd.agl.qml.hybrid***:
 266    QML application with bindings,
 267    content.src designate the relative path of the QML root,
 268    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 269    imports must be put in the subdirectory ***imports*** of the widget
 270
 271 - ***application/vnd.agl.html.hybrid***:
 272    HTML application,
 273    content.src designates the home page of the application,
 274    bindings, if any must be put in the subdirectory ***lib*** of the widget,
 275    http content must be put in the subdirectory ***htdocs*** of the widget
 276
 277 ---
 278
 279
 280 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 281 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 282 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 283 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 284
 285
 286 [meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
 287 [widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
 288 [widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
 289 [libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
 290 [openssl]:          https://www.openssl.org                                         "OpenSSL"
 291 [xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
 292 [json-c]:           https://github.com/json-c/json-c                                "JSON-c"
 293 [d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
 294 [libzip]:           http://www.nih.at/libzip                                        "libzip"
 295 [cmake]:            https://cmake.org                                               "CMake"
 296 [security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
 297 [app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
 298 [tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
 299 [tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
 300 [semantic-version]: http://semver.org/                                              "Semantic versionning"
 301
 302
 303