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:    15 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      Can be repeated.
 156
 157 -r
 158 --root directory
 159
 160      Includes the root application directory to
 161      the database base of applications.
 162
 163      Note that the default root directory for
 164      applications is always added. It is defined
 165      to be /usr/share/afm/applications (may change).
 166
 167      Can be repeated.
 168
 169 -m
 170 --mode (local|remote)
 171
 172      Set the default launch mode.
 173      The default value is 'local'
 174
 175 -d
 176 --daemon
 177
 178      Daemonizes the process. It is not needed by sytemd.
 179
 180 -q
 181 --quiet
 182
 183      Reduces the verbosity (can be repeated).
 184
 185 -v
 186 --verbose
 187
 188      Increases the verbosity (can be repeated).
 189
 190 -h
 191 --help
 192
 193      Prints a short help.
 194 </code></pre>
 195
 196 <a name="Configuration.of.the.launcher"></a>
 197 <h2>Configuration of the launcher</h2>
 198
 199 <p>It contains rules for launching applications.
 200 When <strong>afm-user-daemon</strong> need to launch an application,
 201 it looks to the mode of launch, local or remote, and the
 202 type of the application as given by the file <strong><em>config.xml</em></strong>
 203 of the widget.</p>
 204
 205 <p>This couple mode and type allows to select the rule.</p>
 206
 207 <p>The configuration file is <strong>/etc/afm/afm-launch.conf</strong>.</p>
 208
 209 <p>It contains sections and rules. It can also contain comments
 210 and empty lines to improve the readability.</p>
 211
 212 <p>The separators are space and tabulation, any other character
 213 is meaning something.</p>
 214
 215 <p>The format is line oriented.
 216 The new line character separate the lines.</p>
 217
 218 <p>Lines having only separators are blank lines and are skipped.
 219 Line having the character # (sharp) as first not separator character
 220 are comment lines and are ignored.</p>
 221
 222 <p>Lines starting with a not separator character are differents
 223 of lines starting with a separator character.</p>
 224
 225 <p>The grammar of the configuration file is defined below:</p>
 226
 227 <pre><code>CONF: *COMMENT *SECTION
 228
 229 SECTION: MODE *RULE
 230
 231 RULE: +TYPE VECTOR ?VECTOR
 232
 233 MODE: 'mode' +SEP ('local' | 'remote') *SEP EOL
 234
 235 TYPE: DATA *SEP EOL
 236
 237 VECTOR: +SEP DATA *(+SEP NDATA) *SEP EOL
 238
 239 DATA: CHAR *NCHAR
 240 NDATA: +NCHAR
 241
 242 EOL: NL *COMMENT
 243 COMMENT: *SEP CMT *(SEP | NCHAR) NL
 244
 245 NL: '\x0a'
 246 SEP: '\x20' | '\x09'
 247 CMT: '#'
 248 CHAR: '\x00'..'\x08' | '\x0b'..'\x1f' | '\x21' | '\x22' | '\x24'..'\xff'
 249 NCHAR: CMT | CHAR
 250 </code></pre>
 251
 252 <p>Here is a sample of configuration file for defining how
 253 to launch an application declared of types <em>application/x-executable</em>,
 254 <em>text/x-shellscript</em> and <em>text/html</em> in mode local:</p>
 255
 256 <pre><code>mode local
 257
 258 application/x-executable
 259 text/x-shellscript
 260     %r/%c
 261
 262 text/html
 263     /usr/bin/afb-daemon --mode=local --readyfd=%R --alias=/icons:%I --port=%P --rootdir=%r --token=%S --sessiondir=%D/.afb-daemon
 264     /usr/bin/web-runtime http://localhost:%P/%c?token=%S
 265 </code></pre>
 266
 267 <p>This shows that:</p>
 268
 269 <ul>
 270 <li>within a section, several rules can be defined</li>
 271 <li>within a rule, several types can be defined</li>
 272 <li>within a rule, one or two vectors can be defined</li>
 273 <li>vectors are using %substitution</li>
 274 <li>launched binaries must be defined with their full path</li>
 275 </ul>
 276
 277
 278 <a name="mode.local"></a>
 279 <h3>mode local</h3>
 280
 281 <p>Within this mode, the launchers have either one or two vectors
 282 describing them. All of these vectors are treated as programs
 283 and are executed with the system call &lsquo;execve&rsquo;.</p>
 284
 285 <p>The first vector is the leader vector and it defines the process
 286 group. The second vector (if any) is attached to the group
 287 defined by this first vector.</p>
 288
 289 <a name="mode.remote"></a>
 290 <h3>mode remote</h3>
 291
 292 <p>Within this mode, the launchers have either one or two vectors
 293 describing them.</p>
 294
 295 <p>The first vector is treated as a program and is executed with
 296 the system call &lsquo;execve&rsquo;.</p>
 297
 298 <p>The second vector (if any) defines a text that is returned
 299 to the caller. This mechanism can be used to return the uri
 300 to connect to for executing the application remotely.</p>
 301
 302 <p>The daemon <strong><em>afm-user-daemon</em></strong> allocates a port for the
 303 running the application remotely.
 304 The current implmentation of the port allocation is just
 305 incremental.
 306 A more reliable (cacheable and same-originable) allocation
 307 is to be defined.</p>
 308
 309 <a name="L.substitutions"></a>
 310 <h3>%substitutions</h3>
 311
 312 <p>Vectors can include sequences of 2 characters that have a special
 313 meaning. These sequences are named <em>%substitution</em> because their
 314 first character is the percent sign (%) and because each occurrence
 315 of the sequence is replaced, at launch time, by the value associated
 316 to sequences.</p>
 317
 318 <p>Here is the list of <em>%substitutions</em>:</p>
 319
 320 <ul>
 321 <li><p><strong><em>%%</em></strong>: %.</p>
 322
 323 <p>This simply emits the percent sign %</p></li>
 324 <li><p><strong><em>%a</em></strong>: appid</p>
 325
 326 <p>This is the application Id of the launched application.</p>
 327
 328 <p>Defined by the attribute <strong>id</strong> of the element <strong><widget></strong>
 329 of <strong>config.xml</strong>.</p></li>
 330 <li><p><strong><em>%c</em></strong>: content</p>
 331
 332 <p>The file within the widget directory that is the entry point.</p>
 333
 334 <p>For a HTML application, it is the relative path to the main
 335 page (aka index.html).</p>
 336
 337 <p>Defined by the attribute <strong>src</strong> of the element <strong><content></strong>
 338 of <strong>config.xml</strong>.</p></li>
 339 <li><p><strong><em>%D</em></strong>: datadir</p>
 340
 341 <p>Path of the directory where the application runs (cwd)
 342 and stores its data.</p>
 343
 344 <p>It is equal to %h/%a.</p></li>
 345 <li><p><strong><em>%H</em></strong>: height</p>
 346
 347 <p>Requested height for the widget.</p>
 348
 349 <p>Defined by the attribute <strong>height</strong> of the element <strong><widget></strong>
 350 of <strong>config.xml</strong>.</p></li>
 351 <li><p><strong><em>%h</em></strong>: homedir</p>
 352
 353 <p>Path of the home directory for all applications.</p>
 354
 355 <p>It is generally equal to $HOME/app-data</p></li>
 356 <li><p><strong><em>%I</em></strong>: icondir</p>
 357
 358 <p>Path of the directory were the icons of the applications can be found.</p></li>
 359 <li><p><strong><em>%m</em></strong>: mime-type</p>
 360
 361 <p>Mime type of the launched application.</p>
 362
 363 <p>Defined by the attribute <strong>type</strong> of the element <strong><content></strong>
 364 of <strong>config.xml</strong>.</p></li>
 365 <li><p><strong><em>%n</em></strong>: name</p>
 366
 367 <p>Name of the application as defined by the content of the
 368 element <strong><name></strong> of <strong>config.xml</strong>.</p></li>
 369 <li><p><strong><em>%p</em></strong>: plugins</p>
 370
 371 <p>Unhandled until now.</p>
 372
 373 <p>Will be the colon separated list of plugins and plugins directory.</p></li>
 374 <li><p><strong><em>%P</em></strong>: port</p>
 375
 376 <p>A port to use. It is currently a kind of random port. The precise
 377 model is to be defined later.</p></li>
 378 <li><p><strong><em>%R</em></strong>: readyfd</p>
 379
 380 <p>Number of the file descriptor to use for signalling
 381 readyness of the launched process.</p></li>
 382 <li><p><strong><em>%r</em></strong>: rootdir</p>
 383
 384 <p>Path of the directory containing the widget and its data.</p></li>
 385 <li><p><strong><em>%S</em></strong>: secret</p>
 386
 387 <p>An hexadecimal number that can be used to pair the client
 388 with its server binder.</p></li>
 389 <li><p><strong><em>%W</em></strong>: width</p>
 390
 391 <p>Requested width for the widget.</p>
 392
 393 <p>Defined by the attribute <strong>width</strong> of the element <strong><widget></strong>
 394 of <strong>config.xml</strong>.</p></li>
 395 </ul>
 396
 397
 398 <a name="The.D-Bus.interface"></a>
 399 <h2>The D-Bus interface</h2>
 400
 401 <a name="Overview.of.the.dbus.interface"></a>
 402 <h3>Overview of the dbus interface</h3>
 403
 404 <p><strong><em>afm-user-daemon</em></strong> takes its orders from the session instance
 405 of D-Bus. The use of D-Bus is great because it allows to implement
 406 discovery and signaling.</p>
 407
 408 <p>The dbus of the session is by default adressed by the environment
 409 variable <strong><em>DBUS_SESSION_BUS_ADDRESS</em></strong>. Using <strong>systemd</strong>
 410 the variable <em>DBUS_SESSION_BUS_ADDRESS</em> is automatically set for
 411 user sessions.</p>
 412
 413 <p>The <strong>afm-user-daemon</strong> is listening with the destination name
 414 <strong><em>org.AGL.afm.user</em></strong> at the object of path <strong><em>/org/AGL/afm/user</em></strong>
 415 on the interface <strong><em>org.AGL.afm.user</em></strong> for the below detailed
 416 members <strong><em>runnables</em></strong>, <strong><em>detail</em></strong>, <strong><em>start</em></strong>, <strong><em>terminate</em></strong>,
 417 <strong><em>stop</em></strong>, <strong><em>continue</em></strong>, <strong><em>runners</em></strong>, <strong><em>state</em></strong>,
 418 <strong><em>install</em></strong> and <strong><em>uninstall</em></strong>.</p>
 419
 420 <p>D-Bus is mainly used for signaling and discovery. Its optimized
 421 typed protocol is not used except for transmitting only one string
 422 in both directions.</p>
 423
 424 <p>The client and the service are using JSON serialisation to
 425 exchange data.</p>
 426
 427 <p>The D-Bus interface is defined by:</p>
 428
 429 <ul>
 430 <li><p>DESTINATION: <strong>org.AGL.afm.user</strong></p></li>
 431 <li><p>PATH: <strong>/org/AGL/afm/user</strong></p></li>
 432 <li><p>INTERFACE: <strong>org.AGL.afm.user</strong></p></li>
 433 </ul>
 434
 435
 436 <p>The signature of any member of the interface is <strong><em>string -> string</em></strong>
 437 for <strong><em>JSON -> JSON</em></strong>.</p>
 438
 439 <p>This is the normal case. In case of error, the current implmentation
 440 returns a dbus error that is a string.</p>
 441
 442 <p>Here is an example that use <em>dbus-send</em> to query data on
 443 installed applications.</p>
 444
 445 <pre><code>dbus-send --session --print-reply \
 446     --dest=org.AGL.afm.user \
 447     /org/AGL/afm/user \
 448     org.AGL.afm.user.runnables string:true
 449 </code></pre>
 450
 451 <a name="Using..strong..em.afm-util..em...strong."></a>
 452 <h3>Using <strong><em>afm-util</em></strong></h3>
 453
 454 <p>The command line tool <strong><em>afm-util</em></strong> uses dbus-send to send
 455 orders to <strong>afm-user-daemon</strong>. This small scripts allows to
 456 send command to <strong><em>afm-user-daemon</em></strong> either interactively
 457 at shell prompt or scriptically.</p>
 458
 459 <p>The syntax is simple: it accept a command and if the command
 460 requires it, the argument to the command.</p>
 461
 462 <p>Here is the summary of <strong><em>afm-util</em></strong>:</p>
 463
 464 <ul>
 465 <li><p><strong>afm-util runnables      </strong>:</p>
 466
 467 <p>list the runnable widgets installed</p></li>
 468 <li><p><strong>afm-util install    wgt </strong>:</p>
 469
 470 <p>install the wgt file</p></li>
 471 <li><p><strong>afm-util uninstall  id  </strong>:</p>
 472
 473 <p>remove the installed widget of id</p></li>
 474 <li><p><strong>afm-util detail     id  </strong>:</p>
 475
 476 <p>print detail about the installed widget of id</p></li>
 477 <li><p><strong>afm-util runners        </strong>:</p>
 478
 479 <p>list the running instance</p></li>
 480 <li><p><strong>afm-util start      id  </strong>:</p>
 481
 482 <p>start an instance of the widget of id</p></li>
 483 <li><p><strong>afm-util terminate  rid </strong>:</p>
 484
 485 <p>terminate the running instance rid</p></li>
 486 <li><p><strong>afm-util stop       rid </strong>:</p>
 487
 488 <p>stop the running instance rid</p></li>
 489 <li><p><strong>afm-util continue   rid </strong>:</p>
 490
 491 <p>continue the previously rid</p></li>
 492 <li><p><strong>afm-util state      rid </strong>:</p>
 493
 494 <p>get status of the running instance rid</p></li>
 495 </ul>
 496
 497
 498 <p>Here is how to list applications using <strong><em>afm-util</em></strong>:</p>
 499
 500 <pre><code>afm-util runnables
 501 </code></pre>
 502
 503 <hr />
 504
 505 <a name="The.protocol.over.D-Bus"></a>
 506 <h3>The protocol over D-Bus</h3>
 507
 508 <p>Recall:</p>
 509
 510 <ul>
 511 <li><p><strong>DESTINATION</strong>: org.AGL.afm.user</p></li>
 512 <li><p><strong>PATH</strong>: /org/AGL/afm/user</p></li>
 513 <li><p><strong>INTERFACE</strong>: org.AGL.afm.user</p></li>
 514 </ul>
 515
 516
 517 <hr />
 518
 519 <a name="Method.org.AGL.afm.user.detail"></a>
 520 <h4>Method org.AGL.afm.user.detail</h4>
 521
 522 <p><strong>Description</strong>: Get details about an application from its id.</p>
 523
 524 <p><strong>Input</strong>: the id of the application as below.</p>
 525
 526 <p>Either just a string:</p>
 527
 528 <pre><code>"appli@x.y"
 529 </code></pre>
 530
 531 <p>Or an object having the field &ldquo;id&rdquo; of type string:</p>
 532
 533 <pre><code>{"id":"appli@x.y"}
 534 </code></pre>
 535
 536 <p><strong>Output</strong>: A JSON object describing the application containing
 537 the fields described below.</p>
 538
 539 <pre><code>{
 540   "id":          string, the application id (id@version)
 541   "version":     string, the version of the application
 542   "width":       integer, requested width of the application
 543   "height":      integer, resqueted height of the application
 544   "name":        string, the name of the application
 545   "description": string, the description of the application
 546   "shortname":   string, the short name of the application
 547   "author":      string, the author of the application
 548 }
 549 </code></pre>
 550
 551 <hr />
 552
 553 <a name="Method.org.AGL.afm.user.runnables"></a>
 554 <h4>Method org.AGL.afm.user.runnables</h4>
 555
 556 <p><strong>Description</strong>: Get the list of applications that can be run.</p>
 557
 558 <p><strong>Input</strong>: any valid json entry, can be anything except null.</p>
 559
 560 <p><strong>output</strong>: An array of description of the runnable applications.
 561 Each item of the array contains an object containing the detail of
 562 an application as described above for the method
 563 <em>org.AGL.afm.user.detail</em>.</p>
 564
 565 <hr />
 566
 567 <a name="Method.org.AGL.afm.user.install"></a>
 568 <h4>Method org.AGL.afm.user.install</h4>
 569
 570 <p><strong>Description</strong>: Install an application from its widget file.</p>
 571
 572 <p>If an application of the same <em>id</em> and <em>version</em> exists, it is not
 573 reinstalled except if <em>force=true</em>.</p>
 574
 575 <p>Applications are installed in the subdirectories of the common directory
 576 of applications.
 577 If <em>root</em> is specified, the application is installed under the
 578 sub-directories of the <em>root</em> defined.</p>
 579
 580 <p>Note that this methods is a simple accessor to the method
 581 <strong><em>org.AGL.afm.system.install</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>
 582
 583 <p>After the installation and before returning to the sender,
 584 <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p>
 585
 586 <p><strong>Input</strong>: The <em>path</em> of the widget file to install and, optionaly,
 587 a flag to <em>force</em> reinstallation, and, optionaly, a <em>root</em> directory.</p>
 588
 589 <p>Either just a string being the absolute path of the widget file:</p>
 590
 591 <pre><code>"/a/path/driving/to/the/widget"
 592 </code></pre>
 593
 594 <p>Or an object:</p>
 595
 596 <pre><code>{
 597   "wgt": "/a/path/to/the/widget",
 598   "force": false,
 599   "root": "/a/path/to/the/root"
 600 }
 601 </code></pre>
 602
 603 <p>&ldquo;wgt&rdquo; and &ldquo;root&rdquo; must be absolute paths.</p>
 604
 605 <p><strong>output</strong>: An object with the field &ldquo;added&rdquo; being the string for
 606 the id of the added application.</p>
 607
 608 <pre><code>{"added":"appli@x.y"}
 609 </code></pre>
 610
 611 <hr />
 612
 613 <a name="Method.org.AGL.afm.user.uninstall"></a>
 614 <h4>Method org.AGL.afm.user.uninstall</h4>
 615
 616 <p><strong>Description</strong>: Uninstall an application from its id.</p>
 617
 618 <p>Note that this methods is a simple accessor to the method
 619 <strong><em>org.AGL.afm.system.uninstall</em></strong> of <strong><em>afm-system-daemon</em></strong>.</p>
 620
 621 <p>After the uninstallation and before returning to the sender,
 622 <strong><em>afm-user-daemon</em></strong> sends the signal <strong><em>org.AGL.afm.user.changed</em></strong>.</p>
 623
 624 <p><strong>Input</strong>: the <em>id</em> of the application and, otpionaly, the path to
 625 <em>root</em> of the application.</p>
 626
 627 <p>Either a string:</p>
 628
 629 <pre><code>"appli@x.y"
 630 </code></pre>
 631
 632 <p>Or an object:</p>
 633
 634 <pre><code>{
 635   "id": "appli@x.y",
 636   "root": "/a/path/to/the/root"
 637 }
 638 </code></pre>
 639
 640 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 641
 642 <hr />
 643
 644 <a name="Method.org.AGL.afm.user.start"></a>
 645 <h4>Method org.AGL.afm.user.start</h4>
 646
 647 <p><strong>Description</strong>:</p>
 648
 649 <p><strong>Input</strong>: the <em>id</em> of the application and, optionaly, the
 650 start <em>mode</em> as below.</p>
 651
 652 <p>Either just a string:</p>
 653
 654 <pre><code>"appli@x.y"
 655 </code></pre>
 656
 657 <p>Or an object having the field &ldquo;id&rdquo; of type string and
 658 optionaly a field mode:</p>
 659
 660 <pre><code>{"id":"appli@x.y","mode":"local"}
 661 </code></pre>
 662
 663 <p>The field &ldquo;mode&rdquo; as a string value being either &ldquo;local&rdquo; or &ldquo;remote&rdquo;.</p>
 664
 665 <p><strong>output</strong>: The <em>runid</em> of the application launched.
 666 The runid is an integer.</p>
 667
 668 <hr />
 669
 670 <a name="Method.org.AGL.afm.user.terminate"></a>
 671 <h4>Method org.AGL.afm.user.terminate</h4>
 672
 673 <p><strong>Description</strong>: Terminates the application of <em>runid</em>.</p>
 674
 675 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to terminate.</p>
 676
 677 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 678
 679 <hr />
 680
 681 <a name="Method.org.AGL.afm.user.stop"></a>
 682 <h4>Method org.AGL.afm.user.stop</h4>
 683
 684 <p><strong>Description</strong>: Stops the application of <em>runid</em> until terminate or continue.</p>
 685
 686 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to stop.</p>
 687
 688 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 689
 690 <hr />
 691
 692 <a name="Method.org.AGL.afm.user.continue"></a>
 693 <h4>Method org.AGL.afm.user.continue</h4>
 694
 695 <p><strong>Description</strong>: Continues the application of <em>runid</em> previously stopped.</p>
 696
 697 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance to continue.</p>
 698
 699 <p><strong>output</strong>: the value &lsquo;true&rsquo;.</p>
 700
 701 <hr />
 702
 703 <a name="Method.org.AGL.afm.user.state"></a>
 704 <h4>Method org.AGL.afm.user.state</h4>
 705
 706 <p><strong>Description</strong>: Get informations about a running instance of <em>runid</em>.</p>
 707
 708 <p><strong>Input</strong>: The <em>runid</em> (an integer) of the running instance inspected.</p>
 709
 710 <p><strong>output</strong>: An object describing the state of the instance. It contains:
 711 the runid (an integer), the id of the running application (a string),
 712 the state of the application (a string being either &ldquo;starting&rdquo;, &ldquo;running&rdquo;
 713 or &ldquo;stopped&rdquo;).</p>
 714
 715 <p>Example of returned state:</p>
 716
 717 <pre><code>{
 718   "runid": 2,
 719   "state": "running",
 720   "id": "appli@x.y"
 721 }
 722 </code></pre>
 723
 724 <hr />
 725
 726 <a name="Method.org.AGL.afm.user.runners"></a>
 727 <h4>Method org.AGL.afm.user.runners</h4>
 728
 729 <p><strong>Description</strong>: Get the list of the currently running instances.</p>
 730
 731 <p><strong>Input</strong>: anything.</p>
 732
 733 <p><strong>output</strong>: An array of states, one per running instance, as returned by
 734 the methodd <strong><em>org.AGL.afm.user.state</em></strong>.</p>
 735 </body>
 736 </html>