2
<node name="/Protocol_Interface_Presence"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
5
<tp:copyright>Copyright © 2009-2010 Collabora Ltd.</tp:copyright>
6
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
<p>This library is free software; you can redistribute it and/or
8
modify it under the terms of the GNU Lesser General Public
9
License as published by the Free Software Foundation; either
10
version 2.1 of the License, or (at your option) any later version.</p>
12
<p>This library is distributed in the hope that it will be useful,
13
but WITHOUT ANY WARRANTY; without even the implied warranty of
14
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
Lesser General Public License for more details.</p>
17
<p>You should have received a copy of the GNU Lesser General Public
18
License along with this library; if not, write to the Free Software
19
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
23
<interface name="org.freedesktop.Telepathy.Protocol.Interface.Presence.DRAFT"
24
tp:causes-havoc="experimental">
25
<tp:added version="0.19.8">(draft 1)</tp:added>
26
<tp:requires interface="org.freedesktop.Telepathy.Protocol"/>
28
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
29
<p>An interface for protocols where it might be possible to set the
30
user's presence, and the supported presence types can be predicted
31
before connecting.</p>
34
<p>This allows UIs to show or hide presence types that aren't
35
always supported, such as "invisible", while not online.</p>
38
<p>The properties on this interface SHOULD be cached in the
39
<code>.manager</code> file, in the
40
<code>[Protocol <em>proto</em>]</code>
41
group. For each status <em>s</em> in
42
<tp:member-ref>Statuses</tp:member-ref>, that group should
43
contain a key of the form <code>status-<em>s</em></code> whose value
44
is the <tp:type>Connection_Presence_Type</tp:type> as an ASCII
45
decimal integer, followed by a space-separated sequence of tokens
46
from the following set:</p>
50
<dd>If present, the user can set this status on themselves using
51
<tp:dbus-ref namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence"
52
>SetPresence</tp:dbus-ref>; this corresponds to May_Set_On_Self
53
in the <tp:type>Simple_Status_Spec</tp:type> struct.</dd>
56
<dd>If present, the user can set a non-empty message for this status;
57
this corresponds to Can_Have_Message in the
58
<tp:type>Simple_Status_Spec</tp:type> struct.</dd>
61
<p>Unrecognised tokens MUST be ignored.</p>
63
<p>For instance, an XMPP connection manager might have this
64
<code>.manager</code> file:</p>
66
<pre>[Protocol jabber]
67
Interfaces=org.freedesktop.Telepathy.Protocol.Interface.Presence;
68
param-account=s required
69
param-password=s required
73
status-hidden=5 settable message
74
status-xa=4 settable message
75
status-away=3 settable message
76
status-dnd=6 settable message
77
status-available=2 settable message
78
status-chat=2 settable message
81
<p>which corresponds to these property values (using a Python-like
85
'offline': (OFFLINE, False, False),
86
'unknown': (UNKNOWN, False, False),
87
'error': (ERROR, False, False),
88
'hidden': (HIDDEN, True, True),
89
'xa': (EXTENDED_AWAY, True, True),
90
'away': (AWAY, True, True),
91
'dnd': (BUSY, True, True),
92
'available': (AVAILABLE, True, True),
93
'chat': (AVAILABLE, True, True),
98
<property name="Statuses"
99
tp:name-for-bindings="Statuses"
100
type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map" access="read">
102
<p>The statuses that might appear in the <tp:dbus-ref
103
namespace="org.freedesktop.Telepathy"
104
>Connection.Interface.SimplePresence.Statuses</tp:dbus-ref>
105
property on a connection to this protocol that supports
106
SimplePresence. This property is immutable.</p>
108
<p>Depending on server capabilities, it is possible that not all
109
of these will actually appear on the Connection.</p>