1
1
<?xml version="1.0" ?>
2
<node name="/Connection_Interface_Forwarding" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
3
<tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
4
<tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
5
<tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
2
<node name="/Connection_Interface_Forwarding"
3
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
5
<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
6
<tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright>
7
<tp:copyright>Copyright © 2006 INdT </tp:copyright>
6
8
<tp:license xmlns="http://www.w3.org/1999/xhtml">
7
9
<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 02110-1301, USA.</p>
10
modify it under the terms of the GNU Lesser General Public
11
License as published by the Free Software Foundation; either
12
version 2.1 of the License, or (at your option) any later version.</p>
14
<p>This library is distributed in the hope that it will be useful,
15
but WITHOUT ANY WARRANTY; without even the implied warranty of
16
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17
Lesser General Public License for more details.</p>
19
<p>You should have received a copy of the GNU Lesser General Public
20
License along with this library; if not, write to the Free Software
21
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21
<interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding"
22
tp:causes-havoc='not well-tested'>
23
<tp:requires interface="org.freedesktop.Telepathy.Connection"/>
24
<signal name="ForwardingChanged" tp:name-for-bindings="Forwarding_Changed">
25
<arg name="Forward_To" type="u" tp:type="Contact_Handle">
27
An integer contact handle to forward communication to
31
Emitted when the forwarding contact handle for this connection has been
32
changed. An zero handle indicates forwarding is disabled.
25
<interface name="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT"
26
tp:causes-havoc="experimental">
27
<tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
29
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
30
<p>This connection interface is for protocols that are capable of
31
signaling to remote contacts that incoming communication channels
32
should be instead sent to a separate contact. This might apply to
33
things such as call forwarding, for example.</p>
35
<p>In some cases, a CM may register forwarding rules with an external
36
service; in those cases, it will never see the incoming channel, and
37
the forwarding will happen automatically.</p>
39
<p>In other cases, the CM will handle the forwarding itself. When an
40
incoming channel is detected, the status of the local user will
41
determine whether or not a forwarding rule is matched. For some
42
rules, this MAY happen immediately (ie, if the user is Busy); for
43
others, there MAY be a timeout (in seconds) that must expire
44
before the forwarding rule is matched (the timeout is specified
45
by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p>
47
<p>Once a forwarding rule is matched and any necessary timeouts have
48
expired, the CM can forward the incoming channel to the specified
49
handle. If for whatever reason the remote handle does not accept
50
the channel AND the CM supports multiple forwarding entries AND
51
any necessary timeouts have expired (specified by the next entry
52
in the list), the CM can forward the incoming channel to the next
53
handle in the entry list. This continues until the list is
54
exhausted, or the incoming channel is accepted.</p>
56
<p>Note that the rule matches are only for the first entry in the
57
in the forwarding rule list. Once the incoming channel has been
58
forwarded, the next entry in the list (assuming one exists and
59
the contact that the channel has been forwarded to does not respond
60
after any necessary timeouts) is used regardless of the status of
61
the forwarded channel. The initial match rule might have been
62
Busy, whereas the contact that the channel has been forwarded to
63
might be offline. Even in this case, the Busy list is still
64
traversed until the channel is handled (or there are no more
65
forwarding entries in the list).</p>
67
<p>For example, assuming the following dict for Forwarding_Rules:</p>
70
Busy: ( initial-timeout: 30, [
71
(handle: 3, timeout: 15),
72
(handle: 5, timeout: 20)
74
NoReply: ( initial-timeout: 15, [
75
(handle: 5, timeout: 30),
76
(handle: 3, timeout: 20)
80
<p>We can imagine a scenario where an incoming channel is detected,
81
the media stream is available (ie, not Busy),
82
and the local user is online. While the CM is waiting for the local user to
83
accept the channel, it looks at NoReply's first timeout value. After 15s if
84
the local user hasn't accepted, the CM forwards the channel to Handle #5. The
85
CM then waits 30s for Handle #5 to accept the channel. If after 30s it does
86
not, the CM forwards the incoming channel to Handle #3, which will have
87
20s to accept the channel.</p>
90
<tp:enum name="Forwarding_Condition" type="u">
92
The various forwarding conditions that are supported by this interface.
93
In general, the conditions should not overlap; it should be very clear
94
which rule would be chosen given a CM's behavior with an incoming
95
channel. The exception to this is Unconditional,
96
which will override all other rules.
99
<tp:enumvalue value="0" suffix="Unconditional">
101
Incoming channels should always be forwarded. Note that setting this
102
will override any other rules. If not set, other rules will
103
be checked when an incoming communication channel is detected.
107
<tp:enumvalue value="1" suffix="Busy">
109
<p>The incoming channel should be forwarded if a busy signal is
110
detected. What defines "Busy" is CM-specific (perhaps a single
111
resource is already in use, or a user's status is set to Busy
112
<tp:type>Connection_Presence_Type</tp:type>).</p>
113
<p>If initial timeout is specified for Busy condition and call
114
waiting is not supported by the service, the timeout will be
119
<tp:enumvalue value="2" suffix="No_Reply">
121
The incoming channel should be forwarded if the local user doesn't
122
accept it within the specified amount of time.
126
<tp:enumvalue value="3" suffix="Not_Reachable">
128
The incoming channel should be forwarded if the user is offline.
129
This could be a manual setting (the user has chosen to set their
130
presence to offline or invisible) or something specified by the
131
underlying network (the user is not within range of a cell tower).
136
<tp:struct name="Forwarding_Rule_Entry"
137
array-name="Forwarding_Rule_Entry_List">
138
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
139
<p>A forwarding rule entry. These MAY be chained together
140
for CMs that support chaining of forwards (in other words,
141
a forwarding rule may have multiple entries; if the contact
142
in the first entry doesn't respond, the incoming channel
143
might be forwarded to the contact in the second entry).</p>
145
<p>For CMs and protocols that don't support chaining of
146
entries, only the first entry would be used.</p>
149
<tp:member type="u" name="Timeout">
151
<p>The length of time (in seconds) to wait the contact to respond
152
to the forwarded channel. This MAY be ignored by the CM if it
153
isn't supported by the underlying network/protocol for the
154
specific status of the remote contact (for example, a GSM call
155
that is forwarded may return Not_Reachable immediately without
156
waiting for the timeout value to expire).</p>
157
<p>A value of 0 means the condition can match immediately. A
158
value of MAX_UINT32 means that the CM's default should be
163
<tp:member type="u" tp:type="Contact_Handle" name="Handle">
165
The contact to forward an incoming channel to. If the handle
166
doesn't point to anything (e.g. points to a phone number that
167
doesn't exist), the entry SHOULD be skipped.
172
<tp:struct name="Forwarding_Rule_Chain">
174
A chain of forwarding rules and an initial timeout after which
175
the rules are applied.
178
<tp:member type="u" name="InitialTimeout">
179
<tp:docstring>Initial timeout for the rule.</tp:docstring>
182
<tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]">
183
<tp:docstring>The forwarding targets (an array of type
184
<tp:type>Forwarding_Rule_Entry</tp:type>).
189
<tp:mapping name="Forwarding_Rule_Map" array-name="">
190
<tp:docstring>A dictionary whose keys are forwarding conditions and
191
whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs.
194
<tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
195
<tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain"
199
<tp:mapping name="Supported_Forwarding_Conditions_Map" array-name="">
200
<tp:docstring>A dictionary whose keys are forwarding conditions and
201
whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
204
<tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
205
<tp:member type="u" name="Chain_Length" />
208
<property name="SupportedForwardingConditions" type="a{uu}" access="read"
209
tp:type="Supported_Forwarding_Conditions_Map"
210
tp:name-for-bindings="Supported_Forwarding_Conditions">
213
A map of forwarding conditions supported on this connection to
214
maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
215
supported for the specific condition.
217
When forwarding is done by the provider, different providers
218
might support different chain sizes, or provider and local
219
implementation chain sizes might differ.
225
<property name="ForwardingRules" type="a{u(ua(uu))}" access="read"
226
tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules">
228
<p>The current forwarding rules that are enabled for this connection.
229
Forwarding rules each contain an array of type
230
<tp:type>Forwarding_Rule_Entry</tp:type>.</p>
234
<signal name="ForwardingRuleChanged"
235
tp:name-for-bindings="Forwarding_Rule_Changed">
236
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
237
<p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p>
239
<p>By the time this is emitted, the property MUST have been updated
240
with the new rules being active. If any protocol/network
241
requests must be made, they should be completed before the signal
245
<arg name="Condition" type="u" tp:type="Forwarding_Condition">
247
The condition of the forwarding rule that's been changed.
251
<arg name="Timeout" type="u">
253
The new initial timeout for the rule.
257
<arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
259
The new (and as of the emission of the signal, currently active)
260
forwards. The order is relevant; those at the lowest array index
35
<method name="GetForwardingHandle"
36
tp:name-for-bindings="Get_Forwarding_Handle">
37
<arg direction="out" type="u" tp:type="Contact_Handle">
39
An integer contact handle to whom incoming communication is forwarded
43
Returns the current forwarding contact handle, or zero if none is set.
46
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
47
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
48
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
51
<method name="SetForwardingHandle"
52
tp:name-for-bindings="Set_Forwarding_Handle">
53
<arg direction="in" name="Forward_To" type="u" tp:type="Contact_Handle">
55
An integer contact handle to forward incoming communications to
59
Set a contact handle to forward incoming communications to. A zero
60
handle disables forwarding.
63
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
64
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
65
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable"/>
66
<tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
67
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
71
A connection interface for services which can signal to contacts
72
that they should instead contact a different user ID, effectively
73
forwarding all incoming communication channels to another contact on
266
<method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule">
268
Update the forwarding rules.
271
<arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition">
273
<p>The forwarding rule to override. Note that this SHOULD not affect
274
other rules; setting a rule that overrides others (such as
275
Forwarding_Rule_Unconditional) will not modify other rules. This
276
means that when a client sets Forwarding_Rule_Busy and then
277
temporarily sets Forwarding_Rule_Unconditional, the
278
Forwarding_Rule_Busy rule will retain settings after
279
Forwarding_Rule_Unconditional, has been unset.</p>
281
<p>If the CM has no choice but to adjust multiple rules after a call
282
to this function (ie, due to the network or protocol forcing such
283
behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref>
284
signals for each changed rule. The order of the signals is
285
implementation-dependent, with the only requirement that the
286
last signal is for the rule that was originally requested to have
287
been changed (e.g. if Unconditional automatically modifies
288
Busy and NoReply, three
289
separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the
290
last signal being for Forwarding_Rule_Unconditional).</p>
292
<p>Each forwarding condition will occur no more than once in
293
the rule array. Setting a rule will overwrite the old rule
294
with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p>
298
<arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
300
The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to
301
activate for the rule. An empty array will effectively disable the
306
<arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
308
The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>).
309
This is the list of entries that is being replaced with the call to
310
<tp:member-ref>SetForwardingRule</tp:member-ref>.
314
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
315
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
316
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
318
The specified Condition is not supported by this connection,
319
or the number of chained
320
<tp:member-ref>SupportedForwardingConditions</tp:member-ref> should
321
be checked prior to calling
322
<tp:member-ref>SetForwardingRule</tp:member-ref>.
325
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
327
A Handle that has been supplied is invalid.
330
</tp:possible-errors>
78
335
<!-- vim:set sw=2 sts=2 et ft=xml: -->
added
removed
spec/Connection_Interface_Forwarding.xml
