14 This document describes application framework user daemon fundamentals.
15 FCF (Fully Conform to Specification) implementation is still under development.
16 It may happen that current implementation somehow diverges with specifications.
22 The daemon **afm-user-daemon** is in charge of handling
23 applications on behalf of a user. Its main tasks are:
25 - enumerate applications that end user can run
26 and keep this list available on demand
28 - start applications on behalf of end user, set user running
29 environment, set user security context
31 - list current runnable or running applications
33 - stop (aka pause), continue (aka resume), terminate
34 a running instance of a given application
36 - transfer requests for installation/uninstallation
37 of applications to the corresponding system daemon
40 The **afm-user-daemon** takes its orders from the session
43 The figure below summarizes the situation of **afm-user-daemon** in the system.
45 +------------------------------------------------------------+
47 | +---------------------+ |
48 | +---------------------+ | Smack isolated | |
49 | | D-Bus session + | APPLICATIONS | |
50 | +----------+----------+ +---------+-----------+ |
53 | +----------+--------------------------+-----------+ |
55 | | afm-user-daemon | |
57 | +----------+----------------------+----------+----+ |
60 :================|======================|==========:=========:
62 | +----------+----------+ +-----+-----+ : |
63 | | D-Bus system +-----+ CYNARA | : |
64 | +----------+----------+ +-----+-----+ : |
66 | +----------+---------+ +-------+----------+----+ |
67 | | afm-system-daemon +----+ SECURITY-MANAGER | |
68 | +--------------------+ +-----------------------+ |
71 +------------------------------------------------------------+
74 Tasks of **afm-user-daemon**
75 ----------------------------
77 ### Maintaining list of applications ###
79 At start **afm-user-daemon** scans the directories containing
80 applications and load in memory a list of avaliable applications
81 accessible by current user.
83 When **afm-system-daemon** installs or removes an application.
84 On success it sends the signal *org.AGL.afm.system.changed*.
85 When receiving such a signal, **afm-user-daemon** rebuilds its
88 **afm-user-daemon** provides the data it collects about
89 applications to its clients. Clients may either request the full list
90 of avaliable applications or a more specific information about a
93 ### Launching application ###
95 **afm-user-daemon** launches application. Its builds a secure
96 environment for the application before starting it within a
99 Different kind of applications can be launched.
101 This is set using a configuration file that describes
102 how to launch an application of a given kind within a given
105 There is two launching modes: local or remote.
107 Launching an application locally means that
108 the application and its binder are launched together.
110 Launching application remotely translates in only launching
111 the application binder. The UI by itself has to be activated
112 remotely by the requested (ie: HTML5 homescreen in a browser)
114 Once launched, running instances of application receive
115 a runid that identify them.
117 ### Managing instances of running applications ###
119 **afm-user-daemon** manages the list of applications
122 When owning the right permissions, a client can get the list
123 of running instances and details about a specific
124 running instance. It can also terminates, stops or
125 continues a given application.
127 ### Installing and uninstalling applications ###
129 If the client own the right permissions,
130 **afm-user-daemon** delegates that task
131 to **afm-system-daemon**.
134 Starting **afm-user-daemon**
135 -----------------------------
137 **afm-user-daemon** is launched as a **systemd** service
138 attached to user sessions. Normally, the service file is
139 located at /usr/lib/systemd/user/afm-user-daemon.service.
141 The options for launching **afm-user-daemon** are:
144 --application directory
146 Includes the given application directory to
147 the database base of applications.
154 Includes root application directory or directories when
155 passing multiple rootdir to
156 applications database.
158 Note that default root directory for
159 applications is always added. In current version
160 /usr/share/afm/applications is used as default.
163 --mode (local|remote)
165 Set the default launch mode.
166 The default value is 'local'
171 Daemonizes the process. It is not needed by sytemd.
176 Reduces the verbosity (can be repeated).
181 Increases the verbosity (can be repeated).
189 Launcher Configuration
190 -----------------------------
192 It contains rules for launching applications.
193 When **afm-user-daemon** has to launch an application,
194 it looks for launch mode (local or remote), as well as
195 for the type of application describe in ***config.xml***
196 widget configuration file.
198 This tuple mode+type allows to select the adequate rule.
200 Configuration file is **/etc/afm/afm-launch.conf**.
202 It contains sections and rules. It can also contain comments
203 and empty lines to improve readability.
205 The separators are space and tabulation, any other character
206 should have a meaning.
208 The format is line oriented.
209 The new line character separate the lines.
211 Lines having only separators are blank lines and ignored.
212 Line having character #(sharp) at first position are comment
215 Lines not starting with a separator are different
216 from lines starting with a separator character.
218 The grammar of the configuration file is defined below:
220 CONF: *COMMENT *SECTION
224 RULE: +TYPE VECTOR ?VECTOR
226 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
230 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
236 COMMENT: *SEP CMT *(SEP | NCHAR) NL
241 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
244 Here is a sample of configuration file for defining how
245 to launch an application of types *application/x-executable*,
246 *text/x-shellscript* and *text/html* in local mode:
250 application/x-executable
255 /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
256 /usr/bin/web-runtime http://localhost:%P/%c?token=%S
260 - within a section, several rules can be defined
261 - within a rule, several types can be defined
262 - within a rule, one or two vectors can be defined
263 - vectors are using %substitution
264 - launched binaries must be defined with their full path
268 Within this mode, the launchers have either one or two description vectors.
269 All of those vectors are treated as programs
270 and are executed with 'execve' system call.
272 The first vector is the leader vector and it defines the process
273 group. The second vector (if any) is attached to the group
274 defined by this first vector.
278 Within this mode, the launchers have either one or two vectors
281 The first vector is process as a program and is executed with
282 system call 'execve'.
284 The second vector (if any) defines a text that is returned
285 to the caller. This mechanism can be used to return a uri
286 for remote UI to connect on the newly launched application.
288 The daemon ***afm-user-daemon*** allocates a port for each
289 new remote application.
290 The current implementation port allocation is incremental.
291 A smarter (cacheable and discoverable) allocation should be defined.
295 Vectors can include sequences of 2 characters that have a special
296 meaning. These sequences are named *%substitution* because their
297 first character is the percent sign (%) and because each occurrence
298 of the sequence is replaced, at launch time, by the value associated
301 Here is the list of *%substitutions*:
305 This simply emits the percent sign %
309 Holds application Id of launched application.
311 Defined by the attribute **id** of the element **<widget>**
316 The file within the widget directory that is the entry point.
318 For HTML applications, it represents the relative path to main
319 page (aka index.html).
321 Defined by attribute **src** of the element **<content>** within **config.xml**.
325 Path of the directory where the application runs (cwd)
328 It is equal to %h/%a.
332 Requested height for the widget.
334 Defined by the attribute **height** of the element **<widget>**
339 Path of the home directory for all applications.
341 It is generally equal to $HOME/app-data
345 Path of the directory were the icons of the applications can be found.
347 - ***%m***: mime-type
349 Mime type of the launched application.
351 Defined by the attribute **type** of the element **<content>**
356 Name of the application as defined by the content of the
357 element **<name>** of **config.xml**.
361 In the future should represent the list of plugins and plugins directory separated by ','.
362 Warning: not supported in current version.
366 A port to use. It is currently a kind of random port. The precise
367 model is to be defined later.
371 Number of file descriptor to use for signaling
372 readiness of launched process.
376 Path of directory containing the widget and its data.
380 An hexadecimal number that can be used to initialize pairing of client
381 and application binder.
385 Requested width for the widget.
387 Defined by the attribute **width** of the element **<widget>**
394 ### Overview of the dbus interface
396 ***afm-user-daemon*** takes its orders from the session instance
397 of D-Bus. D-Bus is nice to use in this context because it allows
398 discovery and signaling.
400 The dbus session is by default addressed by environment
401 variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd**
402 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
405 The **afm-user-daemon** is listening on destination name
406 ***org.AGL.afm.user*** at object path ***/org/AGL/afm/user***
407 on interface ***org.AGL.afm.user*** for following members:
408 ***runnables***, ***detail***, ***start***, ***terminate***,
409 ***stop***, ***continue***, ***runners***, ***state***,
410 ***install*** and ***uninstall***.
412 D-Bus is mainly used for signaling and discovery. Its optimized
413 typed protocol is not used except for transmission of standalone strings.
415 Clients and Services are using JSON serialisation to exchange data.
417 The D-Bus interface is defined by:
419 * DESTINATION: **org.AGL.afm.user**
421 * PATH: **/org/AGL/afm/user**
423 * INTERFACE: **org.AGL.afm.user**
425 The signature of any member of the interface is ***string -> string***
426 for ***JSON -> JSON***.
428 This is the normal case. In case of error, the current implementation
429 returns a dbus error as a string.
431 Here an example using *dbus-send* to query data on
432 installed applications.
434 dbus-send --session --print-reply \
435 --dest=org.AGL.afm.user \
437 org.AGL.afm.user.runnables string:true
439 ### Using ***afm-util***
441 The command line tool ***afm-util*** uses dbus-send to send
442 orders to **afm-user-daemon**. This small scripts allows to
443 send command to ***afm-user-daemon*** either interactively
444 at shell prompt or scriptically.
446 The syntax is simple: it accept a command and when requires attached arguments.
448 Here is the summary of ***afm-util***:
450 - **afm-util runnables **:
452 list the runnable widgets installed
454 - **afm-util install wgt **:
458 - **afm-util uninstall id **:
460 remove the installed widget of id
462 - **afm-util detail id **:
464 print detail about the installed widget of id
466 - **afm-util runners **:
468 list the running instance
470 - **afm-util start id **:
472 start an instance of the widget of id
474 - **afm-util terminate rid **:
476 terminate the running instance rid
478 - **afm-util stop rid **:
480 stop the running instance rid
482 - **afm-util continue rid **:
484 continue the previously rid
486 - **afm-util state rid **:
488 get status of the running instance rid
491 Here is how to list applications using ***afm-util***:
497 ### The protocol over D-Bus
501 * **DESTINATION**: org.AGL.afm.user
503 * **PATH**: /org/AGL/afm/user
505 * **INTERFACE**: org.AGL.afm.user
509 #### Method org.AGL.afm.user.detail
511 **Description**: Get details about an application from its id.
513 **Input**: the id of the application as below.
515 Either just a string:
519 Or an object having the field "id" of type string:
523 **Output**: A JSON object describing the application containing
524 the fields described below.
527 "id": string, the application id (id@version)
528 "version": string, the version of the application
529 "width": integer, requested width of the application
530 "height": integer, resqueted height of the application
531 "name": string, the name of the application
532 "description": string, the description of the application
533 "shortname": string, the short name of the application
534 "author": string, the author of the application
539 #### Method org.AGL.afm.user.runnables
541 **Description**: Get the list of applications that can be run.
543 **Input**: any valid json entry, can be anything except null.
545 **output**: An array of description of the runnable applications.
546 Each item of the array contains an object containing the detail of
547 an application as described above for the method
548 *org.AGL.afm.user.detail*.
552 #### Method org.AGL.afm.user.install
554 **Description**: Install an application from its widget file.
556 If an application of the same *id* and *version* exists, it is not
557 reinstalled except when *force=true*.
559 Applications are installed in the subdirectories of the common directory
560 reserved for applications.
561 If *root* is specified, the application is installed under
562 sub-directories of defined *root*.
564 Note that this methods is a simple accessor to the method
565 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
567 After the installation and before returning to the sender,
568 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
570 **Input**: The *path* of widget file to be installed. Optionally,
571 a flag to *force* reinstallation and/or a *root* directory.
573 Simple form a simple string containing the absolute widget path:
575 "/a/path/driving/to/the/widget"
580 "wgt": "/a/path/to/the/widget",
582 "root": "/a/path/to/the/root"
585 "wgt" and "root" MUST be absolute paths.
587 **output**: An object containing field "added" to use as application ID.
589 {"added":"appli@x.y"}
593 #### Method org.AGL.afm.user.uninstall
595 **Description**: Uninstall an application from its id.
598 Note that this methods is a simple accessor to
599 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
601 After the uninstallation and before returning to the sender,
602 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
604 **Input**: the *id* of the application and, optionally, the path to
615 "root": "/a/path/to/the/root"
618 **output**: the value 'true'.
622 #### Method org.AGL.afm.user.start
626 **Input**: the *id* of the application and, optionally, the
627 start *mode* as below.
629 Either just a string:
633 Or an object containing field "id" of type string and
634 optionally a field mode:
636 {"id":"appli@x.y","mode":"local"}
638 The field "mode" is a string equal to either "local" or "remote".
640 **output**: The *runid* of the application launched. *runid* is an integer.
644 #### Method org.AGL.afm.user.terminate
646 **Description**: Terminates the application attached to *runid*.
648 **Input**: The *runid* (an integer) of running instance to terminate.
650 **output**: the value 'true'.
654 #### Method org.AGL.afm.user.stop
656 **Description**: Stops the application attached to *runid* until terminate or continue.
658 **Input**: The *runid* (integer) of the running instance to stop.
660 **output**: the value 'true'.
664 #### Method org.AGL.afm.user.continue
666 **Description**: Continues the application attached to *runid* previously stopped.
668 **Input**: The *runid* (integer) of the running instance to continue.
670 **output**: the value 'true'.
674 #### Method org.AGL.afm.user.state
676 **Description**: Get informations about a running instance of *runid*.
678 **Input**: The *runid* (integer) of the running instance inspected.
680 **output**: An object describing instance state. It contains:
681 the runid (integer), the id of the running application (string),
682 the state of the application (string either: "starting", "running", "stopped").
684 Example of returned state:
694 #### Method org.AGL.afm.user.runners
696 **Description**: Get the list of currently running instances.
700 **output**: An array of states, one per running instance, as returned by
701 the methodd ***org.AGL.afm.user.state***.