8 This document describes application framework user daemon fundamentals.
9 FCF (Fully Conform to Specification) implementation is still under development.
10 It may happen that current implementation somehow diverges with specifications.
16 The daemon **afm-user-daemon** is in charge of handling
17 applications on behalf of a user. Its main tasks are:
19 - enumerate applications that end user can run
20 and keep this list available on demand
22 - start applications on behalf of end user, set user running
23 environment, set user security context
25 - list current runnable or running applications
27 - stop (aka pause), continue (aka resume), terminate
28 a running instance of a given application
30 - transfer requests for installation/uninstallation
31 of applications to the corresponding system daemon
34 The **afm-user-daemon** takes its orders from the session
37 The figure below summarizes the situation of **afm-user-daemon** in the system.
39 +------------------------------------------------------------+
41 | +---------------------+ |
42 | +---------------------+ | Smack isolated | |
43 | | D-Bus session + | APPLICATIONS | |
44 | +----------+----------+ +---------+-----------+ |
47 | +----------+--------------------------+-----------+ |
49 | | afm-user-daemon | |
51 | +----------+----------------------+----------+----+ |
54 :================|======================|==========:=========:
56 | +----------+----------+ +-----+-----+ : |
57 | | D-Bus system +-----+ CYNARA | : |
58 | +----------+----------+ +-----+-----+ : |
60 | +----------+---------+ +-------+----------+----+ |
61 | | afm-system-daemon +----+ SECURITY-MANAGER | |
62 | +--------------------+ +-----------------------+ |
65 +------------------------------------------------------------+
68 Tasks of **afm-user-daemon**
69 ----------------------------
71 ### Maintaining list of applications ###
73 At start **afm-user-daemon** scans the directories containing
74 applications and load in memory a list of avaliable applications
75 accessible by current user.
77 When **afm-system-daemon** installs or removes an application.
78 On success it sends the signal *org.AGL.afm.system.changed*.
79 When receiving such a signal, **afm-user-daemon** rebuilds its
82 **afm-user-daemon** provides the data it collects about
83 applications to its clients. Clients may either request the full list
84 of avaliable applications or a more specific information about a
87 ### Launching application ###
89 **afm-user-daemon** launches application. Its builds a secure
90 environment for the application before starting it within a
93 Different kind of applications can be launched.
95 This is set using a configuration file that describes
96 how to launch an application of a given kind within a given
99 There is two launching modes: local or remote.
101 Launching an application locally means that
102 the application and its binder are launched together.
104 Launching application remotely translates in only launching
105 the application binder. The UI by itself has to be activated
106 remotely by the requested (ie: HTML5 homescreen in a browser)
108 Once launched, running instances of application receive
109 a runid that identify them.
111 ### Managing instances of running applications ###
113 **afm-user-daemon** manages the list of applications
116 When owning the right permissions, a client can get the list
117 of running instances and details about a specific
118 running instance. It can also terminates, stops or
119 continues a given application.
121 ### Installing and uninstalling applications ###
123 If the client own the right permissions,
124 **afm-user-daemon** delegates that task
125 to **afm-system-daemon**.
128 Starting **afm-user-daemon**
129 -----------------------------
131 **afm-user-daemon** is launched as a **systemd** service
132 attached to user sessions. Normally, the service file is
133 located at /usr/lib/systemd/user/afm-user-daemon.service.
135 The options for launching **afm-user-daemon** are:
138 --application directory
140 Includes the given application directory to
141 the database base of applications.
148 Includes root application directory or directories when
149 passing multiple rootdir to
150 applications database.
152 Note that default root directory for
153 applications is always added. In current version
154 /usr/share/afm/applications is used as default.
157 --mode (local|remote)
159 Set the default launch mode.
160 The default value is 'local'
165 Daemonizes the process. It is not needed by sytemd.
170 Reduces the verbosity (can be repeated).
175 Increases the verbosity (can be repeated).
183 Launcher Configuration
184 -----------------------------
186 It contains rules for launching applications.
187 When **afm-user-daemon** has to launch an application,
188 it looks for launch mode (local or remote), as well as
189 for the type of application describe in ***config.xml***
190 widget configuration file.
192 This tuple mode+type allows to select the adequate rule.
194 Configuration file is **/etc/afm/afm-launch.conf**.
196 It contains sections and rules. It can also contain comments
197 and empty lines to improve readability.
199 The separators are space and tabulation, any other character
200 should have a meaning.
202 The format is line oriented.
203 The new line character separate the lines.
205 Lines having only separators are blank lines and ignored.
206 Line having character #(sharp) at first position are comment
209 Lines not starting with a separator are different
210 from lines starting with a separator character.
212 The grammar of the configuration file is defined below:
214 CONF: *COMMENT *SECTION
218 RULE: +TYPE VECTOR ?VECTOR
220 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
224 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
230 COMMENT: *SEP CMT *(SEP | NCHAR) NL
235 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
238 Here is a sample of configuration file for defining how
239 to launch an application of types *application/x-executable*,
240 *text/x-shellscript* and *text/html* in local mode:
244 application/x-executable
249 /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
250 /usr/bin/web-runtime http://localhost:%P/%c?token=%S
254 - within a section, several rules can be defined
255 - within a rule, several types can be defined
256 - within a rule, one or two vectors can be defined
257 - vectors are using %substitution
258 - launched binaries must be defined with their full path
262 Within this mode, the launchers have either one or two description vectors.
263 All of those vectors are treated as programs
264 and are executed with 'execve' system call.
266 The first vector is the leader vector and it defines the process
267 group. The second vector (if any) is attached to the group
268 defined by this first vector.
272 Within this mode, the launchers have either one or two vectors
275 The first vector is process as a program and is executed with
276 system call 'execve'.
278 The second vector (if any) defines a text that is returned
279 to the caller. This mechanism can be used to return a uri
280 for remote UI to connect on the newly launched application.
282 The daemon ***afm-user-daemon*** allocates a port for each
283 new remote application.
284 The current implementation port allocation is incremental.
285 A smarter (cacheable and discoverable) allocation should be defined.
289 Vectors can include sequences of 2 characters that have a special
290 meaning. These sequences are named *%substitution* because their
291 first character is the percent sign (%) and because each occurrence
292 of the sequence is replaced, at launch time, by the value associated
295 Here is the list of *%substitutions*:
299 This simply emits the percent sign %
303 Holds application Id of launched application.
305 Defined by the attribute **id** of the element **<widget>**
310 In the future should represent the list of bindings and bindings directory separated by ','.
311 Warning: not supported in current version.
315 The file within the widget directory that is the entry point.
317 For HTML applications, it represents the relative path to main
318 page (aka index.html).
320 Defined by attribute **src** of the element **<content>** within **config.xml**.
324 Path of the directory where the application runs (cwd)
327 It is equal to %h/%a.
331 Requested height for the widget.
333 Defined by the attribute **height** of the element **<widget>**
338 Path of the home directory for all applications.
340 It is generally equal to $HOME/app-data
344 Path of the directory were the icons of the applications can be found.
346 - ***%m***: mime-type
348 Mime type of the launched application.
350 Defined by the attribute **type** of the element **<content>**
355 Name of the application as defined by the content of the
356 element **<name>** of **config.xml**.
360 A port to use. It is currently a kind of random port. The precise
361 model is to be defined later.
365 Number of file descriptor to use for signaling
366 readiness of launched process.
370 Path of directory containing the widget and its data.
374 An hexadecimal number that can be used to initialize pairing of client
375 and application binder.
379 Requested width for the widget.
381 Defined by the attribute **width** of the element **<widget>**
388 ### Overview of the dbus interface
390 ***afm-user-daemon*** takes its orders from the session instance
391 of D-Bus. D-Bus is nice to use in this context because it allows
392 discovery and signaling.
394 The dbus session is by default addressed by environment
395 variable ***DBUS_SESSION_BUS_ADDRESS***. Using **systemd**
396 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
399 The **afm-user-daemon** is listening on destination name
400 ***org.AGL.afm.user*** at object path ***/org/AGL/afm/user***
401 on interface ***org.AGL.afm.user*** for following members:
402 ***runnables***, ***detail***, ***start***, ***terminate***,
403 ***stop***, ***continue***, ***runners***, ***state***,
404 ***install*** and ***uninstall***.
406 D-Bus is mainly used for signaling and discovery. Its optimized
407 typed protocol is not used except for transmission of standalone strings.
409 Clients and Services are using JSON serialisation to exchange data.
411 The D-Bus interface is defined by:
413 * DESTINATION: **org.AGL.afm.user**
415 * PATH: **/org/AGL/afm/user**
417 * INTERFACE: **org.AGL.afm.user**
419 The signature of any member of the interface is ***string -> string***
420 for ***JSON -> JSON***.
422 This is the normal case. In case of error, the current implementation
423 returns a dbus error as a string.
425 Here an example using *dbus-send* to query data on
426 installed applications.
428 dbus-send --session --print-reply \
429 --dest=org.AGL.afm.user \
431 org.AGL.afm.user.runnables string:true
433 ### Using ***afm-util***
435 The command line tool ***afm-util*** uses dbus-send to send
436 orders to **afm-user-daemon**. This small scripts allows to
437 send command to ***afm-user-daemon*** either interactively
438 at shell prompt or scriptically.
440 The syntax is simple: it accept a command and when requires attached arguments.
442 Here is the summary of ***afm-util***:
444 - **afm-util runnables **:
446 list the runnable widgets installed
448 - **afm-util install wgt **:
452 - **afm-util uninstall id **:
454 remove the installed widget of id
456 - **afm-util detail id **:
458 print detail about the installed widget of id
460 - **afm-util runners **:
462 list the running instance
464 - **afm-util start id **:
466 start an instance of the widget of id
468 - **afm-util terminate rid **:
470 terminate the running instance rid
472 - **afm-util stop rid **:
474 stop the running instance rid
476 - **afm-util continue rid **:
478 continue the previously rid
480 - **afm-util state rid **:
482 get status of the running instance rid
485 Here is how to list applications using ***afm-util***:
491 ### The protocol over D-Bus
495 * **DESTINATION**: org.AGL.afm.user
497 * **PATH**: /org/AGL/afm/user
499 * **INTERFACE**: org.AGL.afm.user
503 #### Method org.AGL.afm.user.detail
505 **Description**: Get details about an application from its id.
507 **Input**: the id of the application as below.
509 Either just a string:
513 Or an object having the field "id" of type string:
517 **Output**: A JSON object describing the application containing
518 the fields described below.
521 "id": string, the application id (id@version)
522 "version": string, the version of the application
523 "width": integer, requested width of the application
524 "height": integer, resqueted height of the application
525 "name": string, the name of the application
526 "description": string, the description of the application
527 "shortname": string, the short name of the application
528 "author": string, the author of the application
533 #### Method org.AGL.afm.user.runnables
535 **Description**: Get the list of applications that can be run.
537 **Input**: any valid json entry, can be anything except null.
539 **output**: An array of description of the runnable applications.
540 Each item of the array contains an object containing the detail of
541 an application as described above for the method
542 *org.AGL.afm.user.detail*.
546 #### Method org.AGL.afm.user.install
548 **Description**: Install an application from its widget file.
550 If an application of the same *id* and *version* exists, it is not
551 reinstalled except when *force=true*.
553 Applications are installed in the subdirectories of the common directory
554 reserved for applications.
555 If *root* is specified, the application is installed under
556 sub-directories of defined *root*.
558 Note that this methods is a simple accessor to the method
559 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
561 After the installation and before returning to the sender,
562 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
564 **Input**: The *path* of widget file to be installed. Optionally,
565 a flag to *force* reinstallation and/or a *root* directory.
567 Simple form a simple string containing the absolute widget path:
569 "/a/path/driving/to/the/widget"
574 "wgt": "/a/path/to/the/widget",
576 "root": "/a/path/to/the/root"
579 "wgt" and "root" MUST be absolute paths.
581 **output**: An object containing field "added" to use as application ID.
583 {"added":"appli@x.y"}
587 #### Method org.AGL.afm.user.uninstall
589 **Description**: Uninstall an application from its id.
592 Note that this methods is a simple accessor to
593 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
595 After the uninstallation and before returning to the sender,
596 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
598 **Input**: the *id* of the application and, optionally, the path to
609 "root": "/a/path/to/the/root"
612 **output**: the value 'true'.
616 #### Method org.AGL.afm.user.start
620 **Input**: the *id* of the application and, optionally, the
621 start *mode* as below.
623 Either just a string:
627 Or an object containing field "id" of type string and
628 optionally a field mode:
630 {"id":"appli@x.y","mode":"local"}
632 The field "mode" is a string equal to either "local" or "remote".
634 **output**: The *runid* of the application launched. *runid* is an integer.
638 #### Method org.AGL.afm.user.terminate
640 **Description**: Terminates the application attached to *runid*.
642 **Input**: The *runid* (an integer) of running instance to terminate.
644 **output**: the value 'true'.
648 #### Method org.AGL.afm.user.stop
650 **Description**: Stops the application attached to *runid* until terminate or continue.
652 **Input**: The *runid* (integer) of the running instance to stop.
654 **output**: the value 'true'.
658 #### Method org.AGL.afm.user.continue
660 **Description**: Continues the application attached to *runid* previously stopped.
662 **Input**: The *runid* (integer) of the running instance to continue.
664 **output**: the value 'true'.
668 #### Method org.AGL.afm.user.state
670 **Description**: Get informations about a running instance of *runid*.
672 **Input**: The *runid* (integer) of the running instance inspected.
674 **output**: An object describing instance state. It contains:
675 the runid (integer), the id of the running application (string),
676 the state of the application (string either: "starting", "running", "stopped").
678 Example of returned state:
688 #### Method org.AGL.afm.user.runners
690 **Description**: Get the list of currently running instances.
694 **output**: An array of states, one per running instance, as returned by
695 the methodd ***org.AGL.afm.user.state***.