1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
<?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:deprecated version="0.25.0">Replaced by <tp:dbus-ref
namespace="org.freedesktop.Telepathy">Connection.Interface.ContactList</tp:dbus-ref>
</tp:deprecated>
<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: -->
|
