diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Resources.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Resources.xml | 212 |
1 files changed, 0 insertions, 212 deletions
diff --git a/qt4/spec/Connection_Interface_Resources.xml b/qt4/spec/Connection_Interface_Resources.xml deleted file mode 100644 index 716089cd6..000000000 --- a/qt4/spec/Connection_Interface_Resources.xml +++ /dev/null @@ -1,212 +0,0 @@ -<?xml version="1.0" ?> -<node name="/Connection_Interface_Resources" - 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="org.freedesktop.Telepathy.Connection.Interface.Resources.DRAFT" - tp:causes-havoc="experimental"> - <tp:added version="0.21.1">(draft 1)</tp:added> - <tp:requires interface="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.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="org.freedesktop.Telepathy.Connection.Interface">SimplePresence/presence</tp:dbus-ref></li> - <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ContactCapabilities/capabilities</tp:dbus-ref></li> - <li><tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface">ClientTypes/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="org.freedesktop.Telepathy.Error.Disconnected"/> - <tp:error name="org.freedesktop.Telepathy.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: --> |