From 82b32b997c51e259ddf66a0ec6bd7631b0ea781d Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@gnome.org>
Date: Thu, 20 Feb 2025 18:15:43 +0000
Subject: [PATCH] docs: Clarify that login1 signals are not emitted for
 convenience objects
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

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>
---
 man/org.freedesktop.login1.xml | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/man/org.freedesktop.login1.xml b/man/org.freedesktop.login1.xml
index 1e28d4a6466..32734b01c0b 100644
--- 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>
-- 
2.47.3