docs/3_Developer_Guides/1_Application_Framework/1_afm-daemons.md

   1 ---
   2 title: The afm daemons
   3 ---
   4
   5 ## Foreword
   6
   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.
  10
  11 ## Introduction
  12
  13 Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications
  14 life.
  15 Understand that they will manage operations like:
  16
  17 - ***installation***
  18 - ***uninstallation***
  19 - ***running***
  20 - ***suspend***
  21 - ***inventory***
  22 - ...
  23
  24 In addition, they ensure that operations use the security framework as needed
  25 and that applications are executed in the correct context.
  26
  27 ***D-Bus*** is in charge of transmitting orders to the appropriate daemon
  28 depending upon ***D-Bus*** destination.
  29
  30 The figure below summarizes the situation of both **afm-system-daemon** and
  31 **afm-user-daemon** in the system.
  32
  33 ![afm-daemons][afm-daemons]
  34
  35 ## The D-Bus interface
  36
  37 ### Overview of the dbus interface
  38
  39 The ***afm daemons*** takes theirs orders from the session instance
  40 of D-Bus.
  41 The use of D-Bus is great because it allows to implement
  42 discovery and signaling.
  43
  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
  47 user sessions.
  48
  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***:
  53
  54 - ***install***
  55 - ***uninstall***
  56
  57 And for ***afm-user-daemon***:
  58
  59 - ***runnables***
  60 - ***detail***
  61 - ***start***
  62 - ***once***
  63 - ***terminate***
  64 - ***pause***
  65 - ***resume***
  66 - ***runners***
  67 - ***state***
  68 - ***install***
  69 - ***uninstall***
  70
  71 D-Bus is mainly used for signaling and discovery.
  72 Its optimized typed protocol is not used except for transmitting
  73  only one string in both directions.
  74
  75 The client and the service are using JSON serialization to
  76 exchange data.
  77 Signature of any member of the D-Bus interface is
  78 ***string -> string*** for ***JSON -> JSON***.
  79 This is the normal case, if there is an error, current implementation
  80 returns a dbus error that is a string.
  81
  82 Here are examples using *dbus-send*, here to install an application from a
  83 widget file:
  84
  85 ```bash
  86 dbus-send --session --print-reply \
  87     --dest=org.AGL.afm.system \
  88     /org/AGL/afm/system \
  89     org.AGL.afm.system.install 'string:"/tmp/appli.wgt"
  90 ```
  91
  92 And here, to query data on installed applications that can be run:
  93
  94 ```bash
  95 dbus-send --session --print-reply \
  96     --dest=org.AGL.afm.user \
  97     /org/AGL/afm/user \
  98     org.AGL.afm.user.runnables string:true
  99 ```
 100
 101 ### The protocol over D-Bus
 102
 103 On all following sub-chapters we assume that we talk about either
 104 ***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters
 105 are considered as self-explanatory.
 106
 107 The D-Bus interface is defined by:
 108
 109 - **DESTINATION**: org.AGL.afm.[user|system]
 110 - **PATH**: /org/AGL/afm/[user|system]
 111 - **INTERFACE**: org.AGL.afm.[user|system]
 112
 113 #### Method org.AGL.afm.system.install
 114
 115 **Description**: Install an application from a widget file.
 116
 117 When an application with the same *id* and *version* already exists. Outside of
 118 using *force=true* the application is not reinstalled.
 119
 120 Applications are installed the subdirectories of applications common directory.
 121 If *root* is specified, the application is installed under the
 122 sub-directories of the *root* defined.
 123
 124 Note that this methods is a simple accessor method of
 125 ***org.AGL.afm.system.install*** from ***afm-system-daemon***.
 126
 127 After the installation and before returning to the sender,
 128 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 129
 130 **Input**: The *path* of the widget file to install and, optionally,
 131 a flag to *force* reinstallation, and, optionally, a *root* directory.
 132
 133 Either just a string being the absolute path of the widget file:
 134
 135 ```bash
 136 "/a/path/driving/to/the/widget"
 137 ```
 138
 139 Or an object:
 140
 141 ```json
 142 {
 143   "wgt": "/a/path/to/the/widget",
 144   "force": false,
 145   "root": "/a/path/to/the/root"
 146 }
 147 ```
 148
 149 "wgt" and "root" must be absolute paths.
 150
 151 **output**: An object with the field "added" being the string for
 152 the id of the added application.
 153
 154 ```json
 155 {"added":"appli@x.y"}
 156 ```
 157
 158
 159
 160 #### Method org.AGL.afm.system.uninstall
 161
 162 **Description**: Uninstall an application from its id.
 163
 164 Note that this methods is a simple method accessor of
 165 ***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***.
 166
 167 After the uninstallation and before returning to the sender,
 168 ***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***.
 169
 170 **Input**: the *id* of the application and optionally the application *root* path.
 171
 172 Either a string:
 173
 174 ```bash
 175 "appli@x.y"
 176 ```
 177
 178 Or an object:
 179
 180 ```json
 181 {
 182   "id": "appli@x.y",
 183   "root": "/a/path/to/the/root"
 184 }
 185 ```
 186
 187 **output**: the value 'true'.
 188
 189
 190
 191 #### Method org.AGL.afm.user.detail
 192
 193 **Description**: Get details about an application from its id.
 194
 195 **Input**: the id of the application as below.
 196
 197 Either just a string:
 198
 199 ```bash
 200 "appli@x.y"
 201 ```
 202
 203 Or an object having the field "id" of type string:
 204
 205 ```json
 206 {"id":"appli@x.y"}
 207 ```
 208
 209 **Output**: A JSON object describing the application containing
 210 the fields described below.
 211
 212 ```json
 213 {
 214   "id":          string, the application id (id@version)
 215   "version":     string, the version of the application
 216   "width":       integer, requested width of the application
 217   "height":      integer, requested height of the application
 218   "name":        string, the name of the application
 219   "description": string, the description of the application
 220   "shortname":   string, the short name of the application
 221   "author":      string, the author of the application
 222 }
 223 ```
 224
 225
 226
 227 #### Method org.AGL.afm.user.runnables
 228
 229 **Description**: Get the list of applications that can be run.
 230
 231 **Input**: any valid json entry, can be anything except null.
 232
 233 **output**: An array of description of the runnable applications.
 234 Each item of the array contains an object containing the detail of
 235 an application as described above for the method
 236 *org.AGL.afm.user.detail*.
 237
 238
 239
 240 #### Method org.AGL.afm.user.install
 241
 242 **Description**: Install an application from its widget file.
 243
 244 If an application of the same *id* and *version* exists, it is not
 245 reinstalled except when *force=true*.
 246
 247 Applications are installed in the subdirectories of the common directory
 248 reserved for applications.
 249 If *root* is specified, the application is installed under
 250 sub-directories of defined *root*.
 251
 252 Note that this methods is a simple accessor to the method
 253 ***org.AGL.afm.system.install*** of ***afm-system-daemon***.
 254
 255 After the installation and before returning to the sender,
 256 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 257
 258 **Input**: The *path* of widget file to be installed. Optionally,
 259 a flag to *force* reinstallation and/or a *root* directory.
 260
 261 Simple form a simple string containing the absolute widget path:
 262
 263 ```bash
 264 "/a/path/driving/to/the/widget"
 265 ```
 266
 267 Or an object:
 268
 269 ```json
 270 {
 271   "wgt": "/a/path/to/the/widget",
 272   "force": false,
 273   "root": "/a/path/to/the/root"
 274 }
 275 ```
 276
 277 ***wgt*** and ***root*** MUST be absolute paths.
 278
 279 **output**: An object containing field "added" to use as application ID.
 280
 281 ```json
 282 {"added":"appli@x.y"}
 283 ```
 284
 285
 286
 287 #### Method org.AGL.afm.user.uninstall
 288
 289 **Description**: Uninstall an application from its id.
 290
 291 Note that this methods is a simple accessor to
 292 ***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***.
 293
 294 After the uninstallation and before returning to the sender,
 295 ***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***.
 296
 297 **Input**: the *id* of the application and, optionally, the path to
 298 application *root*.
 299
 300 Either a string:
 301
 302 ```bash
 303 "appli@x.y"
 304 ```
 305
 306 Or an object:
 307
 308 ```json
 309 {
 310   "id": "appli@x.y",
 311   "root": "/a/path/to/the/root"
 312 }
 313 ```
 314
 315 **output**: the value 'true'.
 316
 317
 318
 319 #### Method org.AGL.afm.user.start
 320
 321 **Description**:
 322
 323 **Input**: the *id* of the application and, optionally, the
 324 start *mode* as below.
 325
 326 Either just a string:
 327
 328 ```bash
 329 "appli@x.y"
 330 ```
 331
 332 Or an object containing field "id" of type string and
 333 optionally a field mode:
 334
 335 ```json
 336 {"id":"appli@x.y","mode":"local"}
 337 ```
 338
 339 The field "mode" is a string equal to either "local" or "remote".
 340
 341 [Currently the mode is not available in the systemd version]
 342
 343 **output**: The *runid* of the application launched. *runid* is an integer.
 344
 345
 346
 347 #### Method org.AGL.afm.user.once
 348
 349 **Description**:
 350
 351 **Input**: the *id* of the application
 352
 353 Either just a string:
 354
 355 ```bash
 356 "appli@x.y"
 357 ```
 358
 359 Or an object containing field "id" of type string.
 360
 361 ```json
 362 {"id":"appli@x.y"}
 363 ```
 364
 365 **output**: The *state* of the application retrieved or launched.
 366 See *org.AGL.afm.user.state* to get a description of the returned
 367 object.
 368
 369
 370
 371 #### Method org.AGL.afm.user.terminate
 372
 373 **Description**: Terminates the application attached to *runid*.
 374
 375 **Input**: The *runid* (an integer) of running instance to terminate.
 376
 377 **output**: the value 'true'.
 378
 379
 380
 381 #### Method org.AGL.afm.user.stop
 382
 383 Obsolete since 8th November 2016 (2016/11/08).
 384 Kept for compatibility.
 385
 386 Use **org.AGL.afm.user.pause** instead.
 387
 388
 389
 390 #### Method org.AGL.afm.user.continue
 391
 392 Obsolete since 8th November 2016 (2016/11/08).
 393 Kept for compatibility.
 394
 395 Use **org.AGL.afm.user.resume** instead.
 396
 397
 398
 399 #### Method org.AGL.afm.user.pause
 400
 401 [Currently not available in the systemd version]
 402
 403 **Description**: Pauses the application attached to *runid* until terminate or resume.
 404
 405 **Input**: The *runid* (integer) of the running instance to pause.
 406
 407 **output**: the value 'true'.
 408
 409
 410
 411 #### Method org.AGL.afm.user.resume
 412
 413 [Currently not available in the systemd version]
 414
 415 **Description**: Resumes the application attached to *runid* previously paused.
 416
 417 **Input**: The *runid* (integer) of the running instance to resume.
 418
 419 **output**: the value 'true'.
 420
 421
 422
 423 #### Method org.AGL.afm.user.state
 424
 425 **Description**: Get information about a running instance of *runid*.
 426
 427 **Input**: The *runid* (integer) of the running instance inspected.
 428
 429 **output**: An object describing instance state.
 430 It contains:
 431
 432 - the runid (integer)
 433 - the pids of the processes as an array starting
 434 - with the group leader
 435 - the id of the running application (string)
 436 - the state of the application (string either: "starting", "running", "paused").
 437
 438 Example of returned state:
 439
 440 ```json
 441     {
 442       "runid": 2,
 443       "pids": [ 435, 436 ],
 444       "state": "running",
 445       "id": "appli@x.y"
 446     }
 447 ```
 448
 449
 450
 451 #### Method org.AGL.afm.user.runners
 452
 453 **Description**: Get the list of currently running instances.
 454
 455 **Input**: anything.
 456
 457 **output**: An array of states, one per running instance, as returned by
 458 the method ***org.AGL.afm.user.state***.
 459
 460 ## Starting **afm daemons**
 461
 462 ***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd
 463 services attached to system and user respectively.
 464 Normally, service files are locatedat */lib/systemd/system/afm-system-daemon.service* and
 465 */usr/lib/systemd/user/afm-user-daemon.service*.
 466
 467 ### ***afm-system-daemon*** options
 468
 469 The options for launching **afm-system-daemon** are:
 470
 471 ```bash
 472     -r
 473     --root directory
 474
 475          Set the root application directory.
 476
 477          Note that the default root directory is defined
 478          to be /usr/share/afm/applications (may change).
 479
 480     -d
 481     --daemon
 482
 483          Daemonizes the process. It is not needed by systemd.
 484
 485     -q
 486     --quiet
 487
 488          Reduces the verbosity (can be repeated).
 489
 490     -v
 491     --verbose
 492
 493          Increases the verbosity (can be repeated).
 494
 495     -h
 496     --help
 497
 498          Prints a short help.
 499 ```
 500
 501 ### ***afm-user-daemon*** options
 502
 503 The options for launching **afm-user-daemon** are:
 504
 505 ```bash
 506     -a
 507     --application directory
 508
 509          [Currently not available in the systemd version]
 510
 511          Includes the given application directory to
 512          the database base of applications.
 513
 514          Can be repeated.
 515
 516     -r
 517     --root directory
 518
 519          [Currently not available in the systemd version]
 520
 521          Includes root application directory or directories when
 522          passing multiple rootdir to
 523          applications database.
 524
 525          Note that default root directory for
 526          applications is always added. In current version
 527          /usr/share/afm/applications is used as default.
 528
 529     -m
 530     --mode (local|remote)
 531
 532          [Currently not available in the systemd version]
 533
 534          Set the default launch mode.
 535          The default value is 'local'
 536
 537     -d
 538     --daemon
 539
 540          Daemonizes the process. It is not needed by systemd.
 541
 542     -q
 543     --quiet
 544
 545          Reduces the verbosity (can be repeated).
 546
 547     -v
 548     --verbose
 549
 550          Increases the verbosity (can be repeated).
 551
 552     -h
 553     --help
 554
 555          Prints a short help.
 556 ```
 557
 558 ## Tasks of **afm-user-daemon**
 559
 560 ### Maintaining list of applications
 561
 562 At start **afm-user-daemon** scans the directories containing
 563 applications and load in memory a list of available applications
 564 accessible by current user.
 565
 566 When **afm-system-daemon** installs or removes an application.
 567 On success it sends the signal *org.AGL.afm.system.changed*.
 568 When receiving such a signal, **afm-user-daemon** rebuilds its
 569 applications list.
 570
 571 **afm-user-daemon** provides the data it collects about
 572 applications to its clients.
 573 Clients may either request the full list
 574 of available applications or a more specific information about a
 575 given application.
 576
 577 ### Launching application
 578
 579 **afm-user-daemon** launches application by using systemd.
 580 Systemd builds a secure environment for the application
 581 before starting it.
 582
 583 Once launched, running instances of application receive
 584 a runid that identify them.
 585 To make interface with systemd evident, the pid is the runid.
 586
 587 ### Managing instances of running applications
 588
 589 **afm-user-daemon** manages the list of applications
 590 that it launched.
 591
 592 When owning the right permissions, a client can get the list
 593 of running instances and details about a specific
 594 running instance.
 595 It can also terminate a given application.
 596
 597 ### Installing and uninstalling applications
 598
 599 If the client own the right permissions,
 600 **afm-user-daemon** delegates that task
 601 to **afm-system-daemon**.
 602
 603 ## Using ***afm-util***
 604
 605 The command line tool ***afm-util*** uses dbus-send to send
 606 orders to **afm-user-daemon**.
 607 This small scripts allows to send command to ***afm-user-daemon*** either
 608 interactively at shell prompt or scriptically.
 609
 610 The syntax is simple:
 611
 612 - it accept a command and when requires attached arguments.
 613
 614 Here is the summary of ***afm-util***:
 615
 616 - **afm-util runnables      **:
 617   list the runnable widgets installed
 618
 619 - **afm-util install    wgt **:
 620   install the wgt file
 621
 622 - **afm-util uninstall  id  **:
 623   remove the installed widget of id
 624
 625 - **afm-util detail     id  **:
 626   print detail about the installed widget of id
 627
 628 - **afm-util runners        **:
 629   list the running instance
 630
 631 - **afm-util start      id  **:
 632   start an instance of the widget of id
 633
 634 - **afm-util once      id  **:
 635   run once an instance of the widget of id
 636
 637 - **afm-util terminate  rid **:
 638   terminate the running instance rid
 639
 640 - **afm-util state      rid **:
 641   get status of the running instance rid
 642
 643 Here is how to list applications using ***afm-util***:
 644
 645 ```bash
 646     afm-util runnables
 647 ```
 648
 649 [afm-daemons]: images/afm-daemons.svg