3001 | |
3002 | <sect2 id="standard-interfaces-objectmanager"> |
3003 | <title><literal>org.freedesktop.DBus.ObjectManager</literal></title> |
3004 | <para> |
3005 | An application can optionally make use of this interface to |
I'd be tempted to say "An API can" instead, to emphasize that choosing whether to use ObjectManager is up to the D-Bus API designer, not the implementer (in cases where they might be different people, like Telepathy or MPRIS). It might also be worth saying something like: 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. |
3009 | call: |
3010 | </para> |
3011 | <para> |
3012 | <programlisting> |
3013 | org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT<OBJPATH,DICT<STRING,DICT<STRING,VARIANT>>> objpath_interfaces_and_properties); |
So, er, that's a{oa{sa{sv}}}? I thought Telepathy had intimidating data-types :-) |
3015 | </para> |
3016 | <para> |
3017 | The return value of this method is a dict whose keys are |
3018 | object paths. All returned object paths are children of the |
3019 | object path implementing this interface. Each value is a dict |
I think this deserves clarification that they're syntactically children in the object-path tree, rather than some loose conceptual relationship: ... implementing this interface, i.e. their object paths start with the ObjectManager's object path plus '/'. (At least, I assume that's what you meant.) |
3021 | containing the properties (see <xref |
3022 | linkend="standard-interfaces-properties"/>) for each interface |
3023 | and object path in question that the |
3024 | <literal>org.freedesktop.DBus.Properties.GetAll</literal> |
3025 | method would return. If an interface has no properties, the |
This run-on sentence is rather awkward. How about: Each value is a dict, whose keys are interface names. Each value in this inner dict is the same dict that would be returned by the <>...GetAll</> method for that combination of object path and interface. If an interface has no ... (I deliberately put object path first here because that's the logical order: as seen in dbus-send, and (hopefully) in the libdbus and GDBus APIs, the hierarchy from largest to smallest is bus name, object path, interface, member.) Does GetAll actually specifically say that it returns {} for a propertyless interface? If not, it should. (There's a dbus-glib bug about that.) |
3038 | </para> |
3039 | <para> |
3040 | The <literal>InterfacesAdded</literal> signal is emitted when |
3041 | either a new object is added or if an existing object gains |
3042 | one or more interfaces while the |
Grammar: choose whether you're saying "when" or "if" (I vote for "when"). I'd say: when either a new object is added, or an existing ... I think this "while" deserves to be a sentence break. |
3043 | <literal>InterfacesRemoved</literal> signal is emitted |
3044 | whenever an object is removed or it loses one or more |
3045 | interfaces. The second parameter of the |
3046 | <literal>InterfacesAdded</literal> signal contains a dict with |
3047 | the interfaces and properties (if any) that has been added to |
"that have been added": it's the interfaces and properties that were added, not the dict |
3046 | <literal>InterfacesAdded</literal> signal contains a dict with |
3047 | the interfaces and properties (if any) that has been added to |
3048 | the given object path. Similarly, the second parameter of the |
3049 | <literal>InterfacesRemoved</literal> signal contains an array |
3050 | of the interfaces that was removed. Note that changes on |
"that were removed": it's the interfaces that were removed, not the array. Do you have a use-case for interfaces disappearing without the entire object going away? I don't think changes to the list of interfaces are generally part of the de facto D-Bus object model? (dbus-glib and dbus-python certainly can't support it with their current design.) |
3048 | the given object path. Similarly, the second parameter of the |
3049 | <literal>InterfacesRemoved</literal> signal contains an array |
3050 | of the interfaces that was removed. Note that changes on |
3051 | properties on existing interfaces are not reported using this |
3052 | interface - an application should use the |
s/use/also monitor/ perhaps |
3055 | <para> |
3056 | Applications SHOULD NOT export objects that are children of an |
3057 | object (directly or otherwise) implementing this interface but |
3058 | which are not returned in the reply from the |
3059 | <literal>GetAll()</literal> method of this interface on the |
it's no longer called GetAll |
3070 | </programlisting> |
3071 | </para> |
3072 | <para> |
3073 | on respectively the message bus and the remote |
3074 | application. Whenever a new remote object is created (or an |
I tend to think of method calls as being an operation on objects (or proxies), rather than on destinations: "on the message bus, and the remote application's ObjectManager, respectively". |
3072 | <para> |
3073 | on respectively the message bus and the remote |
3074 | application. Whenever a new remote object is created (or an |
3075 | existing object gains a new interface), the |
3076 | <literal>InterfacesAdded</literal> signal is emitted and since |
emitted, and |
3075 | existing object gains a new interface), the |
3076 | <literal>InterfacesAdded</literal> signal is emitted and since |
3077 | this signal contains all properties for the interfaces, no |
3078 | calls to the <literal>org.freedesktop.Properties</literal> |
3079 | interface on the remote object is needed. Additionally, since |
are needed |
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.