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 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346
|
<?xml version="1.0" ?>
<node name="/Connection_Interface_Forwarding"
xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
<tp:copyright>Copyright © 2005-2010 Collabora Ltd.</tp:copyright>
<tp:copyright>Copyright © 2006 INdT </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="org.freedesktop.Telepathy.Connection.Interface.Forwarding.DRAFT"
tp:causes-havoc="experimental">
<tp:added version="0.19.6">(draft version, not API-stable)</tp:added>
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>This connection interface is for protocols that are capable of
signaling to remote contacts that incoming communication channels
should be instead sent to a separate contact. This might apply to
things such as call forwarding, for example.</p>
<p>In some cases, a CM may register forwarding rules with an external
service; in those cases, it will never see the incoming channel, and
the forwarding will happen automatically.</p>
<p>In other cases, the CM will handle the forwarding itself. When an
incoming channel is detected, the status of the local user will
determine whether or not a forwarding rule is matched. For some
rules, this MAY happen immediately (ie, if the user is Busy); for
others, there MAY be a timeout (in seconds) that must expire
before the forwarding rule is matched (the timeout is specified
by the first element in the <tp:type>Forwarding_Rule_Entry</tp:type> list).</p>
<p>Once a forwarding rule is matched and any necessary timeouts have
expired, the CM can forward the incoming channel to the specified
handle. If for whatever reason the remote handle does not accept
the channel AND the CM supports multiple forwarding entries AND
any necessary timeouts have expired (specified by the next entry
in the list), the CM can forward the incoming channel to the next
handle in the entry list. This continues until the list is
exhausted, or the incoming channel is accepted.</p>
<p>Note that the rule matches are only for the first entry in the
in the forwarding rule list. Once the incoming channel has been
forwarded, the next entry in the list (assuming one exists and
the contact that the channel has been forwarded to does not respond
after any necessary timeouts) is used regardless of the status of
the forwarded channel. The initial match rule might have been
Busy, whereas the contact that the channel has been forwarded to
might be offline. Even in this case, the Busy list is still
traversed until the channel is handled (or there are no more
forwarding entries in the list).</p>
<p>For example, assuming the following dict for Forwarding_Rules:</p>
<pre>
ForwardingRules = {
Busy: ( initial-timeout: 30, [
(handle: 3, timeout: 15),
(handle: 5, timeout: 20)
]),
NoReply: ( initial-timeout: 15, [
(handle: 5, timeout: 30),
(handle: 3, timeout: 20)
])
}</pre>
<p>We can imagine a scenario where an incoming channel is detected,
the media stream is available (ie, not Busy),
and the local user is online. While the CM is waiting for the local user to
accept the channel, it looks at NoReply's first timeout value. After 15s if
the local user hasn't accepted, the CM forwards the channel to Handle #5. The
CM then waits 30s for Handle #5 to accept the channel. If after 30s it does
not, the CM forwards the incoming channel to Handle #3, which will have
20s to accept the channel.</p>
<p>When an unanswered <tp:dbus-ref
namespace='ofdT.Channel.Type'>StreamedMedia</tp:dbus-ref> call is
forwarded, both the contact and the self handle should be removed from
the group with the self handle as the actor, and
<tp:type>Channel_Group_Change_Reason</tp:type> <code>No_Answer</code> or
<code>Busy</code>, as appropriate. For <tp:dbus-ref
namespace='ofdT.Channel.Type'>Call1</tp:dbus-ref> channels, the
<tp:type>Call_State_Change_Reason</tp:type> <code>Forwarded</code>
should be used.</p>
</tp:docstring>
<tp:enum name="Forwarding_Condition" type="u">
<tp:docstring>
The various forwarding conditions that are supported by this interface.
In general, the conditions should not overlap; it should be very clear
which rule would be chosen given a CM's behavior with an incoming
channel. The exception to this is Unconditional,
which will override all other rules.
</tp:docstring>
<tp:enumvalue value="0" suffix="Unconditional">
<tp:docstring>
Incoming channels should always be forwarded. Note that setting this
will override any other rules. If not set, other rules will
be checked when an incoming communication channel is detected.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue value="1" suffix="Busy">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The incoming channel should be forwarded if a busy signal is
detected. What defines "Busy" is CM-specific (perhaps a single
resource is already in use, or a user's status is set to Busy
<tp:type>Connection_Presence_Type</tp:type>).</p>
<p>If initial timeout is specified for Busy condition and call
waiting is not supported by the service, the timeout will be
ignored.</p>
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue value="2" suffix="No_Reply">
<tp:docstring>
The incoming channel should be forwarded if the local user doesn't
accept it within the specified amount of time.
</tp:docstring>
</tp:enumvalue>
<tp:enumvalue value="3" suffix="Not_Reachable">
<tp:docstring>
The incoming channel should be forwarded if the user is offline.
This could be a manual setting (the user has chosen to set their
presence to offline or invisible) or something specified by the
underlying network (the user is not within range of a cell tower).
</tp:docstring>
</tp:enumvalue>
</tp:enum>
<tp:struct name="Forwarding_Rule_Entry"
array-name="Forwarding_Rule_Entry_List">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A forwarding rule entry. These MAY be chained together
for CMs that support chaining of forwards (in other words,
a forwarding rule may have multiple entries; if the contact
in the first entry doesn't respond, the incoming channel
might be forwarded to the contact in the second entry).</p>
<p>For CMs and protocols that don't support chaining of
entries, only the first entry would be used.</p>
</tp:docstring>
<tp:member type="u" name="Timeout">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The length of time (in seconds) to wait the contact to respond
to the forwarded channel. This MAY be ignored by the CM if it
isn't supported by the underlying network/protocol for the
specific status of the remote contact (for example, a GSM call
that is forwarded may return Not_Reachable immediately without
waiting for the timeout value to expire).</p>
<p>A value of 0 means the condition can match immediately. A
value of MAX_UINT32 means that the CM's default should be
used.</p>
</tp:docstring>
</tp:member>
<tp:member type="u" tp:type="Contact_Handle" name="Handle">
<tp:docstring>
The contact to forward an incoming channel to. If the handle
doesn't point to anything (e.g. points to a phone number that
doesn't exist), the entry SHOULD be skipped.
</tp:docstring>
</tp:member>
</tp:struct>
<tp:struct name="Forwarding_Rule_Chain">
<tp:docstring>
A chain of forwarding rules and an initial timeout after which
the rules are applied.
</tp:docstring>
<tp:member type="u" name="InitialTimeout">
<tp:docstring>Initial timeout for the rule.</tp:docstring>
</tp:member>
<tp:member type="a(uu)" name="Rules" tp:type="Forwarding_Rule_Entry[]">
<tp:docstring>The forwarding targets (an array of type
<tp:type>Forwarding_Rule_Entry</tp:type>).
</tp:docstring>
</tp:member>
</tp:struct>
<tp:mapping name="Forwarding_Rule_Map" array-name="">
<tp:docstring>A dictionary whose keys are forwarding conditions and
whose values are <tp:type>Forwarding_Rule_Chain</tp:type> structs.
</tp:docstring>
<tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
<tp:member type="(ua(uu))" tp:type="Forwarding_Rule_Chain"
name="Rule_Chain" />
</tp:mapping>
<tp:mapping name="Supported_Forwarding_Conditions_Map" array-name="">
<tp:docstring>A dictionary whose keys are forwarding conditions and
whose values are maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
for the condition.
</tp:docstring>
<tp:member type="u" tp:type="Forwarding_Condition" name="Condition" />
<tp:member type="u" name="Chain_Length" />
</tp:mapping>
<property name="SupportedForwardingConditions" type="a{uu}" access="read"
tp:type="Supported_Forwarding_Conditions_Map"
tp:name-for-bindings="Supported_Forwarding_Conditions">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>A map of forwarding conditions supported on this connection to
maximum number of <tp:type>Forwarding_Rule_Entry</tp:type>
supported for the specific condition.</p>
<tp:rationale>
<p>When forwarding is done by the provider, different providers
might support different chain sizes, or provider and local
implementation chain sizes might differ.</p>
</tp:rationale>
</tp:docstring>
</property>
<property name="ForwardingRules" type="a{u(ua(uu))}" access="read"
tp:type="Forwarding_Rule_Map" tp:name-for-bindings="Forwarding_Rules">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The current forwarding rules that are enabled for this connection.
Forwarding rules each contain an array of type
<tp:type>Forwarding_Rule_Entry</tp:type>.</p>
</tp:docstring>
</property>
<signal name="ForwardingRuleChanged"
tp:name-for-bindings="Forwarding_Rule_Changed">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>Emitted when the <tp:member-ref>ForwardingRules</tp:member-ref> property changes.</p>
<p>By the time this is emitted, the property MUST have been updated
with the new rules being active. If any protocol/network
requests must be made, they should be completed before the signal
is emitted.</p>
</tp:docstring>
<arg name="Condition" type="u" tp:type="Forwarding_Condition">
<tp:docstring>
The condition of the forwarding rule that's been changed.
</tp:docstring>
</arg>
<arg name="Timeout" type="u">
<tp:docstring>
The new initial timeout for the rule.
</tp:docstring>
</arg>
<arg name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
<tp:docstring>
The new (and as of the emission of the signal, currently active)
forwards. The order is relevant; those at the lowest array index
are used first.
</tp:docstring>
</arg>
</signal>
<method name="SetForwardingRule" tp:name-for-bindings="Set_Forwarding_Rule">
<tp:docstring>
Update the forwarding rules.
</tp:docstring>
<arg direction="in" name="Condition" type="u" tp:type="Forwarding_Condition">
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
<p>The forwarding rule to override. Note that this SHOULD not affect
other rules; setting a rule that overrides others (such as
Forwarding_Rule_Unconditional) will not modify other rules. This
means that when a client sets Forwarding_Rule_Busy and then
temporarily sets Forwarding_Rule_Unconditional, the
Forwarding_Rule_Busy rule will retain settings after
Forwarding_Rule_Unconditional, has been unset.</p>
<p>If the CM has no choice but to adjust multiple rules after a call
to this function (ie, due to the network or protocol forcing such
behavior), the CM MUST emit multiple <tp:member-ref>ForwardingRuleChanged</tp:member-ref>
signals for each changed rule. The order of the signals is
implementation-dependent, with the only requirement that the
last signal is for the rule that was originally requested to have
been changed (e.g. if Unconditional automatically modifies
Busy and NoReply, three
separate <tp:member-ref>ForwardingRuleChanged</tp:member-ref> signals should be raised with the
last signal being for Forwarding_Rule_Unconditional).</p>
<p>Each forwarding condition will occur no more than once in
the rule array. Setting a rule will overwrite the old rule
with the same <tp:type>Forwarding_Condition</tp:type> in its entirety.</p>
</tp:docstring>
</arg>
<arg direction="in" name="Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
<tp:docstring>
The forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>) to
activate for the rule. An empty array will effectively disable the
rule.
</tp:docstring>
</arg>
<arg direction="out" name="Old_Forwards" type="a(uu)" tp:type="Forwarding_Rule_Entry[]">
<tp:docstring>
The old forwarding targets (an array of type <tp:type>Forwarding_Rule_Entry</tp:type>).
This is the list of entries that is being replaced with the call to
<tp:member-ref>SetForwardingRule</tp:member-ref>.
</tp:docstring>
</arg>
<tp:possible-errors>
<tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
<tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
<tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
<tp:docstring>
The specified Condition is not supported by this connection,
or the number of chained
<tp:member-ref>SupportedForwardingConditions</tp:member-ref> should
be checked prior to calling
<tp:member-ref>SetForwardingRule</tp:member-ref>.
</tp:docstring>
</tp:error>
<tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle">
<tp:docstring>
A Handle that has been supplied is invalid.
</tp:docstring>
</tp:error>
</tp:possible-errors>
</method>
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
|