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
|
<?xml version="1.0" ?>
<node name="/Protocol_Interface_Presence1"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2009-2010 Collabora Ltd.</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="im.telepathy1.Protocol.Interface.Presence1">
<tp:added version="0.21.3">(as stable API)</tp:added>
<tp:requires interface="im.telepathy1.Protocol"/>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>An interface for protocols where it might be possible to set the
user's presence, and the supported presence types can be predicted
before connecting.</p>
<tp:rationale>
<p>This allows UIs to show or hide presence types that aren't
always supported, such as "invisible", while not online.</p>
</tp:rationale>
<p>The properties on this interface SHOULD be cached in the
<code>.manager</code> file, in the
<code>[Protocol <em>proto</em>]</code>
group. For each status <em>s</em> in
<tp:member-ref>Statuses</tp:member-ref>, that group should
contain a key of the form <code>status-<em>s</em></code> whose value
is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII
decimal integer, followed by a space-separated sequence of tokens
from the following set:</p>
<dl>
<dt>settable</dt>
<dd>If present, the user can set this status on themselves using
<tp:dbus-ref namespace="im.telepathy1.Connection.Interface.Presence1"
>SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self
in the <tp:type>Status_Spec</tp:type> struct.</dd>
<dt>message</dt>
<dd>If present, the user can set a non-empty message for this status;
this corresponds to Can_Have_Message in the
<tp:type>Status_Spec</tp:type> struct.</dd>
</dl>
<p>Unrecognised tokens MUST be ignored.</p>
<p>For instance, an XMPP connection manager might have this
<code>.manager</code> file:</p>
<pre>[Protocol jabber]
Interfaces=im.telepathy1.Protocol.Interface.Presence;
param-account=s required
param-password=s required
status-offline=1
status-unknown=7
status-error=8
status-hidden=5 settable message
status-xa=4 settable message
status-away=3 settable message
status-dnd=6 settable message
status-available=2 settable message
status-chat=2 settable message
</pre>
<p>which corresponds to these property values (using a Python-like
syntax):</p>
<pre>Statuses = {
'offline': (OFFLINE, False, False),
'unknown': (UNKNOWN, False, False),
'error': (ERROR, False, False),
'hidden': (HIDDEN, True, True),
'xa': (EXTENDED_AWAY, True, True),
'away': (AWAY, True, True),
'dnd': (BUSY, True, True),
'available': (AVAILABLE, True, True),
'chat': (AVAILABLE, True, True),
}
</pre>
</tp:docstring>
<property name="Statuses"
tp:name-for-bindings="Statuses"
type="a{s(ubb)}" tp:type="Status_Spec_Map" access="read"
tp:immutable="yes">
<tp:docstring>
<p>The statuses that might appear in the <tp:dbus-ref
namespace="im.telepathy1"
>Connection.Interface.Presence1.Statuses</tp:dbus-ref>
property on a connection to this protocol that supports
Presence. This property is immutable.</p>
<p>Depending on server capabilities, it is possible that not all
of these will actually appear on the Connection.</p>
</tp:docstring>
</property>
</interface>
</node>
|
