From 56800b7fb5b1997f1fcdc525f697a3704fcf6b87 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 | 84 ++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 84 insertions(+), 0 deletions(-) diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index bd35909..55bdb3e 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -2981,6 +2981,90 @@ annotation. + + + <literal>org.freedesktop.DBus.ObjectManager</literal> + + 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: + + + + 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. Each value is a dict + whose keys are interfaces names and values are another dict + containing the properties (see ) for each interface + and object path in question that the + org.freedesktop.DBus.Properties.GetAll + method would return. 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 if an existing object gains + one or more interfaces while 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 has been added to + the given object path. Similarly, the second parameter of the + InterfacesRemoved 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 + 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 + GetAll() 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_prefix='/org/example/App'"); + objects = org.freedesktop.DBus.ObjectManager.GetManagedObjects (app_proxy); + + + + 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 + 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 is needed. Additionally, since + the initial AddMatch() rule already include + signal messages from the newly created child object, no new + AddMatch() call is needed. + + -- 1.7.4.1