1 The application framework daemons
2 =================================
7 This document describes application framework daemons
8 FCF (Fully Conform to Specification) implementation is still under development.
9 It may happen that current implementation somehow diverges with specifications.
14 Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications
15 life. Understand that they will manage operations like:
18 - ***uninstallation***
24 In addition, they ensure that operations use the security framework as needed
25 and that applications are executed in the correct context.
27 ***D-Bus*** is in charge of transmitting orders to the appropriate daemon
28 depending upon ***D-Bus*** destination.
30 The figure below summarizes the situation of both **afm-system-daemon** and
31 **afm-user-daemon** in the system.
33 ![afm-daemons][afm-daemons]
38 ### Overview of the dbus interface
40 The ***afm daemons*** takes theirs orders from the session instance
41 of D-Bus. The use of D-Bus is great because it allows to implement
42 discovery and signaling.
44 The dbus session is by default addressed by environment
45 variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd**
46 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
49 They are listening with the destination name ***org.AGL.afm.[user|system]***
50 at the object of path ***/org/AGL/afm/[user|system]*** on the interface
51 ***org.AGL.afm.[user|system]*** for the below detailed members for the
52 ***afm-system-daemon***:
57 And for ***afm-user-daemon***:
71 D-Bus is mainly used for signaling and discovery. Its optimized
72 typed protocol is not used except for transmitting only one string
75 The client and the service are using JSON serialization to
76 exchange data. Signature of any member of the D-Bus interface is
77 ***string -> string*** for ***JSON -> JSON***. This is the normal case, if there
78 is an error, current implementation returns a dbus error that is a string.
80 Here are examples using *dbus-send*, here to install an application from a
83 dbus-send --session --print-reply \
84 --dest=org.AGL.afm.system \
86 org.AGL.afm.system.install 'string:"/tmp/appli.wgt"
89 And here, to query data on installed applications that can be run:
91 dbus-send --session --print-reply \
92 --dest=org.AGL.afm.user \
94 org.AGL.afm.user.runnables string:true
96 ### The protocol over D-Bus
98 On all following sub-chapters we assume that we talk about either
99 ***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters
100 are considered as self-explanatory.
102 The D-Bus interface is defined by:
104 * **DESTINATION**: org.AGL.afm.[user|system]
106 * **PATH**: /org/AGL/afm/[user|system]
108 * **INTERFACE**: org.AGL.afm.[user|system]
110 #### Method org.AGL.afm.system.install
112 **Description**: Install an application from a widget file.
114 When an application with the same *id* and *version* already exists. Outside of
115 using *force=true* the application is not reinstalled.
117 Applications are installed the subdirectories of applications common directory.
118 If *root* is specified, the application is installed under the
119 sub-directories of the *root* defined.
121 Note that this methods is a simple accessor method of
122 ***org.AGL.afm.system.install*** from ***afm-system-daemon***.
124 After the installation and before returning to the sender,
125 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
127 **Input**: The *path* of the widget file to install and, optionally,
128 a flag to *force* reinstallation, and, optionally, a *root* directory.
130 Either just a string being the absolute path of the widget file:
132 "/a/path/driving/to/the/widget"
137 "wgt": "/a/path/to/the/widget",
139 "root": "/a/path/to/the/root"
142 "wgt" and "root" must be absolute paths.
144 **output**: An object with the field "added" being the string for
145 the id of the added application.
147 {"added":"appli@x.y"}
151 #### Method org.AGL.afm.system.uninstall
153 **Description**: Uninstall an application from its id.
156 Note that this methods is a simple method accessor of
157 ***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***.
159 After the uninstallation and before returning to the sender,
160 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
162 **Input**: the *id* of the application and optionally the application *root* path.
172 "root": "/a/path/to/the/root"
175 **output**: the value 'true'.
179 #### Method org.AGL.afm.user.detail
182 **Description**: Get details about an application from its id.
184 **Input**: the id of the application as below.
186 Either just a string:
190 Or an object having the field "id" of type string:
194 **Output**: A JSON object describing the application containing
195 the fields described below.
198 "id": string, the application id (id@version)
199 "version": string, the version of the application
200 "width": integer, requested width of the application
201 "height": integer, resqueted height of the application
202 "name": string, the name of the application
203 "description": string, the description of the application
204 "shortname": string, the short name of the application
205 "author": string, the author of the application
210 #### Method org.AGL.afm.user.runnables
212 **Description**: Get the list of applications that can be run.
214 **Input**: any valid json entry, can be anything except null.
216 **output**: An array of description of the runnable applications.
217 Each item of the array contains an object containing the detail of
218 an application as described above for the method
219 *org.AGL.afm.user.detail*.
223 #### Method org.AGL.afm.user.install
225 **Description**: Install an application from its widget file.
227 If an application of the same *id* and *version* exists, it is not
228 reinstalled except when *force=true*.
230 Applications are installed in the subdirectories of the common directory
231 reserved for applications.
232 If *root* is specified, the application is installed under
233 sub-directories of defined *root*.
235 Note that this methods is a simple accessor to the method
236 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
238 After the installation and before returning to the sender,
239 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
241 **Input**: The *path* of widget file to be installed. Optionally,
242 a flag to *force* reinstallation and/or a *root* directory.
244 Simple form a simple string containing the absolute widget path:
246 "/a/path/driving/to/the/widget"
251 "wgt": "/a/path/to/the/widget",
253 "root": "/a/path/to/the/root"
256 ***wgt*** and ***root*** MUST be absolute paths.
258 **output**: An object containing field "added" to use as application ID.
260 {"added":"appli@x.y"}
264 #### Method org.AGL.afm.user.uninstall
266 **Description**: Uninstall an application from its id.
269 Note that this methods is a simple accessor to
270 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
272 After the uninstallation and before returning to the sender,
273 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
275 **Input**: the *id* of the application and, optionally, the path to
286 "root": "/a/path/to/the/root"
289 **output**: the value 'true'.
293 #### Method org.AGL.afm.user.start
297 **Input**: the *id* of the application and, optionally, the
298 start *mode* as below.
300 Either just a string:
304 Or an object containing field "id" of type string and
305 optionally a field mode:
307 {"id":"appli@x.y","mode":"local"}
309 The field "mode" is a string equal to either "local" or "remote".
311 **output**: The *runid* of the application launched. *runid* is an integer.
315 #### Method org.AGL.afm.user.once
319 **Input**: the *id* of the application
321 Either just a string:
325 Or an object containing field "id" of type string.
329 **output**: The *state* of the application retrieved or launched.
330 See *org.AGL.afm.user.state* to get a description of the returned
335 #### Method org.AGL.afm.user.terminate
337 **Description**: Terminates the application attached to *runid*.
339 **Input**: The *runid* (an integer) of running instance to terminate.
341 **output**: the value 'true'.
345 #### Method org.AGL.afm.user.stop
347 Obsolete since 8th November 2016 (2016/11/08).
348 Kept for compatibility.
350 Use **org.AGL.afm.user.pause** instead.
354 #### Method org.AGL.afm.user.continue
356 Obsolete since 8th November 2016 (2016/11/08).
357 Kept for compatibility.
359 Use **org.AGL.afm.user.resume** instead.
363 #### Method org.AGL.afm.user.pause
365 **Description**: Pauses the application attached to *runid* until terminate or resume.
367 **Input**: The *runid* (integer) of the running instance to pause.
369 **output**: the value 'true'.
373 #### Method org.AGL.afm.user.resume
375 **Description**: Resumes the application attached to *runid* previously paused.
377 **Input**: The *runid* (integer) of the running instance to resume.
379 **output**: the value 'true'.
383 #### Method org.AGL.afm.user.state
385 **Description**: Get informations about a running instance of *runid*.
387 **Input**: The *runid* (integer) of the running instance inspected.
389 **output**: An object describing instance state. It contains:
390 the runid (integer), the pids of the processes as an array starting
391 with the group leader, the id of the running application (string),
392 the state of the application (string either: "starting", "running", "paused").
394 Example of returned state:
398 "pids": [ 435, 436 ],
405 #### Method org.AGL.afm.user.runners
407 **Description**: Get the list of currently running instances.
411 **output**: An array of states, one per running instance, as returned by
412 the method ***org.AGL.afm.user.state***.
414 Starting **afm daemons**
415 ----------------------
417 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
418 services attached to system and user respectively. Normally, service files are
419 locatedat */lib/systemd/system/afm-system-daemon.service* and
420 */lib/systemd/user/afm-user-daemon.service*.
422 ### ***afm-system-daemon*** options
424 The options for launching **afm-system-daemon** are:
429 Set the root application directory.
431 Note that the default root directory is defined
432 to be /usr/share/afm/applications (may change).
437 Daemonizes the process. It is not needed by sytemd.
442 Reduces the verbosity (can be repeated).
447 Increases the verbosity (can be repeated).
454 ### ***afm-user-daemon*** options
456 The options for launching **afm-user-daemon** are:
459 --application directory
461 Includes the given application directory to
462 the database base of applications.
469 Includes root application directory or directories when
470 passing multiple rootdir to
471 applications database.
473 Note that default root directory for
474 applications is always added. In current version
475 /usr/share/afm/applications is used as default.
478 --mode (local|remote)
480 Set the default launch mode.
481 The default value is 'local'
486 Daemonizes the process. It is not needed by sytemd.
491 Reduces the verbosity (can be repeated).
496 Increases the verbosity (can be repeated).
503 Tasks of **afm-user-daemon**
504 ----------------------------
506 ### Maintaining list of applications
508 At start **afm-user-daemon** scans the directories containing
509 applications and load in memory a list of avaliable applications
510 accessible by current user.
512 When **afm-system-daemon** installs or removes an application.
513 On success it sends the signal *org.AGL.afm.system.changed*.
514 When receiving such a signal, **afm-user-daemon** rebuilds its
517 **afm-user-daemon** provides the data it collects about
518 applications to its clients. Clients may either request the full list
519 of avaliable applications or a more specific information about a
522 ### Launching application
524 **afm-user-daemon** launches application. Its builds a secure
525 environment for the application before starting it within a
528 Different kind of applications can be launched.
530 This is set using a configuration file that describes
531 how to launch an application of a given kind within a given
534 There is two launching modes: local or remote.
536 Launching an application locally means that
537 the application and its binder are launched together.
539 Launching application remotely translates in only launching
540 the application binder. The UI by itself has to be activated
541 remotely by the requested (ie: HTML5 homescreen in a browser)
543 Once launched, running instances of application receive
544 a runid that identify them.
546 ### Managing instances of running applications
548 **afm-user-daemon** manages the list of applications
551 When owning the right permissions, a client can get the list
552 of running instances and details about a specific
553 running instance. It can also terminate, pause or
554 resume a given application.
556 ### Installing and uninstalling applications
558 If the client own the right permissions,
559 **afm-user-daemon** delegates that task
560 to **afm-system-daemon**.
562 Launcher Configuration
563 ----------------------
565 It contains rules for launching applications.
566 When **afm-user-daemon** has to launch an application,
567 it looks for launch mode (local or remote), as well as
568 for the type of application describe in ***config.xml***
569 widget configuration file.
571 This tuple mode+type allows to select the adequate rule.
573 Configuration file is **/etc/afm/afm-launch.conf**.
575 It contains sections and rules. It can also contain comments
576 and empty lines to improve readability.
578 The separators are space and tabulation, any other character
579 should have a meaning.
581 The format is line oriented.
582 The new line character separate the lines.
584 Lines having only separators are blank lines and ignored.
585 Line having character #(sharp) at first position are comment
588 Lines not starting with a separator are different
589 from lines starting with a separator character.
591 The grammar of the configuration file is defined below:
593 CONF: *COMMENT *SECTION
597 RULE: +TYPE VECTOR ?VECTOR
599 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
603 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
609 COMMENT: *SEP CMT *(SEP | NCHAR) NL
614 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
617 Here is a sample of configuration file for defining how
618 to launch an application of types *application/x-executable*,
619 *text/x-shellscript* and *text/html* in local mode:
623 application/x-executable
628 /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
629 /usr/bin/web-runtime http://localhost:%P/%c?token=%S
633 - within a section, several rules can be defined
634 - within a rule, several types can be defined
635 - within a rule, one or two vectors can be defined
636 - vectors are using %substitution
637 - launched binaries must be defined with their full path
641 Within this mode, the launchers have either one or two description vectors.
642 All of those vectors are treated as programs
643 and are executed with 'execve' system call.
645 The first vector is the leader vector and it defines the process
646 group. The second vector (if any) is attached to the group
647 defined by this first vector.
651 Within this mode, the launchers have either one or two vectors
654 The first vector is process as a program and is executed with
655 system call 'execve'.
657 The second vector (if any) defines a text that is returned
658 to the caller. This mechanism can be used to return a uri
659 for remote UI to connect on the newly launched application.
661 The daemon ***afm-user-daemon*** allocates a port for each
662 new remote application.
663 The current implementation port allocation is incremental.
664 A smarter (cacheable and discoverable) allocation should be defined.
668 Vectors can include sequences of 2 characters that have a special
669 meaning. These sequences are named *%substitution* because their
670 first character is the percent sign (%) and because each occurrence
671 of the sequence is replaced, at launch time, by the value associated
674 Here is the list of *%substitutions*:
678 This simply emits the percent sign %
682 Holds application Id of launched application.
684 Defined by the attribute **id** of the element **<widget>**
689 In the future should represent the list of bindings and bindings directory separated by ','.
690 Warning: not supported in current version.
694 The file within the widget directory that is the entry point.
696 For HTML applications, it represents the relative path to main
697 page (aka index.html).
699 Defined by attribute **src** of the element **<content>** within **config.xml**.
703 Path of the directory where the application runs (cwd)
706 It is equal to %h/%a.
710 Requested height for the widget.
712 Defined by the attribute **height** of the element **<widget>**
717 Path of the home directory for all applications.
719 It is generally equal to $HOME/app-data
723 Path of the directory were the icons of the applications can be found.
725 - ***%m***: mime-type
727 Mime type of the launched application.
729 Defined by the attribute **type** of the element **<content>**
734 Name of the application as defined by the content of the
735 element **<name>** of **config.xml**.
739 A port to use. It is currently a kind of random port. The precise
740 model is to be defined later.
744 Number of file descriptor to use for signaling
745 readiness of launched process.
749 Path of directory containing the widget and its data.
753 An hexadecimal number that can be used to initialize pairing of client
754 and application binder.
758 Requested width for the widget.
760 Defined by the attribute **width** of the element **<widget>**
766 The command line tool ***afm-util*** uses dbus-send to send
767 orders to **afm-user-daemon**. This small scripts allows to
768 send command to ***afm-user-daemon*** either interactively
769 at shell prompt or scriptically.
771 The syntax is simple: it accept a command and when requires attached arguments.
773 Here is the summary of ***afm-util***:
775 - **afm-util runnables **:
777 list the runnable widgets installed
779 - **afm-util install wgt **:
783 - **afm-util uninstall id **:
785 remove the installed widget of id
787 - **afm-util detail id **:
789 print detail about the installed widget of id
791 - **afm-util runners **:
793 list the running instance
795 - **afm-util start id **:
797 start an instance of the widget of id
799 - **afm-util once id **:
801 run once an instance of the widget of id
803 - **afm-util terminate rid **:
805 terminate the running instance rid
807 - **afm-util pause rid **:
809 pause the running instance rid
811 - **afm-util resume rid **:
813 resume the previously paused rid
815 - **afm-util state rid **:
817 get status of the running instance rid
820 Here is how to list applications using ***afm-util***:
825 [afm-daemons]: pictures/afm-daemons.svg