spec: introduce new value "const" for EmitsChangedSignal annotation

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=72958
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 2b8d1f5..71a8987 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3950,7 +3950,7 @@
            </row>
            <row>
              <entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
-             <entry>true,invalidates,false</entry>
+             <entry>true,invalidates,const,false</entry>
              <entry>
                <para>
                  If set to <literal>false</literal>, the
@@ -3960,6 +3960,12 @@
                  guaranteed to be emitted if the property changes.
                </para>
                <para>
+                 If set to <literal>const</literal> the property never
+                 changes value during the lifetime of the object it
+                 belongs to, and hence the signal is never emitted for
+                 it.
+               </para>
+               <para>
                  If set to <literal>invalidates</literal> the signal
                  is emitted but the value is not included in the
                  signal.
@@ -3975,6 +3981,17 @@
                  defaults to the value specified in the enclosing
                  interface element.
                </para>
+               <para>
+                 This annotation is intended to be used by code
+                 generators to implement client-side caching of
+                 property values. For all properties for which the
+                 annotation is set to <literal>const</literal>,
+                 <literal>invalidates</literal> or
+                 <literal>true</literal> the client may
+                 unconditionally cache the values as the properties
+                 don't change or notifications are generated for them
+                 if they do.
+               </para>
              </entry>
            </row>
          </tbody>