2
<node name="/Client_Observer"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
4
<tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
5
<tp:copyright>Copyright (C) 2008 Nokia Corporation</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.Client.Observer.DRAFT"
24
tp:causes-havoc="experimental">
25
<tp:added version="0.17.12">(as a draft)</tp:added>
27
<tp:requires interface="org.freedesktop.Telepathy.Client.DRAFT"/>
29
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
30
<p>Observers monitor the creation of new channels. This
31
functionality can be used for things like message logging.
32
All observers are notified simultaneously.</p>
34
<p>Observers SHOULD NOT modify the state of a channel except
35
via user interaction.</p>
38
<p>We want Observer UIs for file transfer channels (a progress
39
bar for the transfer) to be able to have a Cancel button.</p>
42
<p>Observers MUST NOT carry out actions that exactly one process
43
must take responsibility for (e.g. acknowledging Text
44
messages, or carrying out the actual transfer in a file transfer
48
<p>Since arbitrarily many observers can be activated for
49
each channel, it would not make sense for observers to do things
50
that can only be done by one process (acknowledging
52
namespace="org.freedesktop.Telepathy.Channel.Type">Text</tp:dbus-ref>
53
messages, carrying out streaming for
55
namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
56
channels, doing the actual data transfer for file transfers,
57
setting up the out-of-band connection for Tubes). The
59
namespace="org.freedesktop.Telepathy.Client">Handler</tp:dbus-ref>
60
is responsible for such tasks.</p>
62
<p>Handlers MAY, of course, delegate responsibility for these
63
tasks to other processes (including those run as observers),
64
but this MUST be done explicitly via a request from the Handler
68
<p>Whenever new channels are signalled, the channel dispatcher
69
will notify all running or activatable observers whose
70
<tp:member-ref>ObserverChannelFilter</tp:member-ref> property
71
(possibly as cached in the .client file) indicates that they are
72
interested in the channel.</p>
74
<p>Observers are activated for all channels in which they have
75
registered an interest - incoming, outgoing or automatically created -
76
although of course the ObserverChannelFilter property can be set
79
namespace="org.freedesktop.Telepathy.Channel">Requested</tp:dbus-ref>
83
<property name="ObserverChannelFilter"
84
tp:name-for-bindings="Observer_Channel_Filter"
85
type="aa{sv}" access="read" tp:type="Channel_Class[]">
86
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
87
<p>A specification of the channels in which this observer is
88
interested. The <tp:member-ref>ObserveChannels</tp:member-ref> method
89
should be called by the channel dispatcher whenever any of the new
90
channels in a NewChannels signal match this description.</p>
92
<p>(FIXME: open issue: do we want this, and the corresponding
93
Approver and Handler properties, to be able to change at
96
<p>Only certain D-Bus types have useful semantics for matching like this,
97
so only certain types are allowed:</p>
100
<dt>Integers of all sizes, including byte (y, n, q, i, u, x, t)</dt>
101
<dd>Matched by numeric value, regardless of type (e.g. 42 as a
102
16-bit signed integer 'n' is considered equal to 42 as a 32-bit
103
unsigned integer 'u')</dd>
105
<dt>Booleans (b)</dt>
106
<dd>Matched by equality in the obvious way; not considered equal to any
110
<dd>Matched by equality in the obvious way; not considered equal to any
113
<dt>Object paths (o)</dt>
114
<dd>Matched by equality in the obvious way; not considered equal to any
119
<p>This property never changes while the observer process is
120
running. For activatable processes, the filter can change due to an
121
upgrade - the channel dispatcher SHOULD observe changes to .client files
122
using a mechanism like inotify.</p>
124
<p>For observers that have a .client file, the channel dispatcher
125
may discover this property from keys of the form
126
<code><em>propertyname</em>/<em>type</em></code>,
127
in groups in the .client file whose name is the name of this
128
interface followed by <code>.ObserverChannelFilter</code>,
129
a space and an ASCII decimal number starting from 0.</p>
131
<p>Integers in the .client file are encoded in ASCII decimal, booleans
132
are encoded as "true" or "false", and strings are encoded in the usual
133
way for desktop files (including the C-style backslash escapes
134
documented in the Desktop Entry specification).</p>
136
<p>For instance, a .client file for an observer that is only interested
137
in Text channels, with CONTACT or ROOM handles, that were requested by
141
[org.freedesktop.Telepathy.Client.DRAFT]
142
Interfaces=org.freedesktop.Telepathy.Client.Observer.DRAFT;
144
[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 0]
145
org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
146
org.freedesktop.Telepathy.Channel.TargetHandleType u=1
147
org.freedesktop.Telepathy.Channel.Requested b=true
149
[org.freedesktop.Telepathy.Client.Observer.DRAFT.ObserverChannelFilter 1]
150
org.freedesktop.Telepathy.Channel.Type s=org.freedesktop.Telepathy.Channel.Type.Text
151
org.freedesktop.Telepathy.Channel.TargetHandleType u=2
152
org.freedesktop.Telepathy.Channel.Requested b=true
158
<method name="ObserveChannels" tp:name-for-bindings="Observe_Channels">
159
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
160
<p>Called by the channel dispatcher when channels in which the
161
observer has registered an interest are created.</p>
163
<p>The observer MUST NOT return from this method call until it is ready
164
for a handler for the channel to run (which may change the channel's
168
<p>The channel dispatcher must wait for observers to start up,
169
to avoid the following race: text channel logger (observer) gets
170
ObserveChannel, text channel handler gets
172
namespace="org.freedesktop.Telepathy.Client.Handler.DRAFT">HandleChannels</tp:dbus-ref>
173
channel handler starts up faster and acknowledges messages,
174
logger never sees those messages.</p>
178
<arg name="Account" type="o" direction="in">
181
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref>
182
with which the channels are associated. The
183
well-known bus name to use is that of the
184
<tp:dbus-ref namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>.
188
<arg name="Connection" type="o" direction="in">
191
<tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref>
192
with which the channels are associated. The
193
well-known bus name to use can be derived from this object
194
path by removing the leading '/' and replacing all subsequent
199
<arg name="Channels" type="a(oa{sv})" tp:type="Channel_Details[]"
203
namespace="org.freedesktop.Telepathy">Channel</tp:dbus-ref>s
204
and their properties. Their well-known bus names are all the same as
205
that of the Connection.
209
<arg name="DispatchOperation" type="o" direction="in">
211
The path to the <tp:dbus-ref
212
namespace="org.freedesktop.Telepathy">ChannelDispatchOperation.DRAFT</tp:dbus-ref>
213
for these channels, or the special value '/' if there is no
214
ChannelDispatchOperation (because the channels were requested, not incoming).
217
This allows an Observer to <tp:dbus-ref
218
namespace="org.freedesktop.Telepathy.ChannelDispatchOperation.DRAFT">Claim</tp:dbus-ref>
219
a set of channels without having to match up calls to this method
220
with calls to <tp:dbus-ref
221
namespace="org.freedesktop.Telepathy.Client.Approver.DRAFT">AddDispatchOperation</tp:dbus-ref>.
226
<arg name="Observer_Info" type="a{sv}" direction="in">
227
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
228
<p>Additional information about these channels. No keys are
229
currently defined.</p>
231
<p>If keys are defined for this dictionary, all will be optional;
232
observers MAY safely ignore any entry in this dictionary.</p>
240
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Client_Observer.xml
