afm-user-daemon: Adds method "once"

[src/app-framework-main.git] / docs / afm-user-daemon.md

diff --git a/docs/afm-user-daemon.md b/docs/afm-user-daemon.md
index f1ce7f8..37cf0e4 100644 (file)
--- a/docs/afm-user-daemon.md
+++ b/docs/afm-user-daemon.md
@@ -24,8 +24,7 @@ applications on behalf of a user. Its main tasks are:
 
  - list current runnable or running applications
 
- - stop (aka pause), continue (aka resume), terminate
-   a running instance of a given application
+ - pause, resume, terminate a running instance of a given application
 
  - transfer requests for installation/uninstallation
    of applications to the corresponding system daemon
@@ -115,8 +114,8 @@ that it launched.
 
 When owning the right permissions, a client can get the list
 of running instances and details about a specific
-running instance. It can also terminates, stops or
-continues a given application.
+running instance. It can also terminate, pause or
+resume a given application.
 
 ### Installing and uninstalling applications ###
 
@@ -399,8 +398,8 @@ user sessions.
 The **afm-user-daemon** is listening on destination name
 ***org.AGL.afm.user*** at object path ***/org/AGL/afm/user***
 on interface ***org.AGL.afm.user*** for following members:
- ***runnables***, ***detail***, ***start***, ***terminate***,
-***stop***, ***continue***, ***runners***, ***state***,
+ ***runnables***, ***detail***, ***start***, ***once***, ***terminate***,
+***pause***, ***resume***, ***runners***, ***state***,
 ***install*** and ***uninstall***.
 
 D-Bus is mainly used for signaling and discovery. Its optimized
@@ -465,17 +464,21 @@ Here is the summary of ***afm-util***:
 
    start an instance of the widget of id
 
+ - **afm-util once      id  **:
+
+   run once an instance of the widget of id
+
  - **afm-util terminate  rid **:
 
    terminate the running instance rid
 
- - **afm-util stop       rid **:
+ - **afm-util pause       rid **:
 
-   stop the running instance rid
+   pause the running instance rid
 
- - **afm-util continue   rid **:
+ - **afm-util resume   rid **:
 
-   continue the previously rid
+   resume the previously paused rid
 
  - **afm-util state      rid **:
 
@@ -635,6 +638,26 @@ The field "mode" is a string equal to either "local" or "remote".
 
 ---
 
+#### Method org.AGL.afm.user.once
+
+**Description**:
+
+**Input**: the *id* of the application
+
+Either just a string:
+
+    "appli@x.y"
+
+Or an object containing field "id" of type string.
+
+    {"id":"appli@x.y"}
+
+**output**: The *state* of the application retrieved or launched.
+See *org.AGL.afm.user.state* to get a description of the returned
+object.
+
+---
+
 #### Method org.AGL.afm.user.terminate
 
 **Description**: Terminates the application attached to *runid*.
@@ -647,19 +670,37 @@ The field "mode" is a string equal to either "local" or "remote".
 
 #### Method org.AGL.afm.user.stop
 
-**Description**: Stops the application attached to *runid* until terminate or continue.
+Obsolete since 8th November 2016 (2016/11/08).
+Kept for compatibility.
+
+Use **org.AGL.afm.user.pause** instead.
+
+---
+
+#### Method org.AGL.afm.user.continue
+
+Obsolete since 8th November 2016 (2016/11/08).
+Kept for compatibility.
+
+Use **org.AGL.afm.user.resume** instead.
+
+---
 
-**Input**: The *runid* (integer) of the running instance to stop.
+#### Method org.AGL.afm.user.pause
+
+**Description**: Pauses the application attached to *runid* until terminate or resume.
+
+**Input**: The *runid* (integer) of the running instance to pause.
 
 **output**: the value 'true'.
 
 ---
 
-#### Method org.AGL.afm.user.continue
+#### Method org.AGL.afm.user.resume
 
-**Description**: Continues the application attached to *runid* previously stopped.
+**Description**: Resumes the application attached to *runid* previously paused.
 
-**Input**: The *runid* (integer) of the running instance to continue.
+**Input**: The *runid* (integer) of the running instance to resume.
 
 **output**: the value 'true'.
 
@@ -672,13 +713,15 @@ The field "mode" is a string equal to either "local" or "remote".
 **Input**: The *runid* (integer) of the running instance inspected.
 
 **output**: An object describing instance state. It contains:
-the runid (integer), the id of the running application (string),
-the state of the application (string either: "starting", "running", "stopped").
+the runid (integer), the pids of the processes as an array starting
+with the group leader, the id of the running application (string),
+the state of the application (string either: "starting", "running", "paused").
 
 Example of returned state:
 
     {
       "runid": 2,
+      "pids": [ 435, 436 ],
       "state": "running",
       "id": "appli@x.y"
     }