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