1 The application framework daemons
2 =================================
7 This document describes application framework daemons
8 FCS (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 [Currently the mode is not available in the systemd version]
313 **output**: The *runid* of the application launched. *runid* is an integer.
317 #### Method org.AGL.afm.user.once
321 **Input**: the *id* of the application
323 Either just a string:
327 Or an object containing field "id" of type string.
331 **output**: The *state* of the application retrieved or launched.
332 See *org.AGL.afm.user.state* to get a description of the returned
337 #### Method org.AGL.afm.user.terminate
339 **Description**: Terminates the application attached to *runid*.
341 **Input**: The *runid* (an integer) of running instance to terminate.
343 **output**: the value 'true'.
347 #### Method org.AGL.afm.user.stop
349 Obsolete since 8th November 2016 (2016/11/08).
350 Kept for compatibility.
352 Use **org.AGL.afm.user.pause** instead.
356 #### Method org.AGL.afm.user.continue
358 Obsolete since 8th November 2016 (2016/11/08).
359 Kept for compatibility.
361 Use **org.AGL.afm.user.resume** instead.
365 #### Method org.AGL.afm.user.pause
367 [Currently not available in the systemd version]
369 **Description**: Pauses the application attached to *runid* until terminate or resume.
371 **Input**: The *runid* (integer) of the running instance to pause.
373 **output**: the value 'true'.
377 #### Method org.AGL.afm.user.resume
379 [Currently not available in the systemd version]
381 **Description**: Resumes the application attached to *runid* previously paused.
383 **Input**: The *runid* (integer) of the running instance to resume.
385 **output**: the value 'true'.
389 #### Method org.AGL.afm.user.state
391 **Description**: Get informations about a running instance of *runid*.
393 **Input**: The *runid* (integer) of the running instance inspected.
395 **output**: An object describing instance state. It contains:
396 the runid (integer), the pids of the processes as an array starting
397 with the group leader, the id of the running application (string),
398 the state of the application (string either: "starting", "running", "paused").
400 Example of returned state:
404 "pids": [ 435, 436 ],
411 #### Method org.AGL.afm.user.runners
413 **Description**: Get the list of currently running instances.
417 **output**: An array of states, one per running instance, as returned by
418 the method ***org.AGL.afm.user.state***.
420 Starting **afm daemons**
421 ----------------------
423 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
424 services attached to system and user respectively. Normally, service files are
425 locatedat */lib/systemd/system/afm-system-daemon.service* and
426 */usr/lib/systemd/user/afm-user-daemon.service*.
428 ### ***afm-system-daemon*** options
430 The options for launching **afm-system-daemon** are:
435 Set the root application directory.
437 Note that the default root directory is defined
438 to be /usr/share/afm/applications (may change).
443 Daemonizes the process. It is not needed by sytemd.
448 Reduces the verbosity (can be repeated).
453 Increases the verbosity (can be repeated).
460 ### ***afm-user-daemon*** options
462 The options for launching **afm-user-daemon** are:
465 --application directory
467 [Currently not available in the systemd version]
469 Includes the given application directory to
470 the database base of applications.
477 [Currently not available in the systemd version]
479 Includes root application directory or directories when
480 passing multiple rootdir to
481 applications database.
483 Note that default root directory for
484 applications is always added. In current version
485 /usr/share/afm/applications is used as default.
488 --mode (local|remote)
490 [Currently not available in the systemd version]
492 Set the default launch mode.
493 The default value is 'local'
498 Daemonizes the process. It is not needed by sytemd.
503 Reduces the verbosity (can be repeated).
508 Increases the verbosity (can be repeated).
515 Tasks of **afm-user-daemon**
516 ----------------------------
518 ### Maintaining list of applications
520 At start **afm-user-daemon** scans the directories containing
521 applications and load in memory a list of avaliable applications
522 accessible by current user.
524 When **afm-system-daemon** installs or removes an application.
525 On success it sends the signal *org.AGL.afm.system.changed*.
526 When receiving such a signal, **afm-user-daemon** rebuilds its
529 **afm-user-daemon** provides the data it collects about
530 applications to its clients. Clients may either request the full list
531 of avaliable applications or a more specific information about a
534 ### Launching application
536 **afm-user-daemon** launches application by using systemd.
537 Systemd builds a secure environment for the application
540 Once launched, running instances of application receive
541 a runid that identify them. To make interface with systemd
542 evident, the pid is the runid.
544 ### Managing instances of running applications
546 **afm-user-daemon** manages the list of applications
549 When owning the right permissions, a client can get the list
550 of running instances and details about a specific
551 running instance. It can also terminate a given application.
553 ### Installing and uninstalling applications
555 If the client own the right permissions,
556 **afm-user-daemon** delegates that task
557 to **afm-system-daemon**.
562 The command line tool ***afm-util*** uses dbus-send to send
563 orders to **afm-user-daemon**. This small scripts allows to
564 send command to ***afm-user-daemon*** either interactively
565 at shell prompt or scriptically.
567 The syntax is simple: it accept a command and when requires attached arguments.
569 Here is the summary of ***afm-util***:
571 - **afm-util runnables **:
573 list the runnable widgets installed
575 - **afm-util install wgt **:
579 - **afm-util uninstall id **:
581 remove the installed widget of id
583 - **afm-util detail id **:
585 print detail about the installed widget of id
587 - **afm-util runners **:
589 list the running instance
591 - **afm-util start id **:
593 start an instance of the widget of id
595 - **afm-util once id **:
597 run once an instance of the widget of id
599 - **afm-util terminate rid **:
601 terminate the running instance rid
603 - **afm-util state rid **:
605 get status of the running instance rid
608 Here is how to list applications using ***afm-util***:
613 [afm-daemons]: pictures/afm-daemons.svg