From bc3c17245d049dd762f525635efbf8a155b238fa Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Tue, 8 Mar 2011 10:41:26 -0500 Subject: [PATCH] Add org.freedesktop.DBus.ObjectManager interface The org.freedesktop.DBus.ObjectManager provides a standardized and efficient way of keeping one or more tree of objects synchronized between one server and several clients. https://bugs.freedesktop.org/show_bug.cgi?id=34869 Signed-off-by: David Zeuthen --- doc/dbus-specification.xml | 108 ++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 108 insertions(+), 0 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index c4fee66..56da774 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -2998,6 +2998,114 @@ annotation. + + + <literal>org.freedesktop.DBus.ObjectManager</literal> + + An API can optionally make use of this interface for one or + more sub-trees of objects. The root of each sub-tree implement + this interface so other applications can get all objects, + interfaces and properties in a single method call. It is + appropriate to use this interface if users of the tree of + objects are expected to be interested in all interfaces of all + objects in the tree; a more granular API should be used if + users of the objects are expected to be interested in a small + subset of the objects, a small subset of their interfaces, or + both. + + + The method that applications can use to get all objects and + properties is GetManagedObjects: + + + + org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties); + + + + 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, i.e. their object + paths start with the ObjectManager's object path plus '/'. + + + Each value is a dict whose keys are interfaces names. Each + value in this inner dict is the same dict that would be + returned by the org.freedesktop.DBus.Properties.GetAll() + method for that combination of object path and interface. If + an interface has no properties, the empty dict is returned. + + + Changes are emitted using the following two signals: + + + + org.freedesktop.DBus.ObjectManager.InterfacesAdded (OBJPATH object_path, + DICT<STRING,DICT<STRING,VARIANT>> interfaces_and_properties); + org.freedesktop.DBus.ObjectManager.InterfacesRemoved (OBJPATH object_path, + ARRAY<STRING> interfaces); + + + + The InterfacesAdded signal is emitted when + either a new object is added or when an existing object gains + one or more interfaces. The + InterfacesRemoved signal is emitted + whenever an object is removed or it loses one or more + interfaces. The second parameter of the + InterfacesAdded signal contains a dict with + the interfaces and properties (if any) that have been added to + the given object path. Similarly, the second parameter of the + InterfacesRemoved signal contains an array + of the interfaces that were removed. Note that changes on + properties on existing interfaces are not reported using this + interface - an application should also monitor the existing PropertiesChanged + signal on each object. + + + 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 + GetManagedObjects() method of this + interface on the given object. + + + The intent of the ObjectManager interface + is to make it easy to write a robust client + implementation. The trivial client implementation only needs + to make two method calls: + + + + org.freedesktop.DBus.AddMatch (bus_proxy, + "type='signal',name='org.example.App',path_namespace='/org/example/App'"); + objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy); + + + + on the message bus and the remote application's + ObjectManager, respectively. Whenever a new + remote object is created (or an existing object gains a new + interface), the InterfacesAdded signal is + emitted, and since this signal contains all properties for the + interfaces, no calls to the + org.freedesktop.Properties interface on the + remote object are needed. Additionally, since the initial + AddMatch() rule already include signal + messages from the newly created child object, no new + AddMatch() call is needed. + + + + + The org.freedesktop.DBus.ObjectManager + interface was added in version 0.17 of the D-Bus + specification. + + + -- 1.7.4.2