diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Client_Types.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Client_Types.xml | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/qt4/spec/Connection_Interface_Client_Types.xml b/qt4/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 000000000..97908561a --- /dev/null +++ b/qt4/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,218 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Client_Types" + xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright>Copyright (C) 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.ClientTypes"> + <tp:added version="0.21.1">(as stable API)</tp:added> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>An interface on connections to support protocols which allows users to + subscribe to the client types of their contacts.</p> + + <p>One can connect to instant messaging networks on a huge variety of + devices, from PCs, to phones to consoles. It can be useful for users + to know what kind of device a contact is using so that he or she + can decide not to send that big file or start a video chat. This + interface exposes exactly this information for clients to display.</p> + + <p>The client types are represented in strings, using the values + <a href="http://xmpp.org/registrar/disco-categories.html#client"> + documented by the XMPP registrar</a> with some additional types + added for other protocols. A contact can set one or more client types + so this interface returns a list of strings to denote client types + for a contact. The well-known client types to be used are:</p> + + <ul> + <li>bot</li> + <li>console (minimal non-GUI client used on dumb terminals or + text-only screens, <strong>not</strong> a games console)</li> + <li>handheld</li> + <li>pc</li> + <li>phone</li> + <li>web</li> +<!-- Excluding these two because there's been no conclusion regarding my mail + to standards@xmpp.org about adding these two to their list: + + <li>sms (the client is not actually an instant messaging client + but all messages sent to this contact will be delivered as SMSs)</li> + <li>game (a gaming device)</li> +--> + </ul> + + <p>If the empty list is given as the client types, this means that + details about the contact's client types are unknown. If there are + multiple resources of a contact online at one point in time, the + client types of the most available resource will be returned. In + other words, the returned client types are those for the resource whose + presence will be retreived using the + <tp:dbus-ref namespace="ofdT.Connection.Interface">SimplePresence</tp:dbus-ref> + interface.</p> + + <p>For example, if a contact has two resources:</p> + + <ul> + <li>their phone, with presence "available"; and</li> + <li>their pc, with presence "busy";</li> + </ul> + + <p>then the methods in this interface will return an array (with + one element: "phone") as the client types because that is the more + available resource. If at some later time the contact's phone's presence + changes to "away", the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + notify that the contact's client types attribute has changed from + ["phone"] to ["pc"], + because "busy" is a more available presence than "away".</p> + + </tp:docstring> + + <tp:mapping name="Contact_Client_Types"> + <tp:docstring> + A mapping from contact handle to client types. + </tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"> + <tp:docstring> + A contact. + </tp:docstring> + </tp:member> + <tp:member type="as" name="Client_Types" tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types as documented earlier in this interface. + </tp:docstring> + </tp:member> + </tp:mapping> + + <method name="GetClientTypes" tp:name-for-bindings="Get_Client_Types"> + <tp:docstring> + Return the client types of the given contacts, if they are + already known. If any of the given contacts' client types are + not known, request their current client types, but return + immediately without waiting for a reply; if a reply with a + non-empty client type array is later received for those + contacts, the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + be emitted for them. + + <tp:rationale> + This method is appropriate for "lazy" client type finding, for instance + displaying the client types (if available) of everyone in your contact + list. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + The contacts whose client types should be returned or signalled. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="a{uas}" + tp:type="Contact_Client_Types"> + <tp:docstring> + The contacts' client types, if already known. Contacts whose client + types are not already known are omitted from the mapping; contacts known + to have no client type information appear in the mapping with an empty + list. + </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> + + <method name="RequestClientTypes" tp:name-for-bindings="Request_Client_Types"> + <tp:docstring> + Return the current client types of the given contact. If necessary, make + a request to the server for up-to-date information, and wait for a + reply. + + <tp:rationale> + This method is appropriate for use in a "Contact Information..." + dialog; it can be used to show progress information (while waiting + for the method to return), and can distinguish between various error + conditions. + </tp:rationale> + </tp:docstring> + + <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact whose client types should be returned. + </tp:docstring> + </arg> + + <arg direction="out" name="Client_Types" type="as" + tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types. It MAY be empty, indicating that no client + type information was found. + </tp:docstring> + </arg> + + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"> + <tp:docstring> + The requested contact does not allow the local user to see their + client type information. + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + + <signal name="ClientTypesUpdated" tp:name-for-bindings="Client_Types_Updated"> + <tp:docstring> + Emitted when a contact's client types change or become known. + </tp:docstring> + + <arg name="Contact" type="u" tp:type="Contact_Handle"> + <tp:docstring> + The contact. + </tp:docstring> + </arg> + <arg name="Client_Types" type="as" tp:type="Contact_Client_Type[]"> + <tp:docstring> + The contact's client types, or an empty list to indicate that nothing + is known about the contact's client types. + </tp:docstring> + </arg> + </signal> + + <tp:contact-attribute name="client-types" type="as" + tp:type="Contact_Client_Type[]"> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>The same mapping that would be returned by + <tp:member-ref>GetClientTypes</tp:member-ref> for this contact. + Omitted from the result if the contact's client types are not + known.</p> + </tp:docstring> + </tp:contact-attribute> + + <tp:simple-type name="Contact_Client_Type" type="s" + array-name="Contact_Client_Type_List"> + <tp:docstring>A string representing a single client type of a + contact.</tp:docstring> + </tp:simple-type> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |