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
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
|
<?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
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.Presence">
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
<!-- We hope to simplify these eventually -->
<tp:mapping name="Multiple_Status_Map">
<tp:docstring>Mapping used in Last_Activity_And_Statuses and passed to
SetStatus, 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 GetPresence and signalled by
PresenceUpdate, 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">
<arg direction="in" name="status" type="s">
<tp:docstring>
The string identifier of the desired status
</tp:docstring>
</arg>
<arg direction="in" name="parms" 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 PresenceUpdate
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: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 PresenceUpdate
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">
<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 PresenceUpdate
signal
</tp:docstring>
</arg>
<tp:docstring>
Get presence previously emitted by PresenceUpdate for the given
contacts. Data is returned in the same structure as the PresenceUpdate
signal. Using this method in favour of RequestPresence 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">
<arg direction="out" type="a{s(ubba{ss})}" tp:type="Status_Spec_Map">
<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">
<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 RequestPresence is available.
</tp:docstring>
</signal>
<method name="RemoveStatus">
<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 PresenceUpdate signals being
emitted. As with ClearStatus, 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">
<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 PresenceUpdate
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' Channel.Type.ContactList, 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">
<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">
<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>
Request that the user's presence be changed to the given statuses and
desired parameters. Changes will be reflected by PresenceUpdate
signals being emitted. 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.
</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: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 the Galago project
(see http://www.galago-project.org/).</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 GetStatuses
method.</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 following well-known values (in common with those in
Galago) should be used where possible to allow clients to identify common
choices:</p>
<ul>
<li>available</li>
<li>away</li>
<li>brb (Be Right Back)</li>
<li>busy</li>
<li>dnd (Do Not Disturb),</li>
<li>xa (Extended Away)</li>
<li>hidden (aka Invisible)</li>
<li>offline</li>
</ul>
<p>As well as these well-known status identifiers, every status also has a
numerical type value chosen from ConnectionPresenceType 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, PresenceUpdate 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, RequestPresence 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>
<tp:enum name="Connection_Presence_Type" type="u">
<tp:enumvalue suffix="Unset" value="0">
<tp:docstring>
An invalid presence type used as a null value
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Offline" value="1">
<tp:docstring>
Offline
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Available" value="2">
<tp:docstring>
Available
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Away" value="3">
<tp:docstring>
Away
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Extended_Away" value="4">
<tp:docstring>
Away for an extended time
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Hidden" value="5">
<tp:docstring>
Hidden (invisible)
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue suffix="Busy" value="6">
<tp:docstring>
Busy, Do Not Disturb.
</tp:docstring>
</tp:enumvalue>
</tp:enum>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|