1 # The application framework daemons
5 This document describes application framework daemons
6 FCS (Fully Conform to Specification) implementation is still under development.
7 It may happen that current implementation somehow diverges with specifications.
11 Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications
13 Understand that they will manage operations like:
16 - ***uninstallation***
22 In addition, they ensure that operations use the security framework as needed
23 and that applications are executed in the correct context.
25 ***D-Bus*** is in charge of transmitting orders to the appropriate daemon
26 depending upon ***D-Bus*** destination.
28 The figure below summarizes the situation of both **afm-system-daemon** and
29 **afm-user-daemon** in the system.
31 ![afm-daemons][afm-daemons]{:: style="width:65%;"}
33 ## The D-Bus interface
35 ### Overview of the dbus interface
37 The ***afm daemons*** takes theirs orders from the session instance
39 The use of D-Bus is great because it allows to implement
40 discovery and signaling.
42 The dbus session is by default addressed by environment
43 variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd**
44 variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for
47 They are listening with the destination name ***org.AGL.afm.[user|system]***
48 at the object of path ***/org/AGL/afm/[user|system]*** on the interface
49 ***org.AGL.afm.[user|system]*** for the below detailed members for the
50 ***afm-system-daemon***:
55 And for ***afm-user-daemon***:
69 D-Bus is mainly used for signaling and discovery.
70 Its optimized typed protocol is not used except for transmitting
71 only one string in both directions.
73 The client and the service are using JSON serialization to
75 Signature of any member of the D-Bus interface is
76 ***string -> string*** for ***JSON -> JSON***.
77 This is the normal case, if there is an error, current implementation
78 returns a dbus error that is a string.
80 Here are examples using *dbus-send*, here to install an application from a
84 dbus-send --session --print-reply \
85 --dest=org.AGL.afm.system \
87 org.AGL.afm.system.install 'string:"/tmp/appli.wgt"
90 And here, to query data on installed applications that can be run:
93 dbus-send --session --print-reply \
94 --dest=org.AGL.afm.user \
96 org.AGL.afm.user.runnables string:true
99 ### The protocol over D-Bus
101 On all following sub-chapters we assume that we talk about either
102 ***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters
103 are considered as self-explanatory.
105 The D-Bus interface is defined by:
107 - **DESTINATION**: org.AGL.afm.[user|system]
108 - **PATH**: /org/AGL/afm/[user|system]
109 - **INTERFACE**: org.AGL.afm.[user|system]
111 #### Method org.AGL.afm.system.install
113 **Description**: Install an application from a widget file.
115 When an application with the same *id* and *version* already exists. Outside of
116 using *force=true* the application is not reinstalled.
118 Applications are installed the subdirectories of applications common directory.
119 If *root* is specified, the application is installed under the
120 sub-directories of the *root* defined.
122 Note that this methods is a simple accessor method of
123 ***org.AGL.afm.system.install*** from ***afm-system-daemon***.
125 After the installation and before returning to the sender,
126 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
128 **Input**: The *path* of the widget file to install and, optionally,
129 a flag to *force* reinstallation, and, optionally, a *root* directory.
131 Either just a string being the absolute path of the widget file:
134 "/a/path/driving/to/the/widget"
141 "wgt": "/a/path/to/the/widget",
143 "root": "/a/path/to/the/root"
147 "wgt" and "root" must be absolute paths.
149 **output**: An object with the field "added" being the string for
150 the id of the added application.
153 {"added":"appli@x.y"}
158 #### Method org.AGL.afm.system.uninstall
160 **Description**: Uninstall an application from its id.
162 Note that this methods is a simple method accessor of
163 ***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***.
165 After the uninstallation and before returning to the sender,
166 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
168 **Input**: the *id* of the application and optionally the application *root* path.
181 "root": "/a/path/to/the/root"
185 **output**: the value 'true'.
189 #### Method org.AGL.afm.user.detail
191 **Description**: Get details about an application from its id.
193 **Input**: the id of the application as below.
195 Either just a string:
201 Or an object having the field "id" of type string:
207 **Output**: A JSON object describing the application containing
208 the fields described below.
212 "id": string, the application id (id@version)
213 "version": string, the version of the application
214 "width": integer, requested width of the application
215 "height": integer, requested height of the application
216 "name": string, the name of the application
217 "description": string, the description of the application
218 "shortname": string, the short name of the application
219 "author": string, the author of the application
225 #### Method org.AGL.afm.user.runnables
227 **Description**: Get the list of applications that can be run.
229 **Input**: any valid json entry, can be anything except null.
231 **output**: An array of description of the runnable applications.
232 Each item of the array contains an object containing the detail of
233 an application as described above for the method
234 *org.AGL.afm.user.detail*.
238 #### Method org.AGL.afm.user.install
240 **Description**: Install an application from its widget file.
242 If an application of the same *id* and *version* exists, it is not
243 reinstalled except when *force=true*.
245 Applications are installed in the subdirectories of the common directory
246 reserved for applications.
247 If *root* is specified, the application is installed under
248 sub-directories of defined *root*.
250 Note that this methods is a simple accessor to the method
251 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
253 After the installation and before returning to the sender,
254 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
256 **Input**: The *path* of widget file to be installed. Optionally,
257 a flag to *force* reinstallation and/or a *root* directory.
259 Simple form a simple string containing the absolute widget path:
262 "/a/path/driving/to/the/widget"
269 "wgt": "/a/path/to/the/widget",
271 "root": "/a/path/to/the/root"
275 ***wgt*** and ***root*** MUST be absolute paths.
277 **output**: An object containing field "added" to use as application ID.
280 {"added":"appli@x.y"}
285 #### Method org.AGL.afm.user.uninstall
287 **Description**: Uninstall an application from its id.
289 Note that this methods is a simple accessor to
290 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
292 After the uninstallation and before returning to the sender,
293 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
295 **Input**: the *id* of the application and, optionally, the path to
309 "root": "/a/path/to/the/root"
313 **output**: the value 'true'.
317 #### Method org.AGL.afm.user.start
321 **Input**: the *id* of the application and, optionally, the
322 start *mode* as below.
324 Either just a string:
330 Or an object containing field "id" of type string and
331 optionally a field mode:
334 {"id":"appli@x.y","mode":"local"}
337 The field "mode" is a string equal to either "local" or "remote".
339 [Currently the mode is not available in the systemd version]
341 **output**: The *runid* of the application launched. *runid* is an integer.
345 #### Method org.AGL.afm.user.once
349 **Input**: the *id* of the application
351 Either just a string:
357 Or an object containing field "id" of type string.
363 **output**: The *state* of the application retrieved or launched.
364 See *org.AGL.afm.user.state* to get a description of the returned
369 #### Method org.AGL.afm.user.terminate
371 **Description**: Terminates the application attached to *runid*.
373 **Input**: The *runid* (an integer) of running instance to terminate.
375 **output**: the value 'true'.
379 #### Method org.AGL.afm.user.stop
381 Obsolete since 8th November 2016 (2016/11/08).
382 Kept for compatibility.
384 Use **org.AGL.afm.user.pause** instead.
388 #### Method org.AGL.afm.user.continue
390 Obsolete since 8th November 2016 (2016/11/08).
391 Kept for compatibility.
393 Use **org.AGL.afm.user.resume** instead.
397 #### Method org.AGL.afm.user.pause
399 [Currently not available in the systemd version]
401 **Description**: Pauses the application attached to *runid* until terminate or resume.
403 **Input**: The *runid* (integer) of the running instance to pause.
405 **output**: the value 'true'.
409 #### Method org.AGL.afm.user.resume
411 [Currently not available in the systemd version]
413 **Description**: Resumes the application attached to *runid* previously paused.
415 **Input**: The *runid* (integer) of the running instance to resume.
417 **output**: the value 'true'.
421 #### Method org.AGL.afm.user.state
423 **Description**: Get information about a running instance of *runid*.
425 **Input**: The *runid* (integer) of the running instance inspected.
427 **output**: An object describing instance state.
430 - the runid (integer)
431 - the pids of the processes as an array starting
432 - with the group leader
433 - the id of the running application (string)
434 - the state of the application (string either: "starting", "running", "paused").
436 Example of returned state:
441 "pids": [ 435, 436 ],
449 #### Method org.AGL.afm.user.runners
451 **Description**: Get the list of currently running instances.
455 **output**: An array of states, one per running instance, as returned by
456 the method ***org.AGL.afm.user.state***.
458 ## Starting **afm daemons**
460 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
461 services attached to system and user respectively.
462 Normally, service files are locatedat */lib/systemd/system/afm-system-daemon.service* and
463 */usr/lib/systemd/user/afm-user-daemon.service*.
465 ### ***afm-system-daemon*** options
467 The options for launching **afm-system-daemon** are:
473 Set the root application directory.
475 Note that the default root directory is defined
476 to be /usr/share/afm/applications (may change).
481 Daemonizes the process. It is not needed by systemd.
486 Reduces the verbosity (can be repeated).
491 Increases the verbosity (can be repeated).
499 ### ***afm-user-daemon*** options
501 The options for launching **afm-user-daemon** are:
505 --application directory
507 [Currently not available in the systemd version]
509 Includes the given application directory to
510 the database base of applications.
517 [Currently not available in the systemd version]
519 Includes root application directory or directories when
520 passing multiple rootdir to
521 applications database.
523 Note that default root directory for
524 applications is always added. In current version
525 /usr/share/afm/applications is used as default.
528 --mode (local|remote)
530 [Currently not available in the systemd version]
532 Set the default launch mode.
533 The default value is 'local'
538 Daemonizes the process. It is not needed by systemd.
543 Reduces the verbosity (can be repeated).
548 Increases the verbosity (can be repeated).
556 ## Tasks of **afm-user-daemon**
558 ### Maintaining list of applications
560 At start **afm-user-daemon** scans the directories containing
561 applications and load in memory a list of available applications
562 accessible by current user.
564 When **afm-system-daemon** installs or removes an application.
565 On success it sends the signal *org.AGL.afm.system.changed*.
566 When receiving such a signal, **afm-user-daemon** rebuilds its
569 **afm-user-daemon** provides the data it collects about
570 applications to its clients.
571 Clients may either request the full list
572 of available applications or a more specific information about a
575 ### Launching application
577 **afm-user-daemon** launches application by using systemd.
578 Systemd builds a secure environment for the application
581 Once launched, running instances of application receive
582 a runid that identify them.
583 To make interface with systemd evident, the pid is the runid.
585 ### Managing instances of running applications
587 **afm-user-daemon** manages the list of applications
590 When owning the right permissions, a client can get the list
591 of running instances and details about a specific
593 It can also terminate a given application.
595 ### Installing and uninstalling applications
597 If the client own the right permissions,
598 **afm-user-daemon** delegates that task
599 to **afm-system-daemon**.
601 ## Using ***afm-util***
603 The command line tool ***afm-util*** uses dbus-send to send
604 orders to **afm-user-daemon**.
605 This small scripts allows to send command to ***afm-user-daemon*** either
606 interactively at shell prompt or scriptically.
608 The syntax is simple:
610 - it accept a command and when requires attached arguments.
612 Here is the summary of ***afm-util***:
614 - **afm-util runnables **:
615 list the runnable widgets installed
617 - **afm-util install wgt **:
620 - **afm-util uninstall id **:
621 remove the installed widget of id
623 - **afm-util detail id **:
624 print detail about the installed widget of id
626 - **afm-util runners **:
627 list the running instance
629 - **afm-util start id **:
630 start an instance of the widget of id
632 - **afm-util once id **:
633 run once an instance of the widget of id
635 - **afm-util terminate rid **:
636 terminate the running instance rid
638 - **afm-util state rid **:
639 get status of the running instance rid
641 Here is how to list applications using ***afm-util***:
647 [afm-daemons]: pictures/afm-daemons.svg