fdo-mirrors/dbus
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/dbus/dbus.git synced 2026-05-05 13:28:02 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add an extra parameter to the PropertiesChanged() signal

Browse source 
It was pointed out on the mailing list that it would be useful to know
that a given property has changed without conveying its value. Because
without this parameter a true_no_value property could change, however
there is no way for a client-side proxy to know _what_ property it was
(only that some property changed).

With the parameter, however, a client-side proxy can reliably discard
a cached property value.

Also rename the "true_no_value" to "invalidates" as the spec is now
using this language.

Also allow using the annotation in the enclosed interface name.

Also rename the annotation name so it uses Property in its name
instead of Properties. This is to be more consistent with the existing
org.freedesktop.DBus.Method.NoReply annotation which uses Method, not
Methods.

Signed-off-by: David Zeuthen <davidz@redhat.com>
This commit is contained in:
David Zeuthen 2010-05-13 10:25:22 -04:00
parent 2541e86615
commit f8729bc864
1 changed files with 42 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
doc/dbus-specification.xml
View file

@ -2765,21 +2765,29 @@
<para>
<programlisting>
org.freedesktop.DBus.Properties.PropertiesChanged (STRING interface_name,
DICT&lt;STRING,VARIANT&gt; changed_properties);
DICT&lt;STRING,VARIANT&gt; changed_properties,
ARRAY&lt;STRING&gt; invalidated_properties);
</programlisting>
</para>
<para>
where <literal>changed_properties</literal> is a dictionary
containing the changed properties and the new values.
containing the changed properties with the new values and
<literal>invalidated_properties</literal> is an array of
properties that changed but the value is not conveyed.
</para>
<para>
Whether the <literal>PropertiesChanged</literal> signal is
supported can be determined by calling
<literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. If
the signal is supported for an object but not used for one or
more properties (for e.g. performance reasons), each such
property must be annotated with the
<literal>org.freedesktop.DBus.Properties.EmitsChangedSignal</literal>
<literal>org.freedesktop.DBus.Introspectable.Introspect</literal>. Note
that the signal may be supported for an object but it may
differ how whether and how it is used on a per-property basis
(for e.g. performance or security reasons). Each property (or
the parent interface) must be annotated with the
<literal>org.freedesktop.DBus.Property.EmitsChangedSignal</literal>
annotation to convey this (usually the default value
<literal>true</literal> is sufficient meaning that the
annotation does not need to be used). See <xref
linkend="introspection-format"/> for details on this
annotation.
</para>
</sect2>
@ -2913,9 +2921,33 @@
<entry>If set, don't expect a reply to the method call; defaults to false.</entry>
</row>
<row>
<entry>org.freedesktop.DBus.Properties.EmitsChangedSignal</entry>
<entry>true,true_no_value,false</entry>
<entry>If set to false, the <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal> signal, see <xref linkend="standard-interfaces-properties"/>, is not emitted if the property changes. If set to true_no_value the signal is emitted but the value is no included in the signal. Defaults to true.</entry>
<entry>org.freedesktop.DBus.Property.EmitsChangedSignal</entry>
<entry>true,invalidates,false</entry>
<entry>
<para>
If set to <literal>false</literal>, the
<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
signal, see <xref
linkend="standard-interfaces-properties"/> is not
guaranteed to be emitted if the property changes.
</para>
<para>
If set to <literal>invalidates</literal> the signal
is emitted but the value is not included in the
signal.
</para>
<para>
If set to <literal>true</literal> the signal is
emitted with the value included.
</para>
<para>
The value for the annotation defaults to
<literal>true</literal> if the enclosing interface
element does not specify the annotation. Otherwise it
defaults to the value specified in the enclosing
interface element.
</para>
</entry>
</row>
</tbody>
</tgroup>