From 5b74cd6f2b5cdd82273759aa7d72150dfff58a2c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Jos=C3=A9=20Bollo?= Date: Mon, 12 Sep 2016 14:08:33 +0200 Subject: [PATCH] add documentation & ideas about config.xml MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Also enforce the strings for 'id' and 'version' to be not empty in config.xml Change-Id: I510b62891885033e0b750fac5f5de5e0fd25d75d Signed-off-by: JosÃ© Bollo --- doc/afm-system-daemon.html | 4 +- doc/afm-user-daemon.html | 4 +- doc/application-framework.html | 4 +- doc/overview.html | 4 +- doc/quick-tutorial.html | 4 +- doc/security-framework.html | 4 +- doc/updt.sh | 1 + doc/widgets.html | 62 +++++++----- doc/writing-config.xml.html | 168 +++++++++++++++++++++++++++++++ doc/writing-config.xml.md | 217 +++++++++++++++++++++++++++++++++++++++++ src/wgtpkg-install.c | 9 +- 11 files changed, 445 insertions(+), 36 deletions(-) create mode 100644 doc/writing-config.xml.html create mode 100644 doc/writing-config.xml.md diff --git a/doc/afm-system-daemon.html b/doc/afm-system-daemon.html index 6cd5ede..199bf38 100644 --- a/doc/afm-system-daemon.html +++ b/doc/afm-system-daemon.html @@ -8,10 +8,10 @@ The afm-system-daemon + -

diff --git a/doc/afm-user-daemon.html b/doc/afm-user-daemon.html index 364218f..5bf56f7 100644 --- a/doc/afm-user-daemon.html +++ b/doc/afm-user-daemon.html @@ -8,10 +8,10 @@ The afm-user-daemon + -

diff --git a/doc/application-framework.html b/doc/application-framework.html index 4a7e36a..8d0e0e3 100644 --- a/doc/application-framework.html +++ b/doc/application-framework.html @@ -8,10 +8,10 @@ Application framework + -

diff --git a/doc/overview.html b/doc/overview.html index c5998a6..055d5d5 100644 --- a/doc/overview.html +++ b/doc/overview.html @@ -7,10 +7,10 @@ AGL framework, overview of the proposal of IoT.bzh + -

diff --git a/doc/quick-tutorial.html b/doc/quick-tutorial.html index 72bf123..3b5c6a9 100644 --- a/doc/quick-tutorial.html +++ b/doc/quick-tutorial.html @@ -8,10 +8,10 @@ AGL Application Framework: A Quick Tutorial + -

diff --git a/doc/security-framework.html b/doc/security-framework.html index dd4e72a..bf4dd48 100644 --- a/doc/security-framework.html +++ b/doc/security-framework.html @@ -7,10 +7,10 @@ The security framework + -

