diff options
Diffstat (limited to 'docs/widgets.md')
| -rw-r--r-- | docs/widgets.md | 236 |
1 files changed, 221 insertions, 15 deletions
diff --git a/docs/widgets.md b/docs/widgets.md index 5637f2c..c23faa8 100644 --- a/docs/widgets.md +++ b/docs/widgets.md @@ -1,19 +1,30 @@ The widgets =========== -The widgets ------------ - The widgets are described by the technical recommendations [widgets] and [widgets-digsig]. In summary, **widgets are ZIP files that can be signed and whose content is described by the file <config.xml>**. -### The configuration file config.xml +The configuration file config.xml +--------------------------------- + +The file **config.xml** describes important data of the application +to the framework: -This is one of the important file of the widget. -It fully describes the widget. +- 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 dependancies 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. @@ -45,7 +56,193 @@ The most important items are: Further development will add handling of <feature> for requiring and providing permissions and services. -### Tools for managing widgets +--- + +### 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 *id* 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. + +#### The element content + +The element *content* is mandatory (for version 2.x, blowfish) and must designate a file +(subject to localisation) 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*. + +### Known widget types and content + +The configuration file ***/etc/afm/afm-launch.conf*** defines the types +of widget known and how to launch it. + +Known types for the type of content are (for version 2.x, blowfish): + +- ***text/html***: + HTML application, + content.src designates the home page of the application + +- ***application/x-executable***: + Native application, + content.src designates the relative path of the binary + +- ***application/vnd.agl.url***: + Internet url, + content.src designates the url to be used + +- ***application/vnd.agl.service***: + AGL service defined as a binder, + content.src designates the directory of provided binders, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***application/vnd.agl.native***: + Native application with AGL service defined as a binder, + content.src designates the relative path of the binary, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content, if any, must be put in the subdirectory ***htdocs*** of the widget + +- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***: + QML application, + content.src designate the relative path of the QML root, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.qml.hybrid***: + QML application with bindings, + content.src designate the relative path of the QML root, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + imports must be put in the subdirectory ***imports*** of the widget + +- ***application/vnd.agl.html.hybrid***: + HTML application, + content.src designates the home page of the application, + bindings, if any must be put in the subdirectory ***lib*** of the widget, + http content must be put in the subdirectory ***htdocs*** of the widget + +--- + +### AGL features + +The AGL framework uses the feature tag for specifying security and binding +requirement of the widget. + +The current version of AGL (up to 2.0.1, blowfish) has no fully implemented +features. + +The features planned to be implemented are described below. + +#### feature name="urn:AGL:required-binding" + +List of the bindings required by the widget. + +Each required binding must be explicited using a <param> entry. + +##### param name=[required binding name] + +The value is either: + +- required: the binding is mandatorily needed except if the feature +isn't required (required="false") and in that case it is optional. +- optional: the binding is optional + +#### feature name="urn:AGL:required-permission" + +List of the permissions required by the widget. + +Each required permission must be explicited using a <param> entry. + +##### 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 + +#### feature name="urn:AGL:provided-binding" + +Use this feature for each provided binding of the widget. +The parameters are: + +##### param name="name" + +REQUIRED + +The value is the string that must match the binding prefix. +It must be unique. + +##### param name="src" + +REQUIRED + +The value is the path of the shared library for the binding. + +##### param name="type" + +REQUIRED + +Currently it must be ***application/vnd.agl.binding.v1***. + + +##### param name="scope" + +REQUIRED + +The value indicate the availability of the binidng: + +- private: used only by the widget +- public: available to allowed clients as a remote service (requires permission+) +- inline: available to allowed clients inside their binding (unsafe, requires permission+++) + +##### param name="needed-binding" + +OPTIONAL + +The value is a space separated list of binding's names that the binding needs. + +#### feature name="urn:AGL:defined-permission" + +Each required permission must be explicited using a <param> entry. + +##### param name=[defined permission name] + +The value is the level of the defined permission. +Standard levels are: + +- system +- platform +- partner +- public + +This level defines the level of accreditation required to get the given +permission. The accreditions are given by signatures of widgets. + + +Tools for managing widgets +-------------------------- This project includes tools for managing widgets. These tools are: @@ -82,7 +279,16 @@ $ unzip WIDGET -d DIRECTORY *Note that DIRECTORY will be created if needed*. -### Signing a widget +Getting data about a widget file +--------------------------------- + +The command **wgtpkg-info** opens a widget file, reads its **config.xml** +file and displays its content in a human readable way. + +Signing and packing widget +-------------------------- + +### Signing To sign a widget, you need a private key and its certificate. @@ -103,7 +309,7 @@ Example 2: add a distributor signature $ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY ``` -### Packing a widget +### Packing This operation can be done using the command **zip** but we provide the tool **wgtpkg-pack** that may add checking. @@ -112,12 +318,6 @@ Example: ```bash $ wgtpkg-pack DIRECTORY -o file.wgt ``` - -### Getting data about a widget file - -The command **wgtpkg-info** opens a widget file, reads its **config.xml** -file and displays its content in a human readable way. - Writing a widget ---------------- @@ -185,6 +385,12 @@ This allows every user to read every file. The data of a user are in its directory and are labelled by the security-manager using the labels of the application. +[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" [widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" [widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" |