docs/4_APIs_and_Services/4.2_Application_Framework/1_afm-daemons.md

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