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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2009–2011 Collabora Ltd.</tp:copyright>
<tp:copyright>Copyright © 2009 Nokia Corporation</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.ContactBlocking">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
<tp:added version='0.21.13'>Changes from the draft:
methods and signals now return <tp:type>Handle_Identifier_Map</tp:type>
(<code>a{us}</code>) rather than bare lists of contact handles
(<code>au</code>)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for connections where contacts can be blocked from
communicating with this user and receiving this user's presence.
Clients may retrieve a list of currently-blocked contacts using
<tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for
<tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified
when contacts are blocked and unblocked. The
<tp:member-ref>BlockContacts</tp:member-ref> and
<tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say
on the tin; depending on the value of the
<tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property,
contacts may be reported for spam or other abuse when calling
<tp:member-ref>BlockContacts</tp:member-ref>.</p>
<p>This interface is intended for protocols where blocking contacts
persists on the server between connections; connection managers for
protocols with no server-side support for blocking contacts MAY choose
to implement this interface using an on-disk file of blocked
contacts or some other means to store blocked contacts between
connections.</p>
<p>This interface is intended to replace the
<tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref>
channel with <tp:dbus-ref
namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
<code>List</code> and <tp:dbus-ref
namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code>
(along with the <tp:dbus-ref
namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and
<tp:dbus-ref
namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref>
interfaces replacing other channels with <tp:dbus-ref
namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
<code>List</code> and <tp:dbus-ref
namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
<code>Group</code>, respectively).</p>
</tp:docstring>
<method name="BlockContacts" tp:name-for-bindings="Block_Contacts">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Direct the server to block some contacts. The precise effect is
protocol-dependent, but SHOULD include ignoring all current and
subsequent communications from the given contacts, avoiding sending
presence to them in future, and if they were already receiving the
local user's presence, behaving as if the local user went
offline.</p>
</tp:docstring>
<arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
<tp:docstring>Some contacts to block. If some of the contacts in this
list are already blocked, the connection manager MUST act as if they
were not specified in this list.</tp:docstring>
</arg>
<arg name="Report_Abusive" type="b" direction="in">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>In addition to blocking, report these contacts as abusive to the
server administrators.</p>
<p>Clients can determine whether this capability is available by
checking the
<tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
property. If this argument is set to <code>True</code> by a client
despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
not containing the <code>Can_Report_Abusive</code> flag, the
connection manager SHOULD act as if it were <code>False</code> and
simply block the supplied contacts.</p>
<tp:rationale>
<p>A correct user interface shouldn't get this far without knowing
that reporting abusive contacts is not supported. If it does,
then the user has expressed their intention to block these
contacts. Returning an error would leave the UI with three
options:</p>
<ul>
<li>Ignore the error, leaving the contacts not actually blocked;</li>
<li>Display an error to the user;</li>
<li>Call this method again, passing <code>False</code> for this
argument.</li>
</ul>
<p>None of these seem preferable to the CM just ignoring this flag
if it doesn't support it: that way, the contacts will be blocked,
as the user requested, and UIs have fewer ways to mess up
entirely.</p>
</tp:rationale>
</tp:docstring>
</arg>
</method>
<method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Direct the server to unblock some contacts.</p>
</tp:docstring>
<arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
<tp:docstring>Some contacts to unblock. If some of the contacts in this
list are not currently blocked, the connection manager MUST act as if
they were not specified in this list.</tp:docstring>
</arg>
</method>
<method name="RequestBlockedContacts"
tp:name-for-bindings="Request_Blocked_Contacts">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>List the contacts that are blocked.</p>
<p>Clients SHOULD allow a relatively long timeout for calls to this
method, since on some protocols contact blocking is part of the
contact list, which can take a significant time to retrieve.</p>
</tp:docstring>
<arg name="Contacts" type="a{us}" direction="out"
tp:type="Handle_Identifier_Map">
<tp:docstring>The blocked contacts’ handles, together with their
identifiers.</tp:docstring>
</arg>
</method>
<signal name="BlockedContactsChanged"
tp:name-for-bindings="Blocked_Contacts_Changed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when the list of blocked contacts is first retrieved
(before returning from any pending calls to
<tp:member-ref>RequestBlockedContacts</tp:member-ref>), and
whenever the list of blocked contacts subsequently changes.</p>
</tp:docstring>
<arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map">
<tp:docstring>Contacts added to the result of
<tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
</arg>
<arg name="Unblocked_Contacts" type="a{us}"
tp:type="Handle_Identifier_Map">
<tp:docstring>Contacts removed from the result of
<tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
</arg>
</signal>
<tp:contact-attribute name="blocked" type="b">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p><code>True</code> if the contact would be in the result of
<tp:member-ref>RequestBlockedContacts</tp:member-ref>;
<code>False</code> or omitted if the contact is not blocked, or if it
is unknown whether the contact is blocked.</p>
</tp:docstring>
</tp:contact-attribute>
<property name="ContactBlockingCapabilities"
tp:name-for-bindings="Contact_Blocking_Capabilities"
tp:type="Contact_Blocking_Capabilities" type="u" access="read"
tp:immutable="yes">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Additional capabilities for contact blocking; currently, this is
limited to whether contacts may be reported as abusive.</p>
<p>Note that there is no capability for supporting blocking itself:
the presence of this interface on a <tp:dbus-ref
namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking
contacts is supported.</p>
</tp:docstring>
</property>
<tp:flags name="Contact_Blocking_Capabilities" type="u"
value-prefix="Contact_Blocking_Capability">
<tp:flag suffix="Can_Report_Abusive" value="1">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
When calling <tp:member-ref>BlockContacts</tp:member-ref>, the
contacts may be reporting as abusive to the server administrators by
setting <var>Report_Abusive</var> to <code>True</code>.
</tp:docstring>
</tp:flag>
</tp:flags>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
