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