diff options
Diffstat (limited to 'spec/Channel_Type_Contact_List.xml')
| -rw-r--r-- | spec/Channel_Type_Contact_List.xml | 104 |
1 files changed, 104 insertions, 0 deletions
diff --git a/spec/Channel_Type_Contact_List.xml b/spec/Channel_Type_Contact_List.xml new file mode 100644 index 0000000..5a0d333 --- /dev/null +++ b/spec/Channel_Type_Contact_List.xml @@ -0,0 +1,104 @@ +<?xml version="1.0" ?> +<node name="/Channel_Type_Contact_List" 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.Channel.Type.ContactList"> + <tp:requires interface="org.freedesktop.Telepathy.Channel"/> + <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.Group"/> + + <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> + <p>A channel type for representing a list of people on the server which is + not used for communication. This is intended for use with the interface + <tp:dbus-ref + namespace="org.freedesktop.Telepathy">Channel.Interface.Group</tp:dbus-ref> + for managing buddy lists and privacy lists + on the server. This channel type has no methods because all of the + functionality it represents is available via the group interface.</p> + + <p>There are currently two types of contact list: + HANDLE_TYPE_LIST is a "magic" server-defined list, and + HANDLE_TYPE_GROUP is a user-defined contact group.</p> + + <p>For server-defined lists like the subscribe list, singleton instances + of this channel type should be created by the connection manager at + connection time if the list exists on the server, or may be requested + by using the appropriate handle. These handles can be obtained using + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_LIST and one of the + following identifiers:</p> + + <ul> + <li>subscribe - the group of contacts for whom you receive presence</li> + <li>publish - the group of contacts who may receive your presence</li> + <li>hide - a group of contacts who are on the publish list but are temporarily disallowed from receiving your presence</li> + <li>allow - a group of contacts who may send you messages</li> + <li>deny - a group of contacts who may not send you messages</li> + <li>stored - on protocols where the user's contacts are stored, this + contact list contains all stored contacts regardless of subscription + status.</li> + </ul> + + <p>A contact can be in several server-defined lists. All lists are optional + to implement. If <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + or <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestChannel</tp:dbus-ref> + for a particular contact list raises an error, this indicates that the + connection manager makes no particular statement about the list's contents; + clients MUST NOT consider this to be fatal.</p> + + <p>If a client wants to list all of a user's contacts, it is appropriate to + use the union of the subscribe, publish and stored lists, including the + local and remote pending members.</p> + + <p>For example in XMPP, contacts who have the subscription type "none", + "from", "to" and "both" can be respectively in the lists:</p> + + <ul> + <li>"none": stored</li> + <li>"from": stored and publish</li> + <li>"to": stored and subscribe</li> + <li>"both": stored, publish and subscribe</li> + </ul> + + <p>These contact list channels may not be closed.</p> + + <p>For user-defined contact groups, instances of this channel type should + be created by the connection manager at connection time for each group + that exists on the server. New, empty groups can be created by calling + <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Connection">RequestHandles</tp:dbus-ref> + with a <tp:type>Handle_Type</tp:type> of HANDLE_TYPE_GROUP and with the + name set to the human-readable UTF-8 name of the group.</p> + + <p>User-defined groups may be deleted by calling <tp:dbus-ref + namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref> on the + channel, but only if + the group is already empty. Closing a channel to a non-empty group is + not allowed; its members must be set to the empty set first.</p> + + <p>On some protocols (e.g. XMPP) empty groups are not represented on the + server, so disconnecting from the server and reconnecting might cause + empty groups to vanish.</p> + </tp:docstring> + + </interface> +</node> +<!-- vim:set sw=2 sts=2 et ft=xml: --> |