man: update D-Bus docs with new calls

diff --git a/man/org.freedesktop.home1.xml b/man/org.freedesktop.home1.xml
index 7c604d2e0c1d0c22810b0ec3d28a6e46d354fbe9..b1bb6587dc449a881d280587e744c518500596e9 100644 (file)
--- a/man/org.freedesktop.home1.xml
+++ b/man/org.freedesktop.home1.xml
@@ -63,9 +63,10 @@ node /org/freedesktop/home1 {
                          out b incomplete,
                          out o bus_path);
       ListHomes(out a(susussso) home_areas);
-      @org.freedesktop.systemd1.Privileged("true")
       ActivateHome(in  s user_name,
                    in  s secret);
+      ActivateHomeIfReferenced(in  s user_name,
+                               in  s secret);
       @org.freedesktop.systemd1.Privileged("true")
       DeactivateHome(in  s user_name);
       RegisterHome(in  s user_record);
@@ -100,6 +101,10 @@ node /org/freedesktop/home1 {
               in  b please_suspend,
               out h send_fd);
       @org.freedesktop.systemd1.Privileged("true")
+      RefHomeUnrestricted(in  s user_name,
+                          in  b please_suspend,
+                          out h send_fd);
+      @org.freedesktop.systemd1.Privileged("true")
       ReleaseHome(in  s user_name);
       InhibitSuspendHome(in  s user_name,
                          out h send_fd);