diff --git a/doc/updt.sh b/doc/updt.sh index 5267ad5..d0c02e7 100755 --- a/doc/updt.sh +++ b/doc/updt.sh @@ -41,6 +41,7 @@ meta() { mkhtml() { local x=$1 local h=${x%%.md}.html + echo updating $h from $x meta "$x" | pandoc --css doc.css -f markdown -t html5 --toc > "$h" } diff --git a/doc/widgets.html b/doc/widgets.html index 5a22e4b..8c27577 100644 --- a/doc/widgets.html +++ b/doc/widgets.html @@ -8,29 +8,47 @@ The widgets - +

@@ -68,7 +86,7 @@ code > span.er { color: #ff0000; font-weight: bold; }

The configuration file config.xml

This is one of the important file of the widget. It fully describes the widget.

Here is the example of the config file for the QML application SmartHome.

<?xml version="1.0" encoding="UTF-8"?>
+<?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"/>
@@ -77,7 +95,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
 automated house. The user interface is completely done with QML.</description>
   <author>Qt team</author>
   <license>GPL</license>
-</widget>
+</widget>

The most important items are:

<widget id="......">: gives the id of the widget. It must be unique.

For all these commands, a tiny help is available with options -h or --help.

There is no tool for unpacking a widget. For doing such operation, you can use the command unzip.

To list the files of a widget:

$ unzip -l WIDGET

$ unzip -l WIDGET

To extract a widget in some directory:

$ unzip WIDGET -d DIRECTORY

$ unzip WIDGET -d DIRECTORY

Note that DIRECTORY will be created if needed.

To sign a widget, you need a private key and its certificate.

The tool wgtpkg-sign creates or replace a signature file in the directory of the widget BEFORE its packaging.

There are two types of signature files: author and distributor.

Example 1: add an author signature

$ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY

$ wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY

Example 2: add a distributor signature

$ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY

$ wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY

This operation can be done using the command zip but we provide the tool wgtpkg-pack that may add checking.

Example:

$ wgtpkg-pack DIRECTORY -o file.wgt

$ wgtpkg-pack DIRECTORY -o file.wgt

The command wgtpkg-info opens a widget file, reads its config.xml file and displays its content in a human readable way.

diff --git a/doc/writing-config.xml.html b/doc/writing-config.xml.html new file mode 100644 index 0000000..35c7372 --- /dev/null +++ b/doc/writing-config.xml.html @@ -0,0 +1,168 @@ + + + + + + + Writing the configuration file "config.xml" + + + + + + +

Writing the configuration file "config.xml"

02 septembre 2016

+ +

Writing the configuration file "config.xml"

About "config.xml"

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 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.

Example of "config.xml"

Here is the example of the config file for the QML application SmartHome.

<?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>

Standard elements of "config.xml"

+ + +

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 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.

+ +

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:provides-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:required-permission"

Several permission can be listed or none whether no permission is requested for the widget.

Each required permission must be explicited using a entry.

param name=[required permission name]

The value is either:

required: the permission is really needed.
optional: the permission isn't mandatory

feature name="urn:AGL:-permission"

+ + diff --git a/doc/writing-config.xml.md b/doc/writing-config.xml.md new file mode 100644 index 0000000..54172ff --- /dev/null +++ b/doc/writing-config.xml.md @@ -0,0 +1,217 @@ +Writing the configuration file "config.xml" +=========================================== + +About "config.xml" +------------------ + +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 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]. + +Example of "config.xml" +----------------------- + +Here is the example of the config file for the QML application SmartHome. + +```xml + + + SmartHome + + + + 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. + + Qt team + GPL + +``` + +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:provides-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:required-permissions" + +List of the permissions required by the widget. + +Each required permission must be explicited using a entry. + +#### param name=[required permission name] + +The value is either: + +- required: the permission is really needed. +- optional: the permission isn't mandatory + +### feature name="urn:AGL:defined-permissions" + +Each required permission must be explicited using a entry. + +#### param name=[defined permission name] + +The value is the level of the defined permission: + +- system: +- platform: +- partner +- public: + + + + + +[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" + diff --git a/src/wgtpkg-install.c b/src/wgtpkg-install.c index 264606a..7d0c318 100644 --- a/src/wgtpkg-install.c +++ b/src/wgtpkg-install.c @@ -56,14 +56,19 @@ static int check_valid_string(const char *value, const char *name) return -1; pos = 0; c = value[pos]; - while(c) { + if (c == 0) { + ERROR("empty string forbidden in '%s' (temporary constraints)", name); + errno = EINVAL; + return -1; + } + do { if (!isalnum(c) && !strchr(".-_", c)) { ERROR("forbidden char %c in '%s' -> '%s' (temporary constraints)", c, name, value); errno = EINVAL; return -1; } c = value[++pos]; - } + } while(c); return 0; } -- 2.16.6

The configuration file config.xml

Signing a widget

Packing a widget

Getting data about a widget file

Writing a widget

Writing the configuration file "config.xml"

02 septembre 2016

Writing the configuration file "config.xml"

About "config.xml"

Example of "config.xml"

Standard elements of "config.xml"

The element widget

the attribute id of widget

the attribute version of widget

The element content

The element icon

Known widget types and content

AGL features

feature name="urn:AGL:provides-binding"

param name="name"

param name="src"

param name="type"

param name="scope"

param name="needed-binding"

feature name="urn:AGL:required-permission"

param name=[required permission name]

feature name="urn:AGL:-permission"