Attachment 43966 Details for Bug 34869 – Proposed addition

[patch] Proposed addition

dbus-objectmanager-spec-additions.patch (text/plain), 4.61 KB, created by David Zeuthen (not reading bugmail) on 2011-03-01 07:05:35 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: David Zeuthen (not reading bugmail)

Created: 2011-03-01 07:05:35 UTC

Size: 4.61 KB

patch

obsolete

>diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
>index ee5aac5..806747f 100644
>--- a/doc/dbus-specification.xml
>+++ b/doc/dbus-specification.xml
>@@ -2981,6 +2981,90 @@
>         annotation.
>       </para>
>     </sect2>
>+
>+    <sect2 id="standard-interfaces-objectmanager">
>+      <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
>+      <para>
>+        An application can optionally make use of this interface to
>+        export one or more sub-trees of objects. The root of the
>+        sub-tree implements this interface so other applications can
>+        get all objects, interfaces and properties in a single method
>+        call:
>+      </para>
>+      <para>
>+        <programlisting>
>+          org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT&lt;OBJPATH,DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);
>+        </programlisting>
>+      </para>
>+      <para>
>+        The return value of this method is a dict whose keys are
>+        object paths. All returned object paths are children of the
>+        object path implementing this interface. Each value is a dict
>+        whose keys are interfaces names and values are another dict
>+        containing the properties (see <xref
>+        linkend="standard-interfaces-properties"/>) for each interface
>+        and object path in question that the
>+        <literal>org.freedesktop.DBus.Properties.GetAll</literal>
>+        method would return. If an interface has no properties, the
>+        empty dict is returned.
>+      </para>
>+      <para>
>+        Changes are emitted using the following two signals:
>+      </para>
>+      <para>
>+        <programlisting>
>+          org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path,
>+                                                              DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt; interfaces_and_properties);
>+          org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path,
>+                                                                ARRAY&lt;STRING&gt; interfaces);
>+        </programlisting>
>+      </para>
>+      <para>
>+        The <literal>InterfacesAdded</literal> signal is emitted when
>+        either a new object is added or if an existing object gains
>+        one or more interfaces while the
>+        <literal>InterfacesRemoved</literal> signal is emitted
>+        whenever an object is removed or it loses one or more
>+        interfaces. The second parameter of the
>+        <literal>InterfacesAdded</literal> signal contains a dict with
>+        the interfaces and properties (if any) that has been added to
>+        the given object path. Similarly, the second parameter of the
>+        <literal>InterfacesRemoved</literal> signal contains an array
>+        of the interfaces that was removed. Note that changes on
>+        properties on existing interfaces are not reported using this
>+        interface - an application should use the
>+        <literal>PropertiesChanged</literal> signal on each object.
>+      </para>
>+      <para>
>+        Applications SHOULD NOT export objects that are children of an
>+        object (directly or otherwise) implementing this interface but
>+        which are not returned in the reply from the
>+        <literal>GetAll()</literal> method of this interface on the
>+        given object.
>+      </para>
>+      <para>
>+        The intent of the <literal>ObjectManager</literal> interface is to make it easy to write a robust client implementation. The trivial client implementation only needs to make two method calls:
>+      </para>
>+      <para>
>+        <programlisting>
>+          org.freedesktop.DBus.AddMatch (bus_proxy,
>+                                         "type='signal',name='org.example.App',path_prefix='/org/example/App'");
>+          objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy);
>+        </programlisting>
>+      </para>
>+      <para>
>+        on respectively the message bus and the remote
>+        application. Whenever a new remote object is created (or an
>+        existing object gains a new interface), the
>+        <literal>InterfacesAdded</literal> signal is emitted and since
>+        this signal contains all properties for the interfaces, no
>+        calls to the <literal>org.freedesktop.Properties</literal>
>+        interface on the remote object is needed. Additionally, since
>+        the initial <literal>AddMatch()</literal> rule already include
>+        signal messages from the newly created child object, no new
>+        <literal>AddMatch()</literal> call is needed.
>+      </para>
>+    </sect2>
>   </sect1>
> 
>   <sect1 id="introspection-format">

Actions: View | Splinter Review

Attachments on bug 34869: 43966 | 43967 | 44236 | 45395 | 45484 | 45558 | 45559

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.