doc/afm-user-daemon.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="doc.css">
   4   <meta charset="UTF-8">
   5 </head>
   6 <body>
   7 <a name="The.afm-user-daemon"></a>
   8 <h1>The afm-user-daemon</h1>
   9
  10 <pre><code>version: 1
  11 Date:    14 March 2016
  12 Author:  José Bollo
  13 </code></pre>
  14
  15 <a name="Foreword"></a>
  16 <h2>Foreword</h2>
  17
  18 <p>This document describes what we intend to do. It may happen that our
  19 current implementation and the content of this document differ.</p>
  20
  21 <p>In case of differences, it is assumed that this document is right
  22 and the implementation is wrong.</p>
  23
  24 <a name="Introduction"></a>
  25 <h2>Introduction</h2>
  26
  27 <p>The daemon <strong>afm-user-daemon</strong> is in charge of handling
  28 applications for one user. Its main tasks are:</p>
  29
  30 <ul>
  31 <li><p>enumerate the applications that the user can run
  32 and keep the list avalable on demand</p></li>
  33 <li><p>start applications for the user, set their running
  34 environment, set their security context</p></li>
  35 <li><p>list the current runner applications</p></li>
  36 <li><p>stop (aka pause), continue (aka resume), terminate
  37 the running instance of application</p></li>
  38 <li><p>transfer requests for installation or uninstallation
  39 of applications to the dedicated system daemon
  40 <strong>afm-system-daemon</strong></p></li>
  41 </ul>
  42
  43
  44 <p>The <strong>afm-user-daemon</strong> takes its orders from the session
  45 instance of D-Bus.</p>
  46
  47 <p>The figure below summarizes the situation of the
  48 <strong>afm-user-daemon</strong> in the system.</p>
  49
  50 <pre><code>+------------------------------------------------------------+
  51 |                          User                              |
  52 |                                 +---------------------+    |
  53 |     +---------------------+     |   Smack isolated    |    |
  54 |     |   D-Bus   session   +     |    APPLICATIONS     |    |
  55 |     +----------+----------+     +---------+-----------+    |
  56 |                |                          |                |
  57 |                |                          |                |
  58 |     +----------+--------------------------+-----------+    |
  59 |     |                                                 |    |
  60 |     |                  afm-user-daemon                |    |
  61 |     |                                                 |    |
  62 |     +----------+----------------------+----------+----+    |
  63 |                |                      |          :         |
  64 |                |                      |          :         |
  65 :================|======================|==========:=========:
  66 |                |                      |          :         |
  67 |     +----------+----------+     +-----+-----+    :         |
  68 |     |   D-Bus   system    +-----+  CYNARA   |    :         |
  69 |     +----------+----------+     +-----+-----+    :         |
  70 |                |                      |          :         |
  71 |     +----------+---------+    +-------+----------+----+    |
  72 |     | afm-system-daemon  +----+   SECURITY-MANAGER    |    |
  73 |     +--------------------+    +-----------------------+    |
  74 |                                                            |
  75 |                          System                            |
  76 +------------------------------------------------------------+
  77 </code></pre>
  78
  79 <a name="Tasks.of..strong.afm-user-daemon..strong."></a>
  80 <h2>Tasks of <strong>afm-user-daemon</strong></h2>
  81
  82 <a name="Maintaining.list.of.applications"></a>
  83 <h3>Maintaining list of applications</h3>
  84
  85 <p>At start <strong>afm-user-daemon</strong> scans the directories containing
  86 the applications and load in memory the list applications
  87 availables to the current user.</p>
  88
  89 <p>When <strong>afm-system-daemon</strong> installs or removes an application,
  90 it sends the signal <em>org.AGL.afm.system.changed</em> on success.
  91 If it receives that signal, <strong>afm-user-daemon</strong> rebuild its
  92 list of applications.</p>
  93
  94 <p><strong>afm-user-daemon</strong> provides the data that it collected about
  95 application to its clients that either want to get that list
  96 or to get information about one application.</p>
  97
  98 <a name="Launching.applications"></a>
  99 <h3>Launching applications</h3>
 100
 101 <p><strong>afm-user-daemon</strong> launchs the applications. This means
 102 that its builds a secure environment for the application
 103 and then start it inside that secured environment.</p>
 104
 105 <p>Applications of different kind can be launched.</p>
 106
 107 <p>This is set using a configuration file that describes
 108 how to launch an application of a given kind for a given
 109 mode.</p>
 110
 111 <p>There is two launching modes: local or remote.</p>
 112
 113 <p>Launching an application locally means that
 114 the application and its binder are launcher together.</p>
 115
 116 <p>Launching application remotely means that only the
 117 binder is launched for the application.</p>
 118
 119 <p>Once launched, running instances of application receive
 120 a runid that identify them.</p>
 121
 122 <a name="Managing.instances.of.running.applications"></a>
 123 <h3>Managing instances of running applications</h3>
 124
 125 <p><strong>afm-user-daemon</strong> manages the list of applications
 126 that it launched.</p>
 127
 128 <p>With the good permissions, a client can get the list
 129 of the running instances and details about a specific
 130 running instance. It can also terminate, stop or
 131 continue a given application.</p>
 132
 133 <a name="Installing.and.uninstalling.applications"></a>
 134 <h3>Installing and uninstalling applications</h3>
 135
 136 <p>If the client has the good permission,
 137 <strong>afm-user-daemon</strong> delegates that task
 138 to <strong>afm-system-daemon</strong>.</p>
 139
 140 <a name="Starting..strong.afm-user-daemon..strong."></a>
 141 <h2>Starting <strong>afm-user-daemon</strong></h2>
 142
 143 <p><strong>afm-user-daemon</strong> is launched as a <strong>systemd</strong> service
 144 attached to user sessions. Normally, the service file is
 145 located at /usr/lib/systemd/user/afm-user-daemon.service.</p>
 146
 147 <p>The options for launching <strong>afm-user-daemon</strong> are:</p>
 148
 149 <pre><code>-a
 150 --application directory
 151
 152      Includes the given application directory to
 153      the database base of applications.
 154
 155 -r
 156 --root directory
 157
 158      Includes the root application directory to
 159      the database base of applications.
 160
 161      Note that the default root directory for
 162      applications is always added. It is defined
 163      to be /usr/share/afm/applications (may change).
 164
 165 -m
 166 --mode (local|remote)
 167
 168      Set the default launch mode.
 169      The default value is 'local'
 170
 171 -d
 172 --daemon
 173
 174      Daemonizes the process. It is not needed by sytemd.
 175
 176 -q
 177 --quiet
 178
 179      Reduces the verbosity (can be repeated).
 180
 181 -v
 182 --verbose
 183
 184      Increases the verbosity (can be repeated).
 185
 186 -h
 187 --help
 188
 189      Prints a short help.
 190 </code></pre>
 191
 192 <a name="Configuration.of.the.launcher"></a>
 193 <h2>Configuration of the launcher</h2>
 194
 195 <p>It contains rules for launching applications.
 196 When <strong>afm-user-daemon</strong> need to launch an application,
 197 it looks to the mode of launch, local or remote, and the
 198 type of the application as given by the file <strong><em>config.xml</em></strong>
 199 of the widget.</p>
 200
 201 <p>This couple mode and type allows to select the rule.</p>
 202
 203 <p>The configuration file is <strong>/etc/afm/afm-launch.conf</strong>.</p>
 204
 205 <p>It contains sections and rules. It can also contain comments
 206 and empty lines to improve the readability.</p>
 207
 208 <p>The separators are space and tabulation, any other character
 209 is meaning something.</p>
 210
 211 <p>The format is line oriented.
 212 The new line character separate the lines.</p>
 213
 214 <p>Lines having only separators are blank lines and are skipped.
 215 Line having the character # (sharp) as first not separator character
 216 are comment lines and are ignored.</p>
 217
 218 <p>Lines starting with a not separator character are differents
 219 of lines starting with a separator character.</p>
 220
 221 <p>The grammar of the configuration file is defined below:</p>
 222
 223 <pre><code>CONF: *COMMENT *SECTION
 224
 225 SECTION: MODE *RULE
 226
 227 RULE: +TYPE VECTOR ?VECTOR
 228
 229 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
 230
 231 TYPE: DATA *SEP EOL
 232
 233 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
 234
 235 DATA: CHAR *NCHAR
 236 NDATA: +NCHAR
 237
 238 EOL: NL *COMMENT
 239 COMMENT: *SEP CMT *(SEP | NCHAR) NL
 240
 241 NL: '\x0a'
 242 SEP: '\x20' | '\x09'
 243 CMT: '#'
 244 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
 245 NCHAR: CMT | CHAR
 246 </code></pre>
 247
 248 <p>Here is a sample of configuration file for defining how
 249 to launch an application declared of types <em>application/x-executable</em>,
 250 <em>text/x-shellscript</em> and <em>text/html</em> in mode local:</p>
 251
 252 <pre><code>mode local
 253
 254 application/x-executable
 255 text/x-shellscript
 256     %r/%c
 257
 258 text/html
 259     /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
 260     /usr/bin/web-runtime http://localhost:%P/%c?token=%S
 261 </code></pre>
 262
 263 <p>This shows that:</p>
 264
 265 <ul>
 266 <li>within a section, several rules can be defined</li>
 267 <li>within a rule, several types can be defined</li>
 268 <li>within a rule, one or two vectors can be defined</li>
 269 <li>vectors are using %substitution</li>
 270 <li>launched binaries must be defined with their full path</li>
 271 </ul>
 272
 273
 274 <a name="mode.local"></a>
 275 <h3>mode local</h3>
 276
 277 <p>Within this mode, the launchers have either one or two vectors
 278 describing them. All of these vectors are treated as programs
 279 and are executed with the system call &lsquo;execve&rsquo;.</p>
 280
 281 <p>The first vector is the leader vector and it defines the process
 282 group. The second vector (if any) is attached to the group
 283 defined by this first vector.</p>
 284
 285 <a name="mode.remote"></a>
 286 <h3>mode remote</h3>
 287
 288 <p>Within this mode, the launchers have either one or two vectors
 289 describing them.</p>
 290
 291 <p>The first vector is treated as a program and is executed with
 292 the system call &lsquo;execve&rsquo;.</p>
 293
 294 <p>The second vector (if any) defines a text that is returned
 295 to the caller. This mechanism can be used to return the uri
 296 to connect to for executing the application remotely.</p>
 297
 298 <p>The daemon <strong><em>afm-user-daemon</em></strong> allocates a port for the
 299 running the application remotely.
 300 The current implmentation of the port allocation is just
 301 incremental.
 302 A more reliable (cacheable and same-originable) allocation
 303 is to be defined.</p>
 304
 305 <a name="L.substitutions"></a>
 306 <h3>%substitutions</h3>
 307
 308 <p>Vectors can include sequences of 2 characters that have a special
 309 meaning. These sequences are named <em>%substitution</em> because their
 310 first character is the percent sign (%) and because each occurrence
 311 of the sequence is replaced, at launch time, by the value associated
 312 to sequences.</p>
 313
 314 <p>Here is the list of <em>%substitutions</em>:</p>
 315
 316 <ul>
 317 <li><p><strong><em>%%</em></strong>: %.</p>
 318
 319 <p>This simply emits the percent sign %</p></li>
 320 <li><p><strong><em>%a</em></strong>: appid</p>
 321
 322 <p>This is the application Id of the launched application.</p>
 323
 324 <p>Defined by the attribute <strong>id</strong> of the element <strong><widget></strong>
 325 of <strong>config.xml</strong>.</p></li>
 326 <li><p><strong><em>%c</em></strong>: content</p>
 327
 328 <p>The file within the widget directory that is the entry point.</p>
 329
 330 <p>For a HTML application, it is the relative path to the main
 331 page (aka index.html).</p>
 332
 333 <p>Defined by the attribute <strong>src</strong> of the element <strong><content></strong>
 334 of <strong>config.xml</strong>.</p></li>
 335 <li><p><strong><em>%D</em></strong>: datadir</p>
 336
 337 <p>Path of the directory where the application runs (cwd)
 338 and stores its data.</p>
 339
 340 <p>It is equal to %h/%a.</p></li>
 341 <li><p><strong><em>%H</em></strong>: height</p>
 342
 343 <p>Requested height for the widget.</p>
 344
 345 <p>Defined by the attribute <strong>height</strong> of the element <strong><widget></strong>
 346 of <strong>config.xml</strong>.</p></li>
 347 <li><p><strong><em>%h</em></strong>: homedir</p>
 348
 349 <p>Path of the home directory for all applications.</p>
 350
 351 <p>It is generally equal to $HOME/app-data</p></li>
 352 <li><p><strong><em>%I</em></strong>: icondir</p>
 353
 354 <p>Path of the directory were the icons of the applications can be found.</p></li>
 355 <li><p><strong><em>%m</em></strong>: mime-type</p>
 356
 357 <p>Mime type of the launched application.</p>
 358
 359 <p>Defined by the attribute <strong>type</strong> of the element <strong><content></strong>
 360 of <strong>config.xml</strong>.</p></li>
 361 <li><p><strong><em>%n</em></strong>: name</p>
 362
 363 <p>Name of the application as defined by the content of the
 364 element <strong><name></strong> of <strong>config.xml</strong>.</p></li>
 365 <li><p><strong><em>%p</em></strong>: plugins</p>
 366
 367 <p>Unhandled until now.</p>
 368
 369 <p>Will be the colon separated list of plugins and plugins directory.</p></li>
 370 <li><p><strong><em>%P</em></strong>: port</p>
 371
 372 <p>A port to use. It is currently a kind of random port. The precise
 373 model is to be defined later.</p></li>
 374 <li><p><strong><em>%R</em></strong>: readyfd</p>
 375
 376 <p>Number of the file descriptor to use for signalling
 377 readyness of the launched process.</p></li>
 378 <li><p><strong><em>%r</em></strong>: rootdir</p>
 379
 380 <p>Path of the directory containing the widget and its data.</p></li>
 381 <li><p><strong><em>%S</em></strong>: secret</p>
 382
 383 <p>An hexadecimal number that can be used to pair the client
 384 with its server binder.</p></li>
 385 <li><p><strong><em>%W</em></strong>: width</p>
 386
 387 <p>Requested width for the widget.</p>
 388
 389 <p>Defined by the attribute <strong>width</strong> of the element <strong><widget></strong>
 390 of <strong>config.xml</strong>.</p></li>
 391 </ul>
 392
 393
 394 <a name="The.D-Bus.interface"></a>
 395 <h2>The D-Bus interface</h2>
 396
 397 <a name="Overview.of.the.dbus.interface"></a>
 398 <h3>Overview of the dbus interface</h3>
 399
 400 <p><strong><em>afm-user-daemon</em></strong> takes its orders from the session instance
 401 of D-Bus. The use of D-Bus is great because it allows to implement
 402 discovery and signaling.</p>
 403
 404 <p>The dbus of the session is by default adressed by the environment
 405 variable <strong><em>DBUS_SESSION_BUS_ADDRESS</em></strong>. Using <strong>systemd</strong>
 406 the variable <em>DBUS_SESSION_BUS_ADDRESS</em> is automatically set for
 407 user sessions.</p>
 408
 409 <p>The <strong>afm-user-daemon</strong> is listening with the destination name
 410 <strong><em>org.AGL.afm.user</em></strong> at the object of path <strong><em>/org/AGL/afm/user</em></strong>
 411 on the interface <strong><em>org.AGL.afm.user</em></strong> for the below detailed
 412 members <strong><em>runnables</em></strong>, <strong><em>detail</em></strong>, <strong><em>start</em></strong>, <strong><em>terminate</em></strong>,
 413 <strong><em>stop</em></strong>, <strong><em>continue</em></strong>, <strong><em>runners</em></strong>, <strong><em>state</em></strong>,
 414 <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p>
 415
 416 <p>D-Bus is mainly used for signaling and discovery. Its optimized
 417 typed protocol is not used except for transmitting only one string
 418 in both directions.</p>
 419
 420 <p>The client and the service are using JSON serialisation to
 421 exchange data.</p>
 422
 423 <p>The D-Bus interface is defined by:</p>
 424
 425 <ul>
 426 <li><p>DESTINATION: <strong>org.AGL.afm.user</strong></p></li>
 427 <li><p>PATH: <strong>/org/AGL/afm/user</strong></p></li>
 428 <li><p>INTERFACE: <strong>org.AGL.afm.user</strong></p></li>
 429 </ul>
 430
 431
 432 <p>The signature of any member of the interface is <strong><em>string -> string</em></strong>
 433 for <strong><em>JSON -> JSON</em></strong>.</p>
 434
 435 <p>This is the normal case. In case of error, the current implmentation
 436 returns a dbus error that is a string.</p>
 437
 438 <p>Here is an example that use <em>dbus-send</em> to query data on
 439 installed applications.</p>
 440
 441 <pre><code>dbus-send --session --print-reply \
 442     --dest=org.AGL.afm.user \
 443     /org/AGL/afm/user \
 444     org.AGL.afm.user.runnables string:true
 445 </code></pre>
 446
 447 <a name="Using..strong..em.afm-util..em...strong."></a>
 448 <h3>Using <strong><em>afm-util</em></strong></h3>
 449
 450 <p>The command line tool <strong><em>afm-util</em></strong> uses dbus-send to send
 451 orders to <strong>afm-user-daemon</strong>. This small scripts allows to
 452 send command to <strong><em>afm-user-daemon</em></strong> either interactively
 453 at shell prompt or scriptically.</p>
 454
 455 <p>The syntax is simple: it accept a command and if the command
 456 requires it, the argument to the command.</p>
 457
 458 <p>Here is the summary of <strong><em>afm-util</em></strong>:</p>
 459
 460 <ul>
 461 <li><p><strong>afm-util runnables      </strong>:</p>
 462
 463 <p>list the runnable widgets installed</p></li>
 464 <li><p><strong>afm-util install    wgt </strong>:</p>
 465
 466 <p>install the wgt file</p></li>
 467 <li><p><strong>afm-util uninstall  id  </strong>:</p>
 468
 469 <p>remove the installed widget of id</p></li>
 470 <li><p><strong>afm-util detail     id  </strong>:</p>
 471
 472 <p>print detail about the installed widget of id</p></li>
 473 <li><p><strong>afm-util runners        </strong>:</p>
 474
 475 <p>list the running instance</p></li>
 476 <li><p><strong>afm-util start      id  </strong>:</p>
 477
 478 <p>start an instance of the widget of id</p></li>
 479 <li><p><strong>afm-util terminate  rid </strong>:</p>
 480
 481 <p>terminate the running instance rid</p></li>
 482 <li><p><strong>afm-util stop       rid </strong>:</p>
 483
 484 <p>stop the running instance rid</p></li>
 485 <li><p><strong>afm-util continue   rid </strong>:</p>
 486
 487 <p>continue the previously rid</p></li>
 488 <li><p><strong>afm-util state      rid </strong>:</p>
 489
 490 <p>get status of the running instance rid</p></li>
 491 </ul>
 492
 493
 494 <p>Here is how to list applications using <strong><em>afm-util</em></strong>:</p>
 495
 496 <pre><code>afm-util runnables
 497 </code></pre>
 498
 499 <hr />
 500
 501 <a name="The.protocol.over.D-Bus"></a>
 502 <h3>The protocol over D-Bus</h3>
 503
 504 <p>Recall:</p>
 505
 506 <ul>
 507 <li><p><strong>DESTINATION</strong>: org.AGL.afm.user</p></li>
 508 <li><p><strong>PATH</strong>: /org/AGL/afm/user</p></li>
 509 <li><p><strong>INTERFACE</strong>: org.AGL.afm.user</p></li>
 510 </ul>
 511
 512
 513 <hr />
 514
 515 <a name="Method.org.AGL.afm.user.detail"></a>
 516 <h4>Method org.AGL.afm.user.detail</h4>
 517
 518 <p><strong>Description</strong>: Get details about an application from its id.</p>
 519
 520 <p><strong>Input</strong>: the id of the application as below.</p>
 521
 522 <p>Either just a string:</p>
 523
 524 <pre><code>"appli@x.y"
 525 </code></pre>
 526
 527 <p>Or an object having the field &ldquo;id&rdquo; of type string:</p>
 528
 529 <pre><code>{"id":"appli@x.y"}
 530 </code></pre>
 531
 532 <p><strong>Output</strong>: A JSON object describing the application containing
 533 the fields described below.</p>
 534
 535 <pre><code>{
 536   "id":          string, the application id (id@version)
 537   "version":     string, the version of the application
 538   "width":       integer, requested width of the application
 539   "height":      integer, resqueted height of the application
 540   "name":        string, the name of the application
 541   "description": string, the description of the application
 542   "shortname":   string, the short name of the application
 543   "author":      string, the author of the application
 544 }
 545 </code></pre>
 546
 547 <hr />
 548
 549 <a name="Method.org.AGL.afm.user.runnables"></a>
 550 <h4>Method org.AGL.afm.user.runnables</h4>
 551
 552 <p><strong>Description</strong>: Get the list of applications that can be run.</p>
 553
 554 <p><strong>Input</strong>: any valid json entry, can be anything except null.</p>
 555
 556 <p><strong>output</strong>: An array of description of the runnable applications.
 557 Each item of the array contains an object containing the detail of
 558 an application as described above for the method
 559 <em>org.AGL.afm.user.detail</em>.</p>
 560
 561 <hr />
 562
 563 <a name="Method.org.AGL.afm.user.install"></a>
 564 <h4>Method org.AGL.afm.user.install</h4>
 565
 566 <p><strong>Description</strong>: Install an application from its widget file.</p>
 567
 568 <p>If an application of the same <em>id</em> and <em>version</em> exists, it is not
 569 reinstalled except if <em>force=true</em>.</p>
 570
 571 <p>Applications are installed in the subdirectories of the common directory
 572 of applications.
 573 If <em>root</em> is specified, the application is installed under the
 574 sub-directories of the <em>root</em> defined.</p>
 575
 576 <p>Note that this methods is a simple accessor to the method
 577 <strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>
 578
 579 <p>After the installation and before returning to the sender,
 580 <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p>
 581
 582 <p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly,
 583 a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p>
 584
 585 <p>Either just a string being the absolute path of the widget file:</p>
 586
 587 <pre><code>"/a/path/driving/to/the/widget"
 588 </code></pre>
 589
 590 <p>Or an object:</p>
 591
 592 <pre><code>{
 593   "wgt": "/a/path/to/the/widget",
 594   "force": false,
 595   "root": "/a/path/to/the/root"
 596 }
 597 </code></pre>
 598
 599 <p>&ldquo;wgt&rdquo; and &ldquo;root&rdquo; must be absolute paths.</p>
 600
 601 <p><strong>output</strong>: An object with the field &ldquo;added&rdquo; being the string for
 602 the id of the added application.</p>
 603
 604 <pre><code>{"added":"appli@x.y" }
 605 </code></pre>
 606
 607 <hr />
 608
 609 <a name="Method.org.AGL.afm.user.uninstall"></a>
 610 <h4>Method org.AGL.afm.user.uninstall</h4>
 611
 612 <p><strong>Description</strong>: Uninstall an application from its id.</p>
 613
 614 <p>Note that this methods is a simple accessor to the method
 615 <strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>
 616
 617 <p>After the uninstallation and before returning to the sender,
 618 <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p>
 619
 620 <p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to
 621 <em>root</em> of the application.</p>
 622
 623 <p>Either a string:</p>
 624
 625 <pre><code>"appli@x.y"
 626 </code></pre>
 627
 628 <p>Or an object:</p>
 629
 630 <pre><code>{
 631   "id": "appli@x.y",
 632   "root": "/a/path/to/the/root"
 633 }
 634 </code></pre>
 635
 636 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 637
 638 <hr />
 639
 640 <a name="Method.org.AGL.afm.user.start"></a>
 641 <h4>Method org.AGL.afm.user.start</h4>
 642
 643 <p><strong>Description</strong>:</p>
 644
 645 <p><strong>Input</strong>: the <em>id</em> of the application and, optionaly, the
 646 start <em>mode</em> as below.</p>
 647
 648 <p>Either just a string:</p>
 649
 650 <pre><code>"appli@x.y"
 651 </code></pre>
 652
 653 <p>Or an object having the field &ldquo;id&rdquo; of type string and
 654 optionaly a field mode:</p>
 655
 656 <pre><code>{"id":"appli@x.y","mode":"local"}
 657 </code></pre>
 658
 659 <p>The field &ldquo;mode&rdquo; as a string value being either &ldquo;local&rdquo; or &ldquo;remote&rdquo;.</p>
 660
 661 <p><strong>output</strong>: The <em>runid</em> of the application launched.
 662 The runid is an integer.</p>
 663
 664 <hr />
 665
 666 <a name="Method.org.AGL.afm.user.terminate"></a>
 667 <h4>Method org.AGL.afm.user.terminate</h4>
 668
 669 <p><strong>Description</strong>: Terminates the application of <em>runid</em>.</p>
 670
 671 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to terminate.</p>
 672
 673 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 674
 675 <hr />
 676
 677 <a name="Method.org.AGL.afm.user.stop"></a>
 678 <h4>Method org.AGL.afm.user.stop</h4>
 679
 680 <p><strong>Description</strong>: Stops the application of <em>runid</em> until terminate or continue.</p>
 681
 682 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to stop.</p>
 683
 684 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 685
 686 <hr />
 687
 688 <a name="Method.org.AGL.afm.user.continue"></a>
 689 <h4>Method org.AGL.afm.user.continue</h4>
 690
 691 <p><strong>Description</strong>: Continues the application of <em>runid</em> previously stopped.</p>
 692
 693 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to continue.</p>
 694
 695 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 696
 697 <hr />
 698
 699 <a name="Method.org.AGL.afm.user.state"></a>
 700 <h4>Method org.AGL.afm.user.state</h4>
 701
 702 <p><strong>Description</strong>: Get informations about a running instance of <em>runid</em>.</p>
 703
 704 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance inspected.</p>
 705
 706 <p><strong>output</strong>: An object describing the state of the instance. It contains:
 707 the runid (an integer), the id of the running application (a string),
 708 the state of the application (a string being either &ldquo;starting&rdquo;, &ldquo;running&rdquo;
 709 or &ldquo;stopped&rdquo;).</p>
 710
 711 <p>Example of returned state:</p>
 712
 713 <pre><code>{
 714   "runid": 2,
 715   "state": "running",
 716   "id": "appli@x.y"
 717 }
 718 </code></pre>
 719
 720 <hr />
 721
 722 <a name="Method.org.AGL.afm.user.runners"></a>
 723 <h4>Method org.AGL.afm.user.runners</h4>
 724
 725 <p><strong>Description</strong>: Get the list of the currently running instances.</p>
 726
 727 <p><strong>Input</strong>: anything.</p>
 728
 729 <p><strong>output</strong>: An array of states, one per running instance, as returned by
 730 the methodd <strong><em>org.AGL.afm.user.state</em></strong>.</p>
 731
 732 <a name="The.afb.plugin"></a>
 733 <h2>The afb plugin</h2>
 734
 735 <p>The base of the path is FWKAPI = /api/fwk</p>
 736
 737 <p>request FWKAPI/runnables
 738   &ndash; get the list of applications
 739   => [ APPDESC&hellip; ]</p>
 740
 741 <p>request FWKAPI/detail?id=APPID
 742   subject to languages tuning
 743   => { &ldquo;id&rdquo;: &ldquo;APPID&rdquo;, &ldquo;name&rdquo;: &ldquo;name&rdquo;, &ldquo;description&rdquo;: &ldquo;description&rdquo;, &ldquo;license&rdquo;: &ldquo;license&rdquo;, &ldquo;author&rdquo;: &ldquo;author&rdquo; }</p>
 744
 745 <p>/<em>
 746 request FWKAPI/icon?id=APPID
 747   subject to languages tuning
 748   => the icon image
 749 </em>/</p>
 750
 751 <p>request FWKAPI/run?id=APPID
 752   => { &ldquo;status&rdquo;: &ldquo;done/error&rdquo;, &ldquo;data&rdquo;: { &ldquo;runid&rdquo;: &ldquo;RUNID&rdquo; } }</p>
 753
 754 <p>request FWKAPI/running
 755   => [ { &ldquo;id&rdquo;: &ldquo;RUNID&rdquo;, &ldquo;appid&rdquo;: &ldquo;APPID&rdquo;, &ldquo;state&rdquo;: &hellip; }&hellip; ]</p>
 756
 757 <p>request FWKAPI/state?id=RUNID
 758   => { &ldquo;id&rdquo;: &ldquo;RUNID&rdquo;, &ldquo;appid&rdquo;: &ldquo;APPID&rdquo;, &ldquo;state&rdquo;: &hellip; }</p>
 759
 760 <p>request FWKAPI/stop?id=RUNID
 761   => { &ldquo;error&rdquo;: &ldquo;message&rdquo; ou &ldquo;done&rdquo;: &ldquo;RUNID&rdquo; }</p>
 762
 763 <p>request FWKAPI/suspend?id=RUNID
 764   => { &ldquo;error&rdquo;: &ldquo;message&rdquo; ou &ldquo;done&rdquo;: &ldquo;RUNID&rdquo; }</p>
 765
 766 <p>request FWKAPI/resume?id=RUNID
 767   => { &ldquo;error&rdquo;: &ldquo;message&rdquo; ou &ldquo;done&rdquo;: &ldquo;RUNID&rdquo; }</p>
 768
 769 <p>/*
 770 request FWKAPI/features
 771   => returns the features of the current application</p>
 772
 773 <p>request FWKAPI/preferences
 774   => returns the features of the current application
 775 */</p>
 776 </body>
 777 </html>