Add LUCHandler1 API docs, rename "Content" property to "LastUserContext"

diff --git a/luc-handler/luc-handler-dbus.xml b/luc-handler/luc-handler-dbus.xml
index 0578caa..dd44e37 100644 (file)
--- a/luc-handler/luc-handler-dbus.xml
+++ b/luc-handler/luc-handler-dbus.xml
@@ -3,16 +3,62 @@
   <!--
     org.genivi.LUCHandler1:
     @short_description: Interface for managing the GENIVI LUC (Last User Context)
+
+    The GENIVI LUC Handler remembers applications that were used in the last
+    session of a user. It is used by other components such as the boot manager
+    in order to restore these applications on the next start-up.
+
+    The LUC Handler is a passive component in the sense that it does not
+    remember applications on its own; instead, applications need to register
+    and deregister themselves proactively.
+
+    Applications can be registered for different LUC types, the standard ones
+    being "foreground", "background" and "audible".
   -->
   <interface name="org.genivi.LUCHandler1">
+    <!--
+      Register:
+      @apps: A dictionary that maps LUC types to arrays of application unit names.
+
+      Registers one or more applications for certain LUC types. Applications may
+      be listed multiple times. For LUC types where only a single application may
+      be registered at a time, the last application in the corresponding list wins.
+
+      An example for the apps parameter would be:
+
+        {
+          "foreground": [ "app1.unit" ],
+          "background": [ "app2.unit", "app3.unit" ],
+          "audible": [ "app3.unit" ]
+        }
+
+    -->
     <method name="Register">
       <annotation name="org.freedesktop.DBus.GLib.Async" value="true"/>
       <arg name="apps" type="a{sas}" direction="in"/>
     </method>
+
+    <!--
+      Deregister:
+      @apps: A dictionary that maps LUC types to arrays of application unit names.
+
+      Removes one or multiple applications from the LUC. It is the exact opposite
+      of the Register() method.
+    -->
     <method name="Deregister">
       <annotation name="org.freedesktop.DBus.GLib.Async" value="true"/>
       <arg name="apps" type="a{sas}" direction="in"/>
     </method>
-    <property name="Content" type="a{sas}" access="read"/>
+
+    <!--
+      LastUserContext:
+
+      The current Last User Context, that is, a dictionary that maps LUC types
+      to arrays of one or more applications registered for each of them.
+
+      This property is read-only as it is supposed to be modified only through
+      Register() and Deregister() method calls.
+    -->
+    <property name="LastUserContext" type="a{sas}" access="read"/>
   </interface>
 </node>

diff --git a/luc-handler/luc-handler-service.c b/luc-handler/luc-handler-service.c
index 61303ab..0c7de47 100644 (file)
--- a/luc-handler/luc-handler-service.c
+++ b/luc-handler/luc-handler-service.c
@@ -94,8 +94,8 @@ luc_handler_service_init (LUCHandlerService *service)
 {
   service->interface = luc_handler_skeleton_new ();
 
-  /* TODO read LUC content from disk and set the "content" property of the 
-   * skeleton instance */
+  /* TODO read LastUserContext from disk and set the "last-user-context" property
+   * of the skeleton instance */
 
   g_signal_connect (service->interface, "handle-register",
                     G_CALLBACK (luc_handler_service_handle_register),
@@ -185,8 +185,8 @@ luc_handler_service_handle_register (LUCHandler            *object,
 
   g_debug ("Register called:");
 
-  /* TODO read the apps parameter and update the "content" property of
-   * the skeleton */
+  /* TODO read the apps parameter and update the "last-user-context" property
+   * of the skeleton */
 
   foreground_apps = g_variant_lookup_value (apps, "foreground",
                                             G_VARIANT_TYPE_STRING_ARRAY);
@@ -218,8 +218,8 @@ luc_handler_service_handle_deregister (LUCHandler            *object,
 
   g_debug ("Deregister called");
 
-  /* TODO read the apps parameter and update the "content" property of
-   * the skeleton */
+  /* TODO read the apps parameter and update the "last-user-context" property
+   * of the skeleton */
 
   g_dbus_method_invocation_return_value (invocation, NULL);