summaryrefslogtreecommitdiff
path: root/spec/Protocol_Interface_Presence1.xml
blob: a0cc125880b457147012ceec5fd3539416407643 (plain)
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>