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
|
<tp:telepathy-types
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:mapping name="Channel_Class" array-name="Channel_Class_List">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Mapping representing a class of channels that can be requested
from a connection manager, can be handled by a user interface,
are supported by a contact, etc.</p>
<p>Classes of channel are identified by the fixed values of
a subset of their properties.</p>
<p>Channel classes SHOULD always include the keys
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
and
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
</p>
</tp:docstring>
<tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
<tp:docstring>
A D-Bus interface name, followed by a dot and a D-Bus property name.
</tp:docstring>
</tp:member>
<tp:member type="v" name="Value">
<tp:docstring>
The value of the property.
</tp:docstring>
</tp:member>
</tp:mapping>
<tp:struct name="Channel_Details" array-name="Channel_Details_List">
<tp:added version="0.17.11">(as stable API)</tp:added>
<tp:docstring>
Enough details of a channel that clients can work out how to dispatch
or handle it.
</tp:docstring>
<tp:member name="Channel" type="o">
<tp:docstring>
The object path of the channel.
</tp:docstring>
</tp:member>
<tp:member name="Properties" type="a{sv}"
tp:type="Qualified_Property_Value_Map">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Properties of the channel.</p>
<p>Connection managers MUST NOT include properties in this mapping
if their values can change. Clients MUST ignore properties
that appear in this mapping if their values can change.</p>
<tp:rationale>
<p>If properties that could change were included, the following
race condition would be likely to exist in some cases:</p>
<ul>
<li>NewChannels or Get("Channels") includes a property P with
value V1</li>
<li>Client creates a proxy object for the channel</li>
<li>The value of P changes to V2</li>
<li>Client connects to PChanged signal</li>
<li>Client should call Get("P") or GetAll here, to avoid the
race, but client's author has forgotten to do so</li>
<li>Proxy object thinks P == V1, but actually P == V2</li>
</ul>
<p>We've taken the opportunity to make the API encourage the
client author to get it right. Where possible, we intend that
properties whose value will be used in channel dispatching
or other "early" processing will be defined so that they are
immutable (can never change).</p>
</tp:rationale>
<p>Each dictionary MUST contain the keys
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>,
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>,
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandle</tp:dbus-ref>
and
<tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetID</tp:dbus-ref>.
</p>
<!-- FIXME: maybe also Requested, InitiatorHandle,
InitiatorID once they leave the FUTURE pseudo-interface -->
<tp:rationale>
<p>We expect these to be crucial to the channel-dispatching
process.</p>
</tp:rationale>
</tp:docstring>
</tp:member>
</tp:struct>
</tp:telepathy-types>
|