@@ -136,6 +141,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="ActivateHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ActivateHomeIfReferenced()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="DeactivateHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="RegisterHome()"/>
@@ -166,6 +173,8 @@ node /org/freedesktop/home1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="RefHome()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="RefHomeUnrestricted()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="ReleaseHome()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspendHome()"/>
@@ -224,6 +233,11 @@ node /org/freedesktop/home1 {
       <classname>org.freedesktop.home1.Home</classname> interface documented below, but may be called on the
       manager object and takes a user name as additional argument, instead.</para>
 
+      <para><function>ActivateHomeIfReferenced()</function> is identical to
+      <function>ActivateHome()</function>. However, the call only succeeds if the home directory is currently
+      referenced. Useful in conjunction with <function>RefHomeUnrestricted()</function>, which allows
+      creating a reference to a home directory even if the home directory is not active.</para>
+
       <para><function>DeactivateHome()</function> deactivates (i.e. unmounts) the home directory of the
       specified user. It is equivalent to the <function>Deactivate()</function> method on the
       <classname>org.freedesktop.home1.Home</classname> interface documented below.</para>
@@ -355,6 +369,10 @@ node /org/freedesktop/home1 {
       <function>Ref()</function> on the <classname>org.freedesktop.home1.Home</classname>
       interface.</para>
 
+      <para><function>RefHomeUnrestricted()</function> is identical to <function>RefHome()</function> but
+      succeeds even if the home area is not active currently. This is useful on conjunction with
+      <function>ActivateHomeIfReferenced()</function>.</para>
+
       <para><function>ReleaseHome()</function> releases a home directory again, if all file descriptors
       referencing it are already closed, that where acquired through <function>AcquireHome()</function> or
       <function>RefHome()</function>. Note that this call does not actually cause the deactivation of the
@@ -409,8 +427,8 @@ node /org/freedesktop/home1 {
 node /org/freedesktop/home1/home {
   interface org.freedesktop.home1.Home {
     methods:
-      @org.freedesktop.systemd1.Privileged("true")
       Activate(in  s secret);
+      ActivateIfReferenced(in  s secret);
       @org.freedesktop.systemd1.Privileged("true")
       Deactivate();
       Unregister();
@@ -436,6 +454,9 @@ node /org/freedesktop/home1/home {
       Ref(in  b please_suspend,
           out h send_fd);
       @org.freedesktop.systemd1.Privileged("true")
+      RefUnrestricted(in  b please_suspend,
+                      out h send_fd);
+      @org.freedesktop.systemd1.Privileged("true")
       Release();
       InhibitSuspend(out h send_fd);
     properties:
@@ -467,6 +488,8 @@ node /org/freedesktop/home1/home {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Activate()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="ActivateIfReferenced()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Deactivate()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="Unregister()"/>
@@ -493,6 +516,8 @@ node /org/freedesktop/home1/home {
 
     <variablelist class="dbus-method" generated="True" extra-ref="Ref()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="RefUnrestricted()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="Release()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="InhibitSuspend()"/>
@@ -512,12 +537,13 @@ node /org/freedesktop/home1/home {
     <refsect2>
       <title>Methods</title>
 
-      <para><function>Activate()</function>, <function>Deactivate()</function>,
-      <function>Unregister()</function>, <function>Realize()</function>, <function>Remove()</function>,
-      <function>Fixate()</function>, <function>Authenticate()</function>, <function>Update()</function>,
-      <function>Resize()</function>, <function>ChangePassword()</function>, <function>Lock()</function>,
-      <function>Unlock()</function>, <function>Acquire()</function>, <function>Ref()</function>,
-      <function>Release()</function>, <function>InhibitSuspend()</function> operate like their matching counterparts on the
+      <para><function>Activate()</function>, <function>ActivateIfReferenced()</function>,
+      <function>Deactivate()</function>, <function>Unregister()</function>, <function>Realize()</function>,
+      <function>Remove()</function>, <function>Fixate()</function>, <function>Authenticate()</function>,
+      <function>Update()</function>, <function>Resize()</function>, <function>ChangePassword()</function>,
+      <function>Lock()</function>, <function>Unlock()</function>, <function>Acquire()</function>,
+      <function>Ref()</function>, <function>RefUnrestricted()</function>, <function>Release()</function>,
+      <function>InhibitSuspend()</function> operate like their matching counterparts on the
       <classname>org.freedesktop.home1.Manager</classname> interface (see above). The main difference is that
       they are methods of the home directory objects, and hence carry no additional user name
       parameter. Which of the two flavors of methods to call depends on the handles to the user known on the
@@ -549,11 +575,11 @@ node /org/freedesktop/home1/home {
     <title>History</title>
     <refsect2>
       <title>The Manager Object</title>
-      <para><function>InhibitSuspendHome()</function> was added in version 256.</para>
+      <para><function>InhibitSuspendHome()</function>, <function>ActivateHomeIfReferenced()</function>, <function>RefHomeUnrestricted()</function> wer added in version 256.</para>
     </refsect2>
     <refsect2>
       <title>Home Objects</title>
-      <para><function>InhibitSuspend()</function> was added in version 256.</para>
+      <para><function>InhibitSuspend()</function>, <function>ActivateIfReferenced()</function> and <function>RefUnrestricted()</function> were added in version 256.</para>
     </refsect2>
   </refsect1>
 

diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index ea466531607475c96c6b83defaa2338e5b24f930..dffd16e325639f254c0502775ed50d6b10915960 100644 (file)
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -1146,6 +1146,7 @@ node /org/freedesktop/login1/session/1 {
       TakeControl(in  b force);
       ReleaseControl();
       SetType(in  s type);
+      SetClass(in  s class);
       SetDisplay(in  s display);
       SetTTY(in  h tty_fd);
       TakeDevice(in  u major,
@@ -1242,6 +1243,8 @@ node /org/freedesktop/login1/session/1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="SetType()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="SetClass()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="SetDisplay()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="SetTTY()"/>
@@ -1342,6 +1345,12 @@ node /org/freedesktop/login1/session/1 {
       connection. This should help prevent a session from entering an inconsistent state, for example if the
       controller crashes. The only argument <varname>type</varname> is the new session type.</para>
 
+      <para><function>SetClass()</function> allows the caller to change the class of the session dynamically.
+      It may only be called by session's owening user. Currently, this call may be exclusively used to change
+      the class from <literal>user-incomplete</literal> to <literal>user</literal>. The call is synchronous,
+      and will return only once the user's service manager has successfully been started, if necessary. The
+      only argument <varname>type</varname> is the new session type.</para>
+
       <para><function>SetDisplay()</function> allows the display name of the graphical session to be changed. This is
       useful if the display server is started as part of the session. It can only be called by session's current
       controller. If <function>TakeControl()</function> has not been called, this method will fail. The only argument
@@ -1578,6 +1587,7 @@ node /org/freedesktop/login1/session/1 {
       <title>Session Objects</title>
       <para><function>SetDisplay()</function> was added in version 252.</para>
       <para><function>SetTTY()</function> was added in version 254.</para>
+      <para><function>SetClass()</function> was added in version 256.</para>
     </refsect2>
   </refsect1>
 </refentry>