diff options
| -rw-r--r-- | doc/afm-system-daemon.html | 57 | ||||
| -rw-r--r-- | doc/afm-system-daemon.md | 89 | ||||
| -rw-r--r-- | doc/afm-user-daemon.html | 270 | ||||
| -rw-r--r-- | doc/afm-user-daemon.md | 266 | ||||
| -rw-r--r-- | doc/application-framework.html | 69 | ||||
| -rw-r--r-- | doc/application-framework.md | 62 |
6 files changed, 370 insertions, 443 deletions
diff --git a/doc/afm-system-daemon.html b/doc/afm-system-daemon.html index 00cf81a..4569bc2 100644 --- a/doc/afm-system-daemon.html +++ b/doc/afm-system-daemon.html @@ -8,7 +8,7 @@ <h1>The afm-system-daemon</h1> <pre><code>version: 1 -Date: 29 mai 2016 +Date: 30 mai 2016 Author: José Bollo </code></pre> @@ -36,30 +36,27 @@ Author: José Bollo <a name="Foreword"></a> <h2>Foreword</h2> -<p>This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ.</p> - -<p>In case of differences, it is assumed that this document is right -and the implementation is wrong.</p> +<p>This document describes application framework system daemon fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications.</p> <a name="Introduction"></a> <h2>Introduction</h2> <p>The daemon <strong>afm-system-daemon</strong> is in charge of installing -applications on the system. Its main tasks are:</p> +applications on AGL system. Its main tasks are:</p> <ul> -<li><p>installs the applications and setup the security framework -to include it</p></li> -<li><p>uninstall the applications</p></li> +<li><p>installs applications and setup security framework +for newly installed application.</p></li> +<li><p>uninstall applications</p></li> </ul> -<p>The <strong>afm-system-daemon</strong> takes its orders from the system +<p>The <strong>afm-system-daemon</strong> takes its orders from system instance of D-Bus.</p> -<p>The figure below summarizes the situation of the -<strong>afm-system-daemon</strong> in the system.</p> +<p>The figure below summarizes the situation of <strong>afm-system-daemon</strong> in the system.</p> <pre><code>+------------------------------------------------------------+ | User | @@ -142,7 +139,7 @@ members <strong><em>install</em></strong> and <strong><em>uninstall</em></strong typed protocol is not used except for transmitting only one string in both directions.</p> -<p>The client and the service are using JSON serialisation to +<p>The client and the service are using JSON serialization to exchange data.</p> <p>The D-Bus interface is defined by:</p> @@ -157,10 +154,10 @@ exchange data.</p> <p>The signature of any member of the interface is <strong><em>string -> string</em></strong> for <strong><em>JSON -> JSON</em></strong>.</p> -<p>This is the normal case. In case of error, the current implmentation +<p>This is the normal case. In case of error, the current implementation returns a dbus error that is a string.</p> -<p>Here is an example that use <em>dbus-send</em> to query data on +<p>Here is an example using <em>dbus-send</em> to query data on installed applications.</p> <pre><code>dbus-send --session --print-reply \ @@ -177,24 +174,23 @@ org.AGL.afm.system.install 'string:"/tmp/appli.wgt"' <a name="Method.org.AGL.afm.system.install"></a> <h4>Method org.AGL.afm.system.install</h4> -<p><strong>Description</strong>: Install an application from its widget file.</p> +<p><strong>Description</strong>: Install an application from a widget file.</p> -<p>If an application of the same <em>id</em> and <em>version</em> exists, it is not -reinstalled except if <em>force=true</em>.</p> +<p>When an application with the same <em>id</em> and <em>version</em> already exists. Outside of +using <em>force=true</em> the application is not reinstalled.</p> -<p>Applications are installed in the subdirectories of the common directory -of applications. +<p>Applications are installed the subdirectories of applications common directory. If <em>root</em> is specified, the application is installed under the sub-directories of the <em>root</em> defined.</p> -<p>Note that this methods is a simple accessor to the method -<strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> +<p>Note that this methods is a simple accessor method of +<strong><em>org.AGL.afm.system.install</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p> <p>After the installation and before returning to the sender, -<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> +<strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> -<p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly, -a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p> +<p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionally, +a flag to <em>force</em> reinstallation, and, optionally, a <em>root</em> directory.</p> <p>Either just a string being the absolute path of the widget file:</p> @@ -225,14 +221,13 @@ the id of the added application.</p> <p><strong>Description</strong>: Uninstall an application from its id.</p> -<p>Note that this methods is a simple accessor to the method -<strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> +<p>Note that this methods is a simple method accessor of +<strong><em>org.AGL.afm.system.uninstall</em></strong> from <strong><em>afm-system-daemon</em></strong>.</p> <p>After the uninstallation and before returning to the sender, -<strong><em>afm-system-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> +<strong><em>afm-system-daemon</em></strong> sends a signal <strong><em>org.AGL.afm.system.changed</em></strong>.</p> -<p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to -<em>root</em> of the application.</p> +<p><strong>Input</strong>: the <em>id</em> of the application and optionally the application <em>root</em> path.</p> <p>Either a string:</p> diff --git a/doc/afm-system-daemon.md b/doc/afm-system-daemon.md index 7589574..2db11d8 100644 --- a/doc/afm-system-daemon.md +++ b/doc/afm-system-daemon.md @@ -3,7 +3,7 @@ The afm-system-daemon ===================== version: 1 - Date: 29 mai 2016 + Date: 30 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE @@ -12,29 +12,26 @@ TABLE-OF-CONTENT-HERE Foreword -------- -This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ. - -In case of differences, it is assumed that this document is right -and the implementation is wrong. +This document describes application framework system daemon fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications. Introduction ------------ The daemon **afm-system-daemon** is in charge of installing -applications on the system. Its main tasks are: +applications on AGL system. Its main tasks are: - - installs the applications and setup the security framework - to include it + - installs applications and setup security framework + for newly installed application. - - uninstall the applications + - uninstall applications -The **afm-system-daemon** takes its orders from the system +The **afm-system-daemon** takes its orders from system instance of D-Bus. -The figure below summarizes the situation of the -**afm-system-daemon** in the system. +The figure below summarizes the situation of **afm-system-daemon** in the system. +------------------------------------------------------------+ | User | @@ -115,7 +112,7 @@ D-Bus is mainly used for signaling and discovery. Its optimized typed protocol is not used except for transmitting only one string in both directions. -The client and the service are using JSON serialisation to +The client and the service are using JSON serialization to exchange data. The D-Bus interface is defined by: @@ -129,10 +126,10 @@ The D-Bus interface is defined by: The signature of any member of the interface is ***string -> string*** for ***JSON -> JSON***. -This is the normal case. In case of error, the current implmentation +This is the normal case. In case of error, the current implementation returns a dbus error that is a string. -Here is an example that use *dbus-send* to query data on +Here is an example using *dbus-send* to query data on installed applications. dbus-send --session --print-reply \ @@ -146,24 +143,23 @@ installed applications. #### Method org.AGL.afm.system.install -**Description**: Install an application from its widget file. +**Description**: Install an application from a widget file. -If an application of the same *id* and *version* exists, it is not -reinstalled except if *force=true*. +When an application with the same *id* and *version* already exists. Outside of +using *force=true* the application is not reinstalled. -Applications are installed in the subdirectories of the common directory -of applications. +Applications are installed the subdirectories of applications common directory. If *root* is specified, the application is installed under the sub-directories of the *root* defined. -Note that this methods is a simple accessor to the method -***org.AGL.afm.system.install*** of ***afm-system-daemon***. +Note that this methods is a simple accessor method of +***org.AGL.afm.system.install*** from ***afm-system-daemon***. After the installation and before returning to the sender, -***afm-system-daemon*** sends the signal ***org.AGL.afm.system.changed***. +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. -**Input**: The *path* of the widget file to install and, optionaly, -a flag to *force* reinstallation, and, optionaly, a *root* directory. +**Input**: The *path* of the widget file to install and, optionally, +a flag to *force* reinstallation, and, optionally, a *root* directory. Either just a string being the absolute path of the widget file: @@ -191,14 +187,13 @@ the id of the added application. **Description**: Uninstall an application from its id. -Note that this methods is a simple accessor to the method -***org.AGL.afm.system.uninstall*** of ***afm-system-daemon***. +Note that this methods is a simple method accessor of +***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***. After the uninstallation and before returning to the sender, -***afm-system-daemon*** sends the signal ***org.AGL.afm.system.changed***. +***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. -**Input**: the *id* of the application and, otpionaly, the path to -*root* of the application. +**Input**: the *id* of the application and optionally the application *root* path. Either a string: @@ -213,38 +208,6 @@ Or an object: **output**: the value 'true'. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - [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" diff --git a/doc/afm-user-daemon.html b/doc/afm-user-daemon.html index 77af347..d69c396 100644 --- a/doc/afm-user-daemon.html +++ b/doc/afm-user-daemon.html @@ -8,7 +8,7 @@ <h1>The afm-user-daemon</h1> <pre><code>version: 1 -Date: 29 mai 2016 +Date: 30 mai 2016 Author: José Bollo </code></pre> @@ -20,13 +20,13 @@ Author: José Bollo <li><a href="#Tasks.of..strong.afm-user-daemon..strong.">Tasks of <strong>afm-user-daemon</strong></a> <ul> <li><a href="#Maintaining.list.of.applications">Maintaining list of applications</a></li> - <li><a href="#Launching.applications">Launching applications</a></li> + <li><a href="#Launching.application">Launching application</a></li> <li><a href="#Managing.instances.of.running.applications">Managing instances of running applications</a></li> <li><a href="#Installing.and.uninstalling.applications">Installing and uninstalling applications</a></li> </ul> </li> <li><a href="#Starting..strong.afm-user-daemon..strong.">Starting <strong>afm-user-daemon</strong></a></li> - <li><a href="#Configuration.of.the.launcher">Configuration of the launcher</a> + <li><a href="#Launcher.Configuration.">Launcher Configuration </a> <ul> <li><a href="#mode.local">mode local</a></li> <li><a href="#mode.remote">mode remote</a></li> @@ -60,28 +60,26 @@ Author: José Bollo <a name="Foreword"></a> <h2>Foreword</h2> -<p>This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ.</p> - -<p>In case of differences, it is assumed that this document is right -and the implementation is wrong.</p> +<p>This document describes application framework user daemon fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications.</p> <a name="Introduction"></a> <h2>Introduction</h2> <p>The daemon <strong>afm-user-daemon</strong> is in charge of handling -applications for one user. Its main tasks are:</p> +applications on behalf of a user. Its main tasks are:</p> <ul> -<li><p>enumerate the applications that the user can run -and keep the list avalable on demand</p></li> -<li><p>start applications for the user, set their running -environment, set their security context</p></li> -<li><p>list the current runner applications</p></li> +<li><p>enumerate applications that end user can run +and keep this list available on demand</p></li> +<li><p>start applications on behalf of end user, set user running +environment, set user security context</p></li> +<li><p>list current runnable or running applications</p></li> <li><p>stop (aka pause), continue (aka resume), terminate -the running instance of application</p></li> -<li><p>transfer requests for installation or uninstallation -of applications to the dedicated system daemon +a running instance of a given application</p></li> +<li><p>transfer requests for installation/uninstallation +of applications to the corresponding system daemon <strong>afm-system-daemon</strong></p></li> </ul> @@ -89,8 +87,7 @@ of applications to the dedicated system daemon <p>The <strong>afm-user-daemon</strong> takes its orders from the session instance of D-Bus.</p> -<p>The figure below summarizes the situation of the -<strong>afm-user-daemon</strong> in the system.</p> +<p>The figure below summarizes the situation of <strong>afm-user-daemon</strong> in the system.</p> <pre><code>+------------------------------------------------------------+ | User | @@ -128,38 +125,40 @@ instance of D-Bus.</p> <h3>Maintaining list of applications</h3> <p>At start <strong>afm-user-daemon</strong> scans the directories containing -the applications and load in memory the list applications -availables to the current user.</p> +applications and load in memory a list of avaliable applications +accessible by current user.</p> -<p>When <strong>afm-system-daemon</strong> installs or removes an application, -it sends the signal <em>org.AGL.afm.system.changed</em> on success. -If it receives that signal, <strong>afm-user-daemon</strong> rebuild its -list of applications.</p> +<p>When <strong>afm-system-daemon</strong> installs or removes an application. +On success it sends the signal <em>org.AGL.afm.system.changed</em>. +When receiving such a signal, <strong>afm-user-daemon</strong> rebuilds its +applications list.</p> -<p><strong>afm-user-daemon</strong> provides the data that it collected about -application to its clients that either want to get that list -or to get information about one application.</p> +<p><strong>afm-user-daemon</strong> provides the data it collects about +applications to its clients. Clients may either request the full list +of avaliable applications or a more specific information about a +given application.</p> -<a name="Launching.applications"></a> -<h3>Launching applications</h3> +<a name="Launching.application"></a> +<h3>Launching application</h3> -<p><strong>afm-user-daemon</strong> launchs the applications. This means -that its builds a secure environment for the application -and then start it inside that secured environment.</p> +<p><strong>afm-user-daemon</strong> launches application. Its builds a secure +environment for the application before starting it within a +secured environment.</p> -<p>Applications of different kind can be launched.</p> +<p>Different kind of applications can be launched.</p> <p>This is set using a configuration file that describes -how to launch an application of a given kind for a given +how to launch an application of a given kind within a given mode.</p> <p>There is two launching modes: local or remote.</p> <p>Launching an application locally means that -the application and its binder are launcher together.</p> +the application and its binder are launched together.</p> -<p>Launching application remotely means that only the -binder is launched for the application.</p> +<p>Launching application remotely translates in only launching +the application binder. The UI by itself has to be activated +remotely by the requested (ie: HTML5 homescreen in a browser)</p> <p>Once launched, running instances of application receive a runid that identify them.</p> @@ -170,15 +169,15 @@ a runid that identify them.</p> <p><strong>afm-user-daemon</strong> manages the list of applications that it launched.</p> -<p>With the good permissions, a client can get the list -of the running instances and details about a specific -running instance. It can also terminate, stop or -continue a given application.</p> +<p>When owning the right permissions, a client can get the list +of running instances and details about a specific +running instance. It can also terminates, stops or +continues a given application.</p> <a name="Installing.and.uninstalling.applications"></a> <h3>Installing and uninstalling applications</h3> -<p>If the client has the good permission, +<p>If the client own the right permissions, <strong>afm-user-daemon</strong> delegates that task to <strong>afm-system-daemon</strong>.</p> @@ -200,16 +199,15 @@ located at /usr/lib/systemd/user/afm-user-daemon.service.</p> Can be repeated. -r ---root directory - - Includes the root application directory to - the database base of applications. +--root directory - Note that the default root directory for - applications is always added. It is defined - to be /usr/share/afm/applications (may change). + Includes root application directory or directories when + passing multiple rootdir to + applications database. - Can be repeated. + Note that default root directory for + applications is always added. In current version + /usr/share/afm/applications is used as default. -m --mode (local|remote) @@ -238,34 +236,34 @@ located at /usr/lib/systemd/user/afm-user-daemon.service.</p> Prints a short help. </code></pre> -<a name="Configuration.of.the.launcher"></a> -<h2>Configuration of the launcher</h2> +<a name="Launcher.Configuration."></a> +<h2>Launcher Configuration </h2> <p>It contains rules for launching applications. -When <strong>afm-user-daemon</strong> need to launch an application, -it looks to the mode of launch, local or remote, and the -type of the application as given by the file <strong><em>config.xml</em></strong> -of the widget.</p> +When <strong>afm-user-daemon</strong> has to launch an application, +it looks for launch mode (local or remote), as well as +for the type of application describe in <strong><em>config.xml</em></strong> +widget configuration file.</p> -<p>This couple mode and type allows to select the rule.</p> +<p>This tuple mode+type allows to select the adequate rule.</p> -<p>The configuration file is <strong>/etc/afm/afm-launch.conf</strong>.</p> +<p>Configuration file is <strong>/etc/afm/afm-launch.conf</strong>.</p> <p>It contains sections and rules. It can also contain comments -and empty lines to improve the readability.</p> +and empty lines to improve readability.</p> <p>The separators are space and tabulation, any other character -is meaning something.</p> +should have a meaning.</p> <p>The format is line oriented. The new line character separate the lines.</p> -<p>Lines having only separators are blank lines and are skipped. -Line having the character # (sharp) as first not separator character -are comment lines and are ignored.</p> +<p>Lines having only separators are blank lines and ignored. +Line having character #(sharp) at first position are comment +lines and ignored.</p> -<p>Lines starting with a not separator character are differents -of lines starting with a separator character.</p> +<p>Lines not starting with a separator are different +from lines starting with a separator character.</p> <p>The grammar of the configuration file is defined below:</p> @@ -295,8 +293,8 @@ NCHAR: CMT | CHAR </code></pre> <p>Here is a sample of configuration file for defining how -to launch an application declared of types <em>application/x-executable</em>, -<em>text/x-shellscript</em> and <em>text/html</em> in mode local:</p> +to launch an application of types <em>application/x-executable</em>, +<em>text/x-shellscript</em> and <em>text/html</em> in local mode:</p> <pre><code>mode local @@ -323,9 +321,9 @@ text/html <a name="mode.local"></a> <h3>mode local</h3> -<p>Within this mode, the launchers have either one or two vectors -describing them. All of these vectors are treated as programs -and are executed with the system call ‘execve’.</p> +<p>Within this mode, the launchers have either one or two description vectors. +All of those vectors are treated as programs +and are executed with ‘execve’ system call.</p> <p>The first vector is the leader vector and it defines the process group. The second vector (if any) is attached to the group @@ -337,19 +335,17 @@ defined by this first vector.</p> <p>Within this mode, the launchers have either one or two vectors describing them.</p> -<p>The first vector is treated as a program and is executed with -the system call ‘execve’.</p> +<p>The first vector is process as a program and is executed with +system call ‘execve’.</p> <p>The second vector (if any) defines a text that is returned -to the caller. This mechanism can be used to return the uri -to connect to for executing the application remotely.</p> +to the caller. This mechanism can be used to return a uri +for remote UI to connect on the newly launched application.</p> -<p>The daemon <strong><em>afm-user-daemon</em></strong> allocates a port for the -running the application remotely. -The current implmentation of the port allocation is just -incremental. -A more reliable (cacheable and same-originable) allocation -is to be defined.</p> +<p>The daemon <strong><em>afm-user-daemon</em></strong> allocates a port for each +new remote application. +The current implementation port allocation is incremental. +A smarter (cacheable and discoverable) allocation should be defined.</p> <a name="L.substitutions"></a> <h3>%substitutions</h3> @@ -368,7 +364,7 @@ to sequences.</p> <p>This simply emits the percent sign %</p></li> <li><p><strong><em>%a</em></strong>: appid</p> -<p>This is the application Id of the launched application.</p> +<p>Holds application Id of launched application.</p> <p>Defined by the attribute <strong>id</strong> of the element <strong><widget></strong> of <strong>config.xml</strong>.</p></li> @@ -376,11 +372,10 @@ of <strong>config.xml</strong>.</p></li> <p>The file within the widget directory that is the entry point.</p> -<p>For a HTML application, it is the relative path to the main +<p>For HTML applications, it represents the relative path to main page (aka index.html).</p> -<p>Defined by the attribute <strong>src</strong> of the element <strong><content></strong> -of <strong>config.xml</strong>.</p></li> +<p>Defined by attribute <strong>src</strong> of the element <strong><content></strong> within <strong>config.xml</strong>.</p></li> <li><p><strong><em>%D</em></strong>: datadir</p> <p>Path of the directory where the application runs (cwd) @@ -413,24 +408,23 @@ of <strong>config.xml</strong>.</p></li> element <strong><name></strong> of <strong>config.xml</strong>.</p></li> <li><p><strong><em>%p</em></strong>: plugins</p> -<p>Unhandled until now.</p> - -<p>Will be the colon separated list of plugins and plugins directory.</p></li> +<p>In the future should represent the list of plugins and plugins directory separated by ‘,’. +Warning: not supported in current version.</p></li> <li><p><strong><em>%P</em></strong>: port</p> <p>A port to use. It is currently a kind of random port. The precise model is to be defined later.</p></li> <li><p><strong><em>%R</em></strong>: readyfd</p> -<p>Number of the file descriptor to use for signalling -readyness of the launched process.</p></li> +<p>Number of file descriptor to use for signaling +readiness of launched process.</p></li> <li><p><strong><em>%r</em></strong>: rootdir</p> -<p>Path of the directory containing the widget and its data.</p></li> +<p>Path of directory containing the widget and its data.</p></li> <li><p><strong><em>%S</em></strong>: secret</p> -<p>An hexadecimal number that can be used to pair the client -with its server binder.</p></li> +<p>An hexadecimal number that can be used to initialize pairing of client +and application binder.</p></li> <li><p><strong><em>%W</em></strong>: width</p> <p>Requested width for the widget.</p> @@ -447,27 +441,25 @@ of <strong>config.xml</strong>.</p></li> <h3>Overview of the dbus interface</h3> <p><strong><em>afm-user-daemon</em></strong> takes its orders from the session instance -of D-Bus. The use of D-Bus is great because it allows to implement +of D-Bus. D-Bus is nice to use in this context because it allows discovery and signaling.</p> -<p>The dbus of the session is by default adressed by the environment +<p>The dbus session is by default addressed by environment variable <strong><em>DBUS_SESSION_BUS_ADDRESS</em></strong>. Using <strong>systemd</strong> -the variable <em>DBUS_SESSION_BUS_ADDRESS</em> is automatically set for +variable <em>DBUS_SESSION_BUS_ADDRESS</em> is automatically set for user sessions.</p> -<p>The <strong>afm-user-daemon</strong> is listening with the destination name -<strong><em>org.AGL.afm.user</em></strong> at the object of path <strong><em>/org/AGL/afm/user</em></strong> -on the interface <strong><em>org.AGL.afm.user</em></strong> for the below detailed -members <strong><em>runnables</em></strong>, <strong><em>detail</em></strong>, <strong><em>start</em></strong>, <strong><em>terminate</em></strong>, +<p>The <strong>afm-user-daemon</strong> is listening on destination name +<strong><em>org.AGL.afm.user</em></strong> at object path <strong><em>/org/AGL/afm/user</em></strong> +on interface <strong><em>org.AGL.afm.user</em></strong> for following members: + <strong><em>runnables</em></strong>, <strong><em>detail</em></strong>, <strong><em>start</em></strong>, <strong><em>terminate</em></strong>, <strong><em>stop</em></strong>, <strong><em>continue</em></strong>, <strong><em>runners</em></strong>, <strong><em>state</em></strong>, <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p> <p>D-Bus is mainly used for signaling and discovery. Its optimized -typed protocol is not used except for transmitting only one string -in both directions.</p> +typed protocol is not used except for transmission of standalone strings.</p> -<p>The client and the service are using JSON serialisation to -exchange data.</p> +<p>Clients and Services are using JSON serialisation to exchange data.</p> <p>The D-Bus interface is defined by:</p> @@ -481,10 +473,10 @@ exchange data.</p> <p>The signature of any member of the interface is <strong><em>string -> string</em></strong> for <strong><em>JSON -> JSON</em></strong>.</p> -<p>This is the normal case. In case of error, the current implmentation -returns a dbus error that is a string.</p> +<p>This is the normal case. In case of error, the current implementation +returns a dbus error as a string.</p> -<p>Here is an example that use <em>dbus-send</em> to query data on +<p>Here an example using <em>dbus-send</em> to query data on installed applications.</p> <pre><code>dbus-send --session --print-reply \ @@ -501,8 +493,7 @@ orders to <strong>afm-user-daemon</strong>. This small scripts allows to send command to <strong><em>afm-user-daemon</em></strong> either interactively at shell prompt or scriptically.</p> -<p>The syntax is simple: it accept a command and if the command -requires it, the argument to the command.</p> +<p>The syntax is simple: it accept a command and when requires attached arguments.</p> <p>Here is the summary of <strong><em>afm-util</em></strong>:</p> @@ -615,12 +606,12 @@ an application as described above for the method <p><strong>Description</strong>: Install an application from its widget file.</p> <p>If an application of the same <em>id</em> and <em>version</em> exists, it is not -reinstalled except if <em>force=true</em>.</p> +reinstalled except when <em>force=true</em>.</p> <p>Applications are installed in the subdirectories of the common directory -of applications. -If <em>root</em> is specified, the application is installed under the -sub-directories of the <em>root</em> defined.</p> +reserved for applications. +If <em>root</em> is specified, the application is installed under +sub-directories of defined <em>root</em>.</p> <p>Note that this methods is a simple accessor to the method <strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> @@ -628,10 +619,10 @@ sub-directories of the <em>root</em> defined.</p> <p>After the installation and before returning to the sender, <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p> -<p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly, -a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p> +<p><strong>Input</strong>: The <em>path</em> of widget file to be installed. Optionally, +a flag to <em>force</em> reinstallation and/or a <em>root</em> directory.</p> -<p>Either just a string being the absolute path of the widget file:</p> +<p>Simple form a simple string containing the absolute widget path:</p> <pre><code>"/a/path/driving/to/the/widget" </code></pre> @@ -645,10 +636,9 @@ a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directo } </code></pre> -<p>“wgt” and “root” must be absolute paths.</p> +<p>“wgt” and “root” MUST be absolute paths.</p> -<p><strong>output</strong>: An object with the field “added” being the string for -the id of the added application.</p> +<p><strong>output</strong>: An object containing field “added” to use as application ID.</p> <pre><code>{"added":"appli@x.y"} </code></pre> @@ -660,14 +650,14 @@ the id of the added application.</p> <p><strong>Description</strong>: Uninstall an application from its id.</p> -<p>Note that this methods is a simple accessor to the method -<strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p> +<p>Note that this methods is a simple accessor to +<strong><em>org.AGL.afm.system.uninstall</em></strong> method from <strong><em>afm-system-daemon</em></strong>.</p> <p>After the uninstallation and before returning to the sender, <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p> -<p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to -<em>root</em> of the application.</p> +<p><strong>Input</strong>: the <em>id</em> of the application and, optionally, the path to +application <em>root</em>.</p> <p>Either a string:</p> @@ -691,7 +681,7 @@ the id of the added application.</p> <p><strong>Description</strong>:</p> -<p><strong>Input</strong>: the <em>id</em> of the application and, optionaly, the +<p><strong>Input</strong>: the <em>id</em> of the application and, optionally, the start <em>mode</em> as below.</p> <p>Either just a string:</p> @@ -699,25 +689,24 @@ start <em>mode</em> as below.</p> <pre><code>"appli@x.y" </code></pre> -<p>Or an object having the field “id” of type string and -optionaly a field mode:</p> +<p>Or an object containing field “id” of type string and +optionally a field mode:</p> <pre><code>{"id":"appli@x.y","mode":"local"} </code></pre> -<p>The field “mode” as a string value being either “local” or “remote”.</p> +<p>The field “mode” is a string equal to either “local” or “remote”.</p> -<p><strong>output</strong>: The <em>runid</em> of the application launched. -The runid is an integer.</p> +<p><strong>output</strong>: The <em>runid</em> of the application launched. <em>runid</em> is an integer.</p> <hr /> <a name="Method.org.AGL.afm.user.terminate"></a> <h4>Method org.AGL.afm.user.terminate</h4> -<p><strong>Description</strong>: Terminates the application of <em>runid</em>.</p> +<p><strong>Description</strong>: Terminates the application attached to <em>runid</em>.</p> -<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to terminate.</p> +<p><strong>Input</strong>: The <em>runid</em> (an integer) of running instance to terminate.</p> <p><strong>output</strong>: the value ‘true’.</p> @@ -726,9 +715,9 @@ The runid is an integer.</p> <a name="Method.org.AGL.afm.user.stop"></a> <h4>Method org.AGL.afm.user.stop</h4> -<p><strong>Description</strong>: Stops the application of <em>runid</em> until terminate or continue.</p> +<p><strong>Description</strong>: Stops the application attached to <em>runid</em> until terminate or continue.</p> -<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to stop.</p> +<p><strong>Input</strong>: The <em>runid</em> (integer) of the running instance to stop.</p> <p><strong>output</strong>: the value ‘true’.</p> @@ -737,9 +726,9 @@ The runid is an integer.</p> <a name="Method.org.AGL.afm.user.continue"></a> <h4>Method org.AGL.afm.user.continue</h4> -<p><strong>Description</strong>: Continues the application of <em>runid</em> previously stopped.</p> +<p><strong>Description</strong>: Continues the application attached to <em>runid</em> previously stopped.</p> -<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to continue.</p> +<p><strong>Input</strong>: The <em>runid</em> (integer) of the running instance to continue.</p> <p><strong>output</strong>: the value ‘true’.</p> @@ -750,12 +739,11 @@ The runid is an integer.</p> <p><strong>Description</strong>: Get informations about a running instance of <em>runid</em>.</p> -<p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance inspected.</p> +<p><strong>Input</strong>: The <em>runid</em> (integer) of the running instance inspected.</p> -<p><strong>output</strong>: An object describing the state of the instance. It contains: -the runid (an integer), the id of the running application (a string), -the state of the application (a string being either “starting”, “running” -or “stopped”).</p> +<p><strong>output</strong>: An object describing instance state. It contains: +the runid (integer), the id of the running application (string), +the state of the application (string either: “starting”, “running”, “stopped”).</p> <p>Example of returned state:</p> @@ -771,7 +759,7 @@ or “stopped”).</p> <a name="Method.org.AGL.afm.user.runners"></a> <h4>Method org.AGL.afm.user.runners</h4> -<p><strong>Description</strong>: Get the list of the currently running instances.</p> +<p><strong>Description</strong>: Get the list of currently running instances.</p> <p><strong>Input</strong>: anything.</p> diff --git a/doc/afm-user-daemon.md b/doc/afm-user-daemon.md index 590b511..b21c1cd 100644 --- a/doc/afm-user-daemon.md +++ b/doc/afm-user-daemon.md @@ -3,7 +3,7 @@ The afm-user-daemon =================== version: 1 - Date: 29 mai 2016 + Date: 30 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE @@ -11,39 +11,36 @@ TABLE-OF-CONTENT-HERE Foreword -------- -This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ. - -In case of differences, it is assumed that this document is right -and the implementation is wrong. +This document describes application framework user daemon fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications. Introduction ------------ The daemon **afm-user-daemon** is in charge of handling -applications for one user. Its main tasks are: +applications on behalf of a user. Its main tasks are: - - enumerate the applications that the user can run - and keep the list avalable on demand + - enumerate applications that end user can run + and keep this list available on demand - - start applications for the user, set their running - environment, set their security context + - start applications on behalf of end user, set user running + environment, set user security context - - list the current runner applications + - list current runnable or running applications - stop (aka pause), continue (aka resume), terminate - the running instance of application + a running instance of a given application - - transfer requests for installation or uninstallation - of applications to the dedicated system daemon + - transfer requests for installation/uninstallation + of applications to the corresponding system daemon **afm-system-daemon** The **afm-user-daemon** takes its orders from the session instance of D-Bus. -The figure below summarizes the situation of the -**afm-user-daemon** in the system. +The figure below summarizes the situation of **afm-user-daemon** in the system. +------------------------------------------------------------+ | User | @@ -80,37 +77,39 @@ Tasks of **afm-user-daemon** ### Maintaining list of applications ### At start **afm-user-daemon** scans the directories containing -the applications and load in memory the list applications -availables to the current user. +applications and load in memory a list of avaliable applications +accessible by current user. -When **afm-system-daemon** installs or removes an application, -it sends the signal *org.AGL.afm.system.changed* on success. -If it receives that signal, **afm-user-daemon** rebuild its -list of applications. +When **afm-system-daemon** installs or removes an application. +On success it sends the signal *org.AGL.afm.system.changed*. +When receiving such a signal, **afm-user-daemon** rebuilds its +applications list. -**afm-user-daemon** provides the data that it collected about -application to its clients that either want to get that list -or to get information about one application. +**afm-user-daemon** provides the data it collects about +applications to its clients. Clients may either request the full list +of avaliable applications or a more specific information about a +given application. -### Launching applications ### +### Launching application ### -**afm-user-daemon** launchs the applications. This means -that its builds a secure environment for the application -and then start it inside that secured environment. +**afm-user-daemon** launches application. Its builds a secure +environment for the application before starting it within a +secured environment. -Applications of different kind can be launched. +Different kind of applications can be launched. This is set using a configuration file that describes -how to launch an application of a given kind for a given +how to launch an application of a given kind within a given mode. There is two launching modes: local or remote. Launching an application locally means that -the application and its binder are launcher together. +the application and its binder are launched together. -Launching application remotely means that only the -binder is launched for the application. +Launching application remotely translates in only launching +the application binder. The UI by itself has to be activated +remotely by the requested (ie: HTML5 homescreen in a browser) Once launched, running instances of application receive a runid that identify them. @@ -120,14 +119,14 @@ a runid that identify them. **afm-user-daemon** manages the list of applications that it launched. -With the good permissions, a client can get the list -of the running instances and details about a specific -running instance. It can also terminate, stop or -continue a given application. +When owning the right permissions, a client can get the list +of running instances and details about a specific +running instance. It can also terminates, stops or +continues a given application. ### Installing and uninstalling applications ### -If the client has the good permission, +If the client own the right permissions, **afm-user-daemon** delegates that task to **afm-system-daemon**. @@ -150,17 +149,16 @@ The options for launching **afm-user-daemon** are: Can be repeated. -r - --root directory - - Includes the root application directory to - the database base of applications. - - Note that the default root directory for - applications is always added. It is defined - to be /usr/share/afm/applications (may change). - - Can be repeated. + --root directory + Includes root application directory or directories when + passing multiple rootdir to + applications database. + + Note that default root directory for + applications is always added. In current version + /usr/share/afm/applications is used as default. + -m --mode (local|remote) @@ -188,34 +186,34 @@ The options for launching **afm-user-daemon** are: Prints a short help. -Configuration of the launcher +Launcher Configuration ----------------------------- It contains rules for launching applications. -When **afm-user-daemon** need to launch an application, -it looks to the mode of launch, local or remote, and the -type of the application as given by the file ***config.xml*** -of the widget. +When **afm-user-daemon** has to launch an application, +it looks for launch mode (local or remote), as well as +for the type of application describe in ***config.xml*** +widget configuration file. -This couple mode and type allows to select the rule. +This tuple mode+type allows to select the adequate rule. -The configuration file is **/etc/afm/afm-launch.conf**. +Configuration file is **/etc/afm/afm-launch.conf**. It contains sections and rules. It can also contain comments -and empty lines to improve the readability. +and empty lines to improve readability. The separators are space and tabulation, any other character -is meaning something. +should have a meaning. The format is line oriented. The new line character separate the lines. -Lines having only separators are blank lines and are skipped. -Line having the character # (sharp) as first not separator character -are comment lines and are ignored. +Lines having only separators are blank lines and ignored. +Line having character #(sharp) at first position are comment +lines and ignored. -Lines starting with a not separator character are differents -of lines starting with a separator character. +Lines not starting with a separator are different +from lines starting with a separator character. The grammar of the configuration file is defined below: @@ -244,8 +242,8 @@ The grammar of the configuration file is defined below: NCHAR: CMT | CHAR Here is a sample of configuration file for defining how -to launch an application declared of types *application/x-executable*, -*text/x-shellscript* and *text/html* in mode local: +to launch an application of types *application/x-executable*, +*text/x-shellscript* and *text/html* in local mode: mode local @@ -267,9 +265,9 @@ This shows that: ### mode local -Within this mode, the launchers have either one or two vectors -describing them. All of these vectors are treated as programs -and are executed with the system call 'execve'. +Within this mode, the launchers have either one or two description vectors. +All of those vectors are treated as programs +and are executed with 'execve' system call. The first vector is the leader vector and it defines the process group. The second vector (if any) is attached to the group @@ -280,19 +278,17 @@ defined by this first vector. Within this mode, the launchers have either one or two vectors describing them. -The first vector is treated as a program and is executed with -the system call 'execve'. +The first vector is process as a program and is executed with +system call 'execve'. The second vector (if any) defines a text that is returned -to the caller. This mechanism can be used to return the uri -to connect to for executing the application remotely. +to the caller. This mechanism can be used to return a uri +for remote UI to connect on the newly launched application. -The daemon ***afm-user-daemon*** allocates a port for the -running the application remotely. -The current implmentation of the port allocation is just -incremental. -A more reliable (cacheable and same-originable) allocation -is to be defined. +The daemon ***afm-user-daemon*** allocates a port for each +new remote application. +The current implementation port allocation is incremental. +A smarter (cacheable and discoverable) allocation should be defined. ### %substitutions @@ -310,7 +306,7 @@ Here is the list of *%substitutions*: - ***%a***: appid - This is the application Id of the launched application. + Holds application Id of launched application. Defined by the attribute **id** of the element **<widget>** of **config.xml**. @@ -319,11 +315,10 @@ Here is the list of *%substitutions*: The file within the widget directory that is the entry point. - For a HTML application, it is the relative path to the main + For HTML applications, it represents the relative path to main page (aka index.html). - Defined by the attribute **src** of the element **<content>** - of **config.xml**. + Defined by attribute **src** of the element **<content>** within **config.xml**. - ***%D***: datadir @@ -363,9 +358,8 @@ Here is the list of *%substitutions*: - ***%p***: plugins - Unhandled until now. - - Will be the colon separated list of plugins and plugins directory. + In the future should represent the list of plugins and plugins directory separated by ','. + Warning: not supported in current version. - ***%P***: port @@ -374,17 +368,17 @@ Here is the list of *%substitutions*: - ***%R***: readyfd - Number of the file descriptor to use for signalling - readyness of the launched process. + Number of file descriptor to use for signaling + readiness of launched process. - ***%r***: rootdir - Path of the directory containing the widget and its data. + Path of directory containing the widget and its data. - ***%S***: secret - An hexadecimal number that can be used to pair the client - with its server binder. + An hexadecimal number that can be used to initialize pairing of client + and application binder. - ***%W***: width @@ -400,27 +394,25 @@ The D-Bus interface ### Overview of the dbus interface ***afm-user-daemon*** takes its orders from the session instance -of D-Bus. The use of D-Bus is great because it allows to implement +of D-Bus. D-Bus is nice to use in this context because it allows discovery and signaling. -The dbus of the session is by default adressed by the environment +The dbus session is by default addressed by environment variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd** -the variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for +variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for user sessions. -The **afm-user-daemon** is listening with the destination name -***org.AGL.afm.user*** at the object of path ***/org/AGL/afm/user*** -on the interface ***org.AGL.afm.user*** for the below detailed -members ***runnables***, ***detail***, ***start***, ***terminate***, +The **afm-user-daemon** is listening on destination name +***org.AGL.afm.user*** at object path ***/org/AGL/afm/user*** +on interface ***org.AGL.afm.user*** for following members: + ***runnables***, ***detail***, ***start***, ***terminate***, ***stop***, ***continue***, ***runners***, ***state***, ***install*** and ***uninstall***. D-Bus is mainly used for signaling and discovery. Its optimized -typed protocol is not used except for transmitting only one string -in both directions. +typed protocol is not used except for transmission of standalone strings. -The client and the service are using JSON serialisation to -exchange data. +Clients and Services are using JSON serialisation to exchange data. The D-Bus interface is defined by: @@ -433,10 +425,10 @@ The D-Bus interface is defined by: The signature of any member of the interface is ***string -> string*** for ***JSON -> JSON***. -This is the normal case. In case of error, the current implmentation -returns a dbus error that is a string. +This is the normal case. In case of error, the current implementation +returns a dbus error as a string. -Here is an example that use *dbus-send* to query data on +Here an example using *dbus-send* to query data on installed applications. dbus-send --session --print-reply \ @@ -451,8 +443,7 @@ orders to **afm-user-daemon**. This small scripts allows to send command to ***afm-user-daemon*** either interactively at shell prompt or scriptically. -The syntax is simple: it accept a command and if the command -requires it, the argument to the command. +The syntax is simple: it accept a command and when requires attached arguments. Here is the summary of ***afm-util***: @@ -563,12 +554,12 @@ an application as described above for the method **Description**: Install an application from its widget file. If an application of the same *id* and *version* exists, it is not -reinstalled except if *force=true*. +reinstalled except when *force=true*. Applications are installed in the subdirectories of the common directory -of applications. -If *root* is specified, the application is installed under the -sub-directories of the *root* defined. +reserved for applications. +If *root* is specified, the application is installed under +sub-directories of defined *root*. Note that this methods is a simple accessor to the method ***org.AGL.afm.system.install*** of ***afm-system-daemon***. @@ -576,10 +567,10 @@ Note that this methods is a simple accessor to the method After the installation and before returning to the sender, ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. -**Input**: The *path* of the widget file to install and, optionaly, -a flag to *force* reinstallation, and, optionaly, a *root* directory. +**Input**: The *path* of widget file to be installed. Optionally, +a flag to *force* reinstallation and/or a *root* directory. -Either just a string being the absolute path of the widget file: +Simple form a simple string containing the absolute widget path: "/a/path/driving/to/the/widget" @@ -591,10 +582,9 @@ Or an object: "root": "/a/path/to/the/root" } -"wgt" and "root" must be absolute paths. +"wgt" and "root" MUST be absolute paths. -**output**: An object with the field "added" being the string for -the id of the added application. +**output**: An object containing field "added" to use as application ID. {"added":"appli@x.y"} @@ -605,14 +595,14 @@ the id of the added application. **Description**: Uninstall an application from its id. -Note that this methods is a simple accessor to the method -***org.AGL.afm.system.uninstall*** of ***afm-system-daemon***. +Note that this methods is a simple accessor to +***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***. After the uninstallation and before returning to the sender, ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. -**Input**: the *id* of the application and, otpionaly, the path to -*root* of the application. +**Input**: the *id* of the application and, optionally, the path to +application *root*. Either a string: @@ -633,30 +623,29 @@ Or an object: **Description**: -**Input**: the *id* of the application and, optionaly, the +**Input**: the *id* of the application and, optionally, the start *mode* as below. Either just a string: "appli@x.y" -Or an object having the field "id" of type string and -optionaly a field mode: +Or an object containing field "id" of type string and +optionally a field mode: {"id":"appli@x.y","mode":"local"} -The field "mode" as a string value being either "local" or "remote". +The field "mode" is a string equal to either "local" or "remote". -**output**: The *runid* of the application launched. -The runid is an integer. +**output**: The *runid* of the application launched. *runid* is an integer. --- #### Method org.AGL.afm.user.terminate -**Description**: Terminates the application of *runid*. +**Description**: Terminates the application attached to *runid*. -**Input**: The *runid* (an integer) of the running instance to terminate. +**Input**: The *runid* (an integer) of running instance to terminate. **output**: the value 'true'. @@ -664,9 +653,9 @@ The runid is an integer. #### Method org.AGL.afm.user.stop -**Description**: Stops the application of *runid* until terminate or continue. +**Description**: Stops the application attached to *runid* until terminate or continue. -**Input**: The *runid* (an integer) of the running instance to stop. +**Input**: The *runid* (integer) of the running instance to stop. **output**: the value 'true'. @@ -674,9 +663,9 @@ The runid is an integer. #### Method org.AGL.afm.user.continue -**Description**: Continues the application of *runid* previously stopped. +**Description**: Continues the application attached to *runid* previously stopped. -**Input**: The *runid* (an integer) of the running instance to continue. +**Input**: The *runid* (integer) of the running instance to continue. **output**: the value 'true'. @@ -686,12 +675,11 @@ The runid is an integer. **Description**: Get informations about a running instance of *runid*. -**Input**: The *runid* (an integer) of the running instance inspected. +**Input**: The *runid* (integer) of the running instance inspected. -**output**: An object describing the state of the instance. It contains: -the runid (an integer), the id of the running application (a string), -the state of the application (a string being either "starting", "running" -or "stopped"). +**output**: An object describing instance state. It contains: +the runid (integer), the id of the running application (string), +the state of the application (string either: "starting", "running", "stopped"). Example of returned state: @@ -705,7 +693,7 @@ Example of returned state: #### Method org.AGL.afm.user.runners -**Description**: Get the list of the currently running instances. +**Description**: Get the list of currently running instances. **Input**: anything. diff --git a/doc/application-framework.html b/doc/application-framework.html index d2e19c5..e909b77 100644 --- a/doc/application-framework.html +++ b/doc/application-framework.html @@ -8,7 +8,7 @@ <h1>Application framework</h1> <pre><code>version: 1 -Date: 29 mai 2016 +Date: 30 mai 2016 Author: José Bollo </code></pre> @@ -27,13 +27,13 @@ Author: José Bollo </li> </ul> </li> - <li><a href="#Organisation.of.directory.of.applications">Organisation of directory of applications</a> + <li><a href="#organization.of.directory.of.applications">organization of directory of applications</a> <ul> <li><a href="#Identity.of.installed.files">Identity of installed files</a></li> - <li><a href="#Labelling.the.directories.of.applications">Labelling the directories of applications</a></li> + <li><a href="#labeling.the.directories.of.applications">labeling the directories of applications</a></li> </ul> </li> - <li><a href="#Organisation.of.data">Organisation of data</a></li> + <li><a href="#organization.of.data">organization of data</a></li> <li><a href="#Setting.Smack.rules.for.the.application">Setting Smack rules for the application</a></li> <li><a href="#What.user.can.run.an.application.">What user can run an application?</a></li> </ul></p> @@ -41,35 +41,34 @@ Author: José Bollo <a name="Foreword"></a> <h2>Foreword</h2> -<p>This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ.</p> - -<p>In case of differences, it is assumed that this document is right -and the implementation is wrong.</p> +<p>This document describes application framework fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications.</p> <a name="Overview"></a> <h2>Overview</h2> <p>The application framework on top of the security framework -provides the components to install and uninstall applications -and to run it in a secured environment.</p> +provides components to install and uninstall applications +as well as to run them in a secured environment.</p> -<p>The goal is to manage applications and to hide the details of -the security framework to the applications.</p> +<p>The goal of the framework is to manage applications and hide security details +to applications.</p> -<p>For the reasons explained in introduction, we did not used the -application framework of Tizen as is but used an adaptation of it.</p> +<p>For the reasons explained in introduction, it was choose not to reuse Tizen +application framework directly, but to rework a new framework inspired from Tizen.</p> -<p>The basis is kept identical: the applications are distributed -in a digitally signed container that must match the specifications -of widgets (web applications). This is described by the technical -recomendations <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a> of the W3 consortium.</p> +<p>fundamentals remain identical: the applications are distributed +in a digitally signed container that should match widget specifications +normalized by the W3C. This is described by the technical +recommendations <a href="http://www.w3.org/TR/widgets" title="Packaged Web Apps">widgets</a> and <a href="http://www.w3.org/TR/widgets-digsig" title="XML Digital Signatures for Widgets">widgets-digsig</a> of the W3 consortium.</p> -<p>This model allows the distribution of HTML, QML and binary applications.</p> +<p>As today this model allows the distribution of HTML, QML and binary applications +but it could be extended to any other class of applications.</p> -<p>The management of signatures of the widget packages -This basis is not meant as being rigid and it can be extended in the -futur to include for example incremental delivery.</p> +<p>The management of widget package signatures. +Current model is only an initial step, it might be extended in the +future to include new feature (ie: incremental delivery).</p> <a name="Comparison.to.other.frameworks"></a> <h2>Comparison to other frameworks</h2> @@ -83,10 +82,10 @@ futur to include for example incremental delivery.</p> <a name="ostro"></a> <h3>ostro</h3> -<a name="Organisation.of.directory.of.applications"></a> -<h1>Organisation of directory of applications</h1> +<a name="organization.of.directory.of.applications"></a> +<h1>organization of directory of applications</h1> -<p>The main path for applivcations are: APPDIR/PKGID/VER.</p> +<p>The main path for applications are: APPDIR/PKGID/VER.</p> <p>Where:</p> @@ -97,24 +96,24 @@ futur to include for example incremental delivery.</p> </ul> -<p>This organisation has the advantage to allow several versions to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits).</p> +<p>The advantage of such an organization is to allow several versions to live together. +This is required for multiple reasons (ie: roll back) and to comply with developers habits.</p> <a name="Identity.of.installed.files"></a> <h2>Identity of installed files</h2> -<p>All the files are installed as the user “userapp” and group “userapp”. +<p>All the files are installed as user “userapp” and group “userapp”. All files have rw(x) for user and r-(x) for group and others.</p> -<p>This allows any user to read the files.</p> +<p>This allows any user to read files.</p> -<a name="Labelling.the.directories.of.applications"></a> -<h2>Labelling the directories of applications</h2> +<a name="labeling.the.directories.of.applications"></a> +<h2>labeling the directories of applications</h2> -<a name="Organisation.of.data"></a> -<h1>Organisation of data</h1> +<a name="organization.of.data"></a> +<h1>organization of data</h1> -<p>The data of a user are in its directory and are labelled using the labels of the application</p> +<p>The data of a user are contain within its directory and are labeled using the application labels</p> <a name="Setting.Smack.rules.for.the.application"></a> <h1>Setting Smack rules for the application</h1> diff --git a/doc/application-framework.md b/doc/application-framework.md index 278df60..a88dc5b 100644 --- a/doc/application-framework.md +++ b/doc/application-framework.md @@ -3,7 +3,7 @@ Application framework ===================== version: 1 - Date: 29 mai 2016 + Date: 30 mai 2016 Author: José Bollo TABLE-OF-CONTENT-HERE @@ -11,36 +11,34 @@ TABLE-OF-CONTENT-HERE Foreword -------- -This document describes what we intend to do. It may happen that our -current implementation and the content of this document differ. - -In case of differences, it is assumed that this document is right -and the implementation is wrong. - +This document describes application framework fundamentals. +FCF (Fully Conform to Specification) implementation is still under development. +It may happen that current implementation somehow diverges with specifications. Overview -------- The application framework on top of the security framework -provides the components to install and uninstall applications -and to run it in a secured environment. +provides components to install and uninstall applications +as well as to run them in a secured environment. -The goal is to manage applications and to hide the details of -the security framework to the applications. +The goal of the framework is to manage applications and hide security details +to applications. -For the reasons explained in introduction, we did not used the -application framework of Tizen as is but used an adaptation of it. +For the reasons explained in introduction, it was choose not to reuse Tizen +application framework directly, but to rework a new framework inspired from Tizen. -The basis is kept identical: the applications are distributed -in a digitally signed container that must match the specifications -of widgets (web applications). This is described by the technical -recomendations [widgets] and [widgets-digsig] of the W3 consortium. +fundamentals remain identical: the applications are distributed +in a digitally signed container that should match widget specifications +normalized by the W3C. This is described by the technical +recommendations [widgets] and [widgets-digsig] of the W3 consortium. -This model allows the distribution of HTML, QML and binary applications. +As today this model allows the distribution of HTML, QML and binary applications +but it could be extended to any other class of applications. -The management of signatures of the widget packages -This basis is not meant as being rigid and it can be extended in the -futur to include for example incremental delivery. +The management of widget package signatures. +Current model is only an initial step, it might be extended in the +future to include new feature (ie: incremental delivery). Comparison to other frameworks @@ -52,10 +50,10 @@ Comparison to other frameworks ### ostro -Organisation of directory of applications +organization of directory of applications ========================================= -The main path for applivcations are: APPDIR/PKGID/VER. +The main path for applications are: APPDIR/PKGID/VER. Where: @@ -63,26 +61,26 @@ Where: - PKGID is a directory whose name is the package identifier - VER is the version of the package MAJOR.MINOR -This organisation has the advantage to allow several versions to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits). +The advantage of such an organization is to allow several versions to live together. +This is required for multiple reasons (ie: roll back) and to comply with developers habits. Identity of installed files --------------------------- -All the files are installed as the user "userapp" and group "userapp". +All the files are installed as user "userapp" and group "userapp". All files have rw(x) for user and r-(x) for group and others. -This allows any user to read the files. +This allows any user to read files. -Labelling the directories of applications +labeling the directories of applications ----------------------------------------- -Organisation of data +organization of data ==================== -The data of a user are in its directory and are labelled using the labels of the application +The data of a user are contain within its directory and are labeled using the application labels Setting Smack rules for the application ======================================= @@ -115,10 +113,6 @@ Not all user are able to run all applications. How to manage that? - - - - [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" |