diff options
Diffstat (limited to 'spec/Connection_Interface_Resources1.xml')
| -rw-r--r-- | spec/Connection_Interface_Resources1.xml | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Resources1.xml b/spec/Connection_Interface_Resources1.xml new file mode 100644 index 00000000..ca7dddd3 --- /dev/null +++ b/spec/Connection_Interface_Resources1.xml @@ -0,0 +1,212 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Resources1" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright © 2010 Collabora Ltd.</tp:copyright> + <tp:license xmlns="http://www.w3.org/1999/xhtml"> + <p>This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2.1 of the License, or (at your option) any later version.</p> + +<p>This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details.</p> + +<p>You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p> + </tp:license> + <interface name="im.telepathy1.Connection.Interface.Resources1" + tp:causes-havoc="experimental"> + <tp:added version="0.21.1">(draft 1)</tp:added> + <tp:requires interface="im.telepathy1.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to show contact attributes for + specific resources of a contact, if the protocol supports + multiple resources. Resources are most common in XMPP, hence the + name of this interface, but they are also present in MSN, where + they are called points of presence.</p> + + <p>When a client requests some attribute of a contact using its + handle on the connection, the CM uses an algorithm to choose the + most appropriate resource for the job. If there is only one + resource, then the choice is obvious. If, however, there is more + than one resource connected at any one time, the CM either + aggregates all appropriate information to return (in the case of + capabilities), or chooses one specific resource (in the case of + presence).</p> + + <p>Resources in XMPP have names, and it can be extremely useful + for the user to be able to know which resources of a contact are + online, providing the names are human-readable. Before now, + resources have not been exposed in Telepathy, but this interface + attempts to change this.</p> + + <p>When using this interface, it is a little like using the + <tp:dbus-ref namespace="im.telepathy1.Connection.Interface" + >Contacts</tp:dbus-ref> interface, but only resource-specific + attributes are ever returned. The resource-specific contact + attributes are decided on by the CM, but XMPP's are listed + below:</p> + + <ul> + <li><tp:dbus-ref namespace="im.telepathy1.Connection.Interface">Presence1/presence</tp:dbus-ref></li> + <li><tp:dbus-ref namespace="im.telepathy1.Connection.Interface">ContactCapabilities1/capabilities</tp:dbus-ref></li> + <li><tp:dbus-ref namespace="im.telepathy1.Connection.Interface">ClientTypes1/client-types</tp:dbus-ref></li> + </ul> + + </tp:docstring> + + <method name="GetResources" tp:name-for-bindings="Get_Resources"> + <tp:docstring> + Return the resource information of the given contacts. If any + of the contact attributes for specific resources of the given + contacts' are not known return immediately without waiting for + a reply. + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose resource attributes should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Resources" type="a{ua{sa{sv}}}" + tp:type="Resources_Attributes_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The contacts' resources and the contact attributes specific + to each resource. If contact attributes are not immediately + known, the behaviour is defined by the interface; the + attribute should either be omitted from the result or + replaced with a default value.</p> + + <p>For every contact handle passed into this method, it is + guaranteed that there will be a key in the returned map + that corresponds to said handle. If there is no information + regarding the contact the resource information map will be + empty.</p> + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="im.telepathy1.Error.Disconnected"/> + <tp:error name="im.telepathy1.Error.InvalidHandle"/> + </tp:possible-errors> + </method> + + <tp:enum name="Resources_Human_Readability" type="u"> + <tp:enumvalue suffix="Never" value="0"> + <tp:docstring> + The resource string is never human-readable. + </tp:docstring> + </tp:enumvalue> + <tp:enumvalue suffix="Maybe" value="1"> + <tp:docstring> + The resource string might be human-readable. + </tp:docstring> + </tp:enumvalue> + </tp:enum> + + <property name="ResourcesHumanReadable" type="u" access="read" + tp:type="Resources_Human_Readability" + tp:name-for-bindings="Resources_Human_Readable"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Whether the resources returned from <tp:member-ref>GetResources</tp:member-ref> + are human readable or not.</p> + + <p>If the connection manager knows that all resource names are + automatically generated, then the resource strings mean + nothing to the user. Showing these strings in the UI would + be confusing, so by setting this to + Resources_Human_Readability_Never, the UI is advised not to + show resources.</p> + + <p>If on the other hand, all resources are set to nice names + (such as "office" or "home") then it might be wise to expose + these strings in the UI, so this property would be set to + Resources_Human_Readability_Maybe. This is the case in XMPP -- + most resources are set in a way that the user can deduce some + information from them. The absence of an Always enum value is + because in the case of XMPP, the resource string could be + partially human-readable (as on Google Talk, where a resource + of "home" is changed by the server to a unique string like + "home_1234fdec") or not at all human-readable.</p> + + </tp:docstring> + </property> + + <signal name="ResourcesUpdated" tp:name-for-bindings="Resources_Updated"> + <tp:docstring> + Emitted when a contact has a resource added or removed, or any + contact attribute for any resource changes. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact. + </tp:docstring> + </arg> + <arg name="Resources" tp:type="Resource_Information_Map" + type="a{sa{sv}}"> + <tp:docstring> + The contact's resource information. All resource information + is given, not just the details which have changed. + </tp:docstring> + </arg> + </signal> + + <tp:mapping name="Resource_Information_Map"> + <tp:docstring> + A map of a contact's resources to their resource-specific + information. + </tp:docstring> + + <tp:member name="Key" type="s"> + <tp:docstring> + <p>The name of the resource.</p> + </tp:docstring> + </tp:member> + + <tp:member name="Contact_Attributes" type="a{sv}" + tp:type="Single_Contact_Attributes_Map"> + <tp:docstring> + A map of contact attributes whose data is specific to this + resource. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:mapping name="Resources_Attributes_Map"> + <tp:docstring>Mapping returned by + <tp:member-ref>GetResources</tp:member-ref>, representing a + collection of Contacts, their resources, and their + resource-specific contact attributes.</tp:docstring> + + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact. + </tp:docstring> + </tp:member> + + <tp:member type="a{sa{sv}}" tp:type="Resource_Information_Map" + name="Resources"> + <tp:docstring> + A map of the contact's resources to their resource-specific + information. + </tp:docstring> + </tp:member> + </tp:mapping> + + <tp:contact-attribute name="resources" type="a{sa{sv}}" + tp:type="Resource_Information_Map"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetResources</tp:member-ref> for this contact.</p> + </tp:docstring> + </tp:contact-attribute> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |