docs: Clarify that login1 signals are not emitted for convenience objects

While this is obvious if you spend a few minutes thinking about how
D-Bus signals work (in this case, they are broadcast from a system
service, so cannot apply to a specific user/session/seat), it’s a bit
easy to overlook this while putting code together which uses the login1
D-Bus API, so it’s helpful to point this hazard out specifically in the
docs.

The signals can only be emitted on the canonical objects. The
convenience objects are useful for method calls, as the calling context
can be used to dereference ‘self’ and ‘auto’, but this can’t work for
signals.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index 1e28d4a6466bf9998149912c993310f306a6080e..32734b01c0b59cecc69e2f42e25ce88e640882ee 100644 (file)
--- a/man/org.freedesktop.login1.xml
+++ b/man/org.freedesktop.login1.xml
@@ -1002,6 +1002,11 @@ node /org/freedesktop/login1/seat/seat0 {
       <function>CanGraphical</function>, <function>CanTTY</function>,
       or the idle state changes, <function>PropertyChanged</function> signals are sent out to clients which
       have subscribed.</para>
+
+      <para>Signals are only emitted on objects referencing a specific seat ID, not on the
+      <literal>/org/freedesktop/login1/seat/self</literal> or
+      <literal>/org/freedesktop/login1/seat/auto</literal> convenience objects, as they can only be
+      dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>
@@ -1122,6 +1127,10 @@ node /org/freedesktop/login1/user/_1000 {
 
       <para>Whenever <varname>Sessions</varname> or the idle state changes,
       <function>PropertyChanged</function> signals are sent out to clients which have subscribed.</para>
+
+      <para>Signals are only emitted on objects referencing a specific UID, not on the
+      <literal>/org/freedesktop/login1/user/self</literal> convenience object, as <varname>self</varname>
+      can only be dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>
@@ -1483,6 +1492,11 @@ node /org/freedesktop/login1/session/1 {
       screen-locked/unlocked. A session manager of the session should listen to this signal and act
       accordingly. This signal is sent out as a result of the <function>Lock()</function> and
       <function>Unlock()</function> methods, respectively.</para>
+
+      <para>Signals are only emitted on objects referencing a specific session ID, not on the
+      <literal>/org/freedesktop/login1/session/self</literal> or
+      <literal>/org/freedesktop/login1/session/auto</literal> convenience objects, as they can only be
+      dereferenced relative to a method caller.</para>
     </refsect2>
 
     <refsect2>