diff options
Diffstat (limited to 'qt4/spec/Connection_Interface_Presence.xml')
| -rw-r--r-- | qt4/spec/Connection_Interface_Presence.xml | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/qt4/spec/Connection_Interface_Presence.xml b/qt4/spec/Connection_Interface_Presence.xml new file mode 100644 index 000000000..8a344d416 --- /dev/null +++ b/qt4/spec/Connection_Interface_Presence.xml @@ -0,0 +1,346 @@ +<?xml version="1.0" ?> +<node name="/Connection_Interface_Presence" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0"> + <tp:copyright> + Copyright (C) 2005, 2006 Collabora Limited + </tp:copyright> + <tp:copyright> +Copyright (C) 2005, 2006 Nokia Corporation + </tp:copyright> + <tp:copyright> +Copyright (C) 2006 INdT + </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.Presence"> + <tp:requires interface="org.freedesktop.Telepathy.Connection"/> + <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"/> + + <tp:mapping name="Multiple_Status_Map"> + <tp:docstring>Mapping used in + <tp:type>Last_Activity_And_Statuses</tp:type> and passed to + <tp:member-ref>SetStatus</tp:member-ref>, representing a collection of + statuses. Use of this mapping with more than one member is + deprecated.</tp:docstring> + <tp:member type="s" name="Status"/> + <tp:member type="a{sv}" tp:type="String_Variant_Map" name="Parameters"/> + </tp:mapping> + <tp:struct name="Last_Activity_And_Statuses" array-name=""> + <tp:docstring>Structure representing a contact's presence, containing + a last-activity time (deprecated) and a Multiple_Status_Map. + </tp:docstring> + <tp:member type="u" tp:type="Unix_Timestamp" name="Last_Activity"/> + <tp:member type="a{sa{sv}}" tp:type="Multiple_Status_Map" + name="Statuses"/> + </tp:struct> + <tp:mapping name="Contact_Presences"> + <tp:docstring>Mapping returned by + <tp:member-ref>GetPresence</tp:member-ref> and signalled by + <tp:member-ref>PresenceUpdate</tp:member-ref>, where the keys are + contacts and the values represent their presences.</tp:docstring> + <tp:member type="u" tp:type="Contact_Handle" name="Contact"/> + <tp:member type="(ua{sa{sv}})" tp:type="Last_Activity_And_Statuses" + name="Presence"/> + </tp:mapping> + <tp:struct name="Status_Spec" array-name=""> + <tp:member type="u" tp:type="Connection_Presence_Type" name="Type"/> + <tp:member type="b" name="May_Set_On_Self"/> + <tp:member type="b" name="Exclusive"/> + <tp:member type="a{ss}" tp:type="String_String_Map" + name="Parameter_Types"/> + </tp:struct> + <tp:mapping name="Status_Spec_Map"> + <tp:member type="s" name="Identifier"/> + <tp:member type="(ubba{ss})" tp:type="Status_Spec" name="Spec"/> + </tp:mapping> + + <method name="AddStatus" tp:name-for-bindings="Add_Status"> + <arg direction="in" name="Status" type="s"> + <tp:docstring> + The string identifier of the desired status + </tp:docstring> + </arg> + <arg direction="in" name="Parameters" type="a{sv}" tp:type="String_Variant_Map"> + <tp:docstring> + A dictionary of optional parameter names mapped to their variant-boxed values + </tp:docstring> + </arg> + <tp:docstring> + Request that a single presence status is published for the user, along + with any desired parameters. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. + </tp:docstring> + <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.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + <method name="ClearStatus" tp:name-for-bindings="Clear_Status"> + <tp:docstring> + Request that all of a user's presence statuses be removed. Be aware + that this request may simply result in the statuses being replaced by a + default available status. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. + </tp:docstring> + <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.PermissionDenied"/> + </tp:possible-errors> + </method> + <method name="GetPresence" tp:name-for-bindings="Get_Presence"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> + <arg direction="out" name="Presence" type="a{u(ua{sa{sv}})}" + tp:type="Contact_Presences"> + <tp:docstring> + Presence information in the same format as for the + <tp:member-ref>PresenceUpdate</tp:member-ref> signal + </tp:docstring> + </arg> + <tp:docstring> + Get presence previously emitted by + <tp:member-ref>PresenceUpdate</tp:member-ref> for the given contacts. + Data is returned in the same structure as the PresenceUpdate signal. + Using this method in favour of + <tp:member-ref>RequestPresence</tp:member-ref> has the advantage that + it will not wake up each client connected to the PresenceUpdate signal. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/> + <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/> + </tp:possible-errors> + </method> + <method name="GetStatuses" tp:name-for-bindings="Get_Statuses"> + <arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map" + name="Available_Statuses"> + <tp:docstring> + A dictionary of string identifiers mapped to a struct for each status, containing: + <ul> + <li>a type value from one of the values above</li> + <li>a boolean to indicate if this status may be set on yourself</li> + <li>a boolean to indicate if this is an exclusive status which you + may not set alongside any other</li> + <li>a dictionary of valid optional string argument names mapped to + their types</li> + </ul> + </tp:docstring> + </arg> + <tp:docstring> + Get a dictionary of the valid presence statuses for this connection. + This is only available when online because only some statuses will + be available on some servers. + </tp:docstring> + <tp:possible-errors> + <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/> + <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/> + </tp:possible-errors> + </method> + <signal name="PresenceUpdate" tp:name-for-bindings="Presence_Update"> + <arg name="Presence" type="a{u(ua{sa{sv}})}" tp:type="Contact_Presences"> + <tp:docstring> + A dictionary of contact handles mapped to a struct containing + a UNIX timestamp of the last activity time (in UTC), and + a dictionary mapping the contact's current status identifiers to + a dictionary of optional parameter names mapped to their + variant-boxed values + </tp:docstring> + </arg> + <tp:docstring> + This signal should be emitted when your own presence has been changed, + or the presence of the member of any of the connection's channels has + been changed, or when the presence requested by + <tp:member-ref>RequestPresence</tp:member-ref> is available. + </tp:docstring> + </signal> + <method name="RemoveStatus" tp:name-for-bindings="Remove_Status"> + <arg direction="in" name="Status" type="s"> + <tp:docstring> + The string identifier of the status not to publish anymore for the user + </tp:docstring> + </arg> + <tp:docstring> + Request that the given presence status is no longer published for the + user. Changes will be indicated by + <tp:member-ref>PresenceUpdate</tp:member-ref> signals being emitted. As + with <tp:member-ref>ClearStatus</tp:member-ref>, removing a status may + actually result in it being replaced by a default available status. + </tp:docstring> + <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.PermissionDenied"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"> + <tp:docstring>The status requested is not currently set</tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="RequestPresence" tp:name-for-bindings="Request_Presence"> + <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]"> + <tp:docstring> + An array of the contacts whose presence should be obtained + </tp:docstring> + </arg> + <tp:docstring> + Request the presence for contacts on this connection. A <tp:member-ref>PresenceUpdate</tp:member-ref> + signal will be emitted when they are received. This is not the same as + subscribing to the presence of a contact, which must be done using the + 'subscription' <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel.Type">ContactList</tp:dbus-ref>, + and on some protocols presence information may not be available unless + a subscription exists. + </tp:docstring> + <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:error name="org.freedesktop.Telepathy.Error.NotAvailable"> + <tp:docstring> + The presence of the requested contacts is not reported to this connection + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="SetLastActivityTime" + tp:name-for-bindings="Set_Last_Activity_Time"> + <arg direction="in" name="Time" type="u" tp:type="Unix_Timestamp"> + <tp:docstring> + A UNIX timestamp of the user's last activity time (in UTC) + </tp:docstring> + </arg> + <tp:docstring> + Request that the recorded last activity time for the user be updated on + the server. + </tp:docstring> + <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.NotImplemented"> + <tp:docstring> + This protocol has no concept of idle time + </tp:docstring> + </tp:error> + </tp:possible-errors> + </method> + <method name="SetStatus" tp:name-for-bindings="Set_Status"> + <arg direction="in" name="Statuses" type="a{sa{sv}}" tp:type="Multiple_Status_Map"> + <tp:docstring> + A dictionary mapping status identifiers to dictionaries, which + map optional parameter names to their variant-boxed values + </tp:docstring> + </arg> + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>Request that the user's presence be changed to the given statuses + and desired parameters. Changes will be reflected by + <tp:member-ref>PresenceUpdate</tp:member-ref> + signals being emitted.</p> + + <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type> + is Offline, Error or Unknown MUST NOT be passed to this + function. Connection managers SHOULD reject these statuses.</p> + + <tp:rationale> + <p>The same rationale as for <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref> + applies.</p> + </tp:rationale> + + <p>On certain protocols, this method may be + called on a newly-created connection which is still in the + DISCONNECTED state, and will sign on with the requested status. + If the requested status is not available after signing on, + NotAvailable will be returned and the connection will remain + offline, or if the protocol does not support signing on with + a certain status, Disconnected will be returned.</p> + </tp:docstring> + <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.NotAvailable"/> + <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/> + <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/> + </tp:possible-errors> + </method> + + <tp:deprecated version="0.17.21">Client implementations + SHOULD use <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + instead.</tp:deprecated> + <tp:changed version="0.17.23">Connection managers implementing + Presence MUST implement SimplePresence too.</tp:changed> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + + <p>This interface is for services which have a concept of presence which + can be published for yourself and monitored on your contacts. + Telepathy's definition of presence is based on that used by + <a href="http://www.galago-project.org/">the Galago project</a>.</p> + + <p>Presence on an individual (yourself or one of your contacts) is modelled as + a last activity time along with a set of zero or more statuses, each of + which may have arbitrary key/value parameters. Valid statuses are defined + per connection, and a list of them can be obtained with the + <tp:member-ref>GetStatuses</tp:member-ref> method.</p> + + <p>(The SimplePresence interface which replaces this one restricts + presences to one status per contact, with an optional message, which is + in practice all that was implemented on this interface.)</p> + + <p>Each status has an arbitrary string identifier which should have an agreed + meaning between the connection manager and any client which is expected to + make use of it. The well-known values defined by the <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref> + interface SHOULD be used where possible</p> + + <p>As well as these well-known status identifiers, every status also has a + numerical type value chosen from + <tp:type>Connection_Presence_Type</tp:type> which can be used by the client + to classify even unknown statuses into different fundamental types.</p> + + <p>These numerical types exist so that even if a client does not understand + the string identifier being used, and hence cannot present the presence to + the user to set on themselves, it may display an approximation of the + presence if it is set on a contact.</p> + + <p>The dictionary of variant types allows the connection manager to exchange + further protocol-specific information with the client. It is recommended + that the string (s) argument 'message' be interpreted as an optional + message which can be associated with a presence status.</p> + + <p>If the connection has a 'subscribe' contact list, + <tp:member-ref>PresenceUpdate</tp:member-ref> signals should be emitted to + indicate changes of contacts on this list, and should also be emitted for + changes in your own presence. Depending on the protocol, the signal may + also be emitted for others such as people with whom you are communicating, + and any user interface should be updated accordingly.</p> + + <p>On some protocols, <tp:member-ref>RequestPresence</tp:member-ref> may + only succeed on contacts on your 'subscribe' list, and other contacts will + cause a PermissionDenied error. On protocols where there is no 'subscribe' + list, and RequestPresence succeeds, a client may poll the server + intermittently to update any display of presence information.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |