diff options
Diffstat (limited to 'spec/Connection_Interface_Client_Types.xml')
-rw-r--r-- | spec/Connection_Interface_Client_Types.xml | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/spec/Connection_Interface_Client_Types.xml b/spec/Connection_Interface_Client_Types.xml new file mode 100644 index 000000000..879095e7c --- /dev/null +++ b/spec/Connection_Interface_Client_Types.xml @@ -0,0 +1,203 @@ +<?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.DRAFT" + tp:causes-havoc="experimental"> + <tp:added version="0.19.11">(as draft)</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> + <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 client types are the types of the client whose + SimplePresence we see. For example, if a contact has two + resources:</p> + + <ul> + <li>one his phone, with presence "available", and</li> + <li>one his 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 as that is the more + available resource. If some time later his phone's presence + moves to "away", then the + <tp:member-ref>ClientTypesUpdated</tp:member-ref> signal will + notify that his client type have 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: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: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: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: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> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |