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
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Avatars" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright (C) 2005-2007 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
Library 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.Avatars">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<tp:mapping name="Avatar_Token_Map" array-name="">
<tp:docstring>A dictionary whose keys are contact handles and whose
values are avatar tokens.</tp:docstring>
<tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
<tp:member type="s" name="Token"/>
</tp:mapping>
<signal name="AvatarUpdated">
<arg name="contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
An integer handle for the contact whose avatar has changed
</tp:docstring>
</arg>
<arg name="new_avatar_token" type="s">
<tp:docstring>
Unique token for their new avatar
</tp:docstring>
</arg>
<tp:docstring>
Emitted when the avatar for a contact has been updated, or first
discovered on this connection. If the token differs from the token
associated with the client's cached avatar for this contact, the new
avatar should be requested with RequestAvatar.
</tp:docstring>
</signal>
<signal name="AvatarRetrieved">
<arg name="contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
The contact whose avatar has been retrieved
</tp:docstring>
</arg>
<arg name="token" type="s">
<tp:docstring>
The token corresponding to the avatar
</tp:docstring>
</arg>
<arg name="avatar" type="ay">
<tp:docstring>
An array of bytes containing the image data
</tp:docstring>
</arg>
<arg name="type" type="s">
<tp:docstring>
A string containing the image MIME type (eg image/jpeg), or empty if
unknown
</tp:docstring>
</arg>
<tp:docstring>
Emitted when the avatar for a contact has been retrieved.
</tp:docstring>
</signal>
<method name="GetAvatarRequirements">
<arg direction="out" type="as">
<tp:docstring>
An array of supported MIME types (eg image/jpeg)
</tp:docstring>
</arg>
<arg direction="out" type="q">
<tp:docstring>
The minimum image width in pixels
</tp:docstring>
</arg>
<arg direction="out" type="q">
<tp:docstring>
The minimum image height in pixels
</tp:docstring>
</arg>
<arg direction="out" type="q">
<tp:docstring>
The maximum image width in pixels, or 0 if there is no limit
</tp:docstring>
</arg>
<arg direction="out" type="q">
<tp:docstring>
The maximum image height in pixels, or 0 if there is no limit
</tp:docstring>
</arg>
<arg direction="out" type="u">
<tp:docstring>
The maximum image size in bytes, or 0 if there is no limit
</tp:docstring>
</arg>
<tp:docstring>
Get the required format of avatars on this connection.
</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.NotAvailable"/>
</tp:possible-errors>
</method>
<method name="GetAvatarTokens">
<arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
An array of handles representing contacts
</tp:docstring>
</arg>
<arg direction="out" type="as">
<tp:docstring>
An array of avatar tokens or empty strings (if no avatar is set) in the
same order as the given array of contact handles
</tp:docstring>
</arg>
<tp:docstring>
Get the unique tokens for all of the given contacts' avatars.
Using this method in new Telepathy clients is deprecated; use
GetKnownAvatarTokens instead.
</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.PermissionDenied"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
</tp:possible-errors>
</method>
<method name="GetKnownAvatarTokens">
<arg direction="in" name="contacts" type="au" tp:type="Contact_Handle[]">
<tp:docstring>
An array of handles representing contacts
</tp:docstring>
</arg>
<arg direction="out" type="a{us}" tp:type="Avatar_Token_Map">
<tp:docstring>
A dictionary of handles mapped to avatar tokens, containing only
the known avatar tokens.
</tp:docstring>
</arg>
<tp:docstring>
Get the unique tokens for the given contacts' avatars. These tokens
can be persisted across connections, and should be used by the client
to check whether the avatars have been updated. A empty token means
that no avatar is set for the given contact.
</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.PermissionDenied"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
</tp:possible-errors>
</method>
<method name="RequestAvatar">
<arg direction="in" name="contact" type="u" tp:type="Contact_Handle">
<tp:docstring>
An integer handle for the contact to request the avatar for
</tp:docstring>
</arg>
<arg direction="out" type="ay">
<tp:docstring>
An array of bytes containing the image data
</tp:docstring>
</arg>
<arg direction="out" type="s">
<tp:docstring>
A string containing the image MIME type (eg image/jpeg), or empty if
unknown
</tp:docstring>
</arg>
<tp:docstring>
Request the avatar for a given contact. Using this method in new
Telepathy clients is deprecated; use RequestAvatars instead.
</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 contact does not currently have an avatar.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
<method name="RequestAvatars">
<arg direction="in" name="contacts" type="au"
tp:type="Contact_Handle[]">
<tp:docstring>
The contacts to retrieve avatars for
</tp:docstring>
</arg>
<tp:docstring>
Request avatars for a number of contacts. The AvatarRetrieved signal
is emitted for each avatar retrieved. If the handles are valid but
retrieving an avatar fails (for any reason, including the contact not
having an avatar) the AvatarRetrieved signal is not emitted for that
contact.
</tp:docstring>
<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="SetAvatar">
<arg direction="in" name="avatar" type="ay">
<tp:docstring>
An array of bytes representing the avatar image data
</tp:docstring>
</arg>
<arg direction="in" name="mime_type" type="s">
<tp:docstring>
A string representing the image MIME type
</tp:docstring>
</arg>
<arg direction="out" type="s">
<tp:docstring>
The string token of the new avatar
</tp:docstring>
</arg>
<tp:docstring>
Set a new avatar image for this connection. The avatar image must
respect the requirements obtained by GetAvatarRequirements.
</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.PermissionDenied"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
</tp:possible-errors>
</method>
<method name="ClearAvatar">
<tp:added version="0.15.0" />
<tp:docstring>
Remove the avatar image for this connection.
</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>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for requesting avatars for contacts on a given connection,
receiving notification when avatars are changed, and publishing your own
avatar.</p>
<p>Avatars are identified by a unique (per contact) token which represents a
hash or timestamp (depending on the protocol) of the contacts' avatar data.
An empty token means that an avatar has not been set for this contact, and
a changed token implies the contact's avatar has changed, but the strings
should otherwise be considered opaque by clients.</p>
<p>A client should use GetAvatarTokens to request the tokens for the avatars
of all the contacts it is interested in when it connects. The avatars can
then be retreived using RequestAvatar for the corresponding contact.
Clients should bind to the AvatarChanged signal and request a new copy of
the avatar when a contacts' avatar token changes. Clients should cache the
token and data of each contact's avatar between connections, to avoid
repeatedly retrieving the same avatar.</p>
<p>To publish an avatar, a client should use SetAvatar to provide an image
which meets the requirements returned by the GetAvatarRequirements
function. On some protocols the avatar is stored on the server, so setting
the avatar is persistent, but on others it is transferred via a peer to
peer mechanism, so needs to be set every connection. Hence, on every
connection, clients should inspect the avatar token of the connection's
self handle, and set the avatar if it is an empty string (and may
optionally replace it if the token corresponds to a different avatar).</p>
<p>To remove the published avatar on protocols which have persistent avatars,
a client should use the ClearAvatar method. This method can safely be used
even if there is no avatar for this connection.</p>
</tp:docstring>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|
