Copyright © 2005-2010 Nokia Corporation Copyright © 2005-2010 Collabora Ltd. Copyright © 2006 INdT

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.

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.

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.

(draft version, not API-stable)

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.

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.

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 Forwarding_Rule_Entry list).

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.

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).

For example, assuming the following dict for Forwarding_Rules:

        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)
          ])
        }

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.

When an unanswered Call1 call is forwarded, both the contact and the self handle should be removed from the group with the self handle as the actor, and Channel_Group_Change_Reason No_Answer or Busy, as appropriate. For Call1 channels, the Call_State_Change_Reason Forwarded should be used.

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. 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.

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 Connection_Presence_Type).

If initial timeout is specified for Busy condition and call waiting is not supported by the service, the timeout will be ignored.

The incoming channel should be forwarded if the local user doesn't accept it within the specified amount of time. 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).

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).

For CMs and protocols that don't support chaining of entries, only the first entry would be used.

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).

A value of 0 means the condition can match immediately. A value of MAX_UINT32 means that the CM's default should be used.

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.
A chain of forwarding rules and an initial timeout after which the rules are applied. Initial timeout for the rule. The forwarding targets (an array of type Forwarding_Rule_Entry). A dictionary whose keys are forwarding conditions and whose values are Forwarding_Rule_Chain structs. A dictionary whose keys are forwarding conditions and whose values are maximum number of Forwarding_Rule_Entry for the condition.

A map of forwarding conditions supported on this connection to maximum number of Forwarding_Rule_Entry supported for the specific condition.

When forwarding is done by the provider, different providers might support different chain sizes, or provider and local implementation chain sizes might differ.

The current forwarding rules that are enabled for this connection. Forwarding rules each contain an array of type Forwarding_Rule_Entry.

Emitted when the ForwardingRules property changes.

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.

The condition of the forwarding rule that's been changed. The new initial timeout for the rule. 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.
Update the forwarding rules.

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.

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 ForwardingRuleChanged 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 ForwardingRuleChanged signals should be raised with the last signal being for Forwarding_Rule_Unconditional).

Each forwarding condition will occur no more than once in the rule array. Setting a rule will overwrite the old rule with the same Forwarding_Condition in its entirety.

The forwarding targets (an array of type Forwarding_Rule_Entry) to activate for the rule. An empty array will effectively disable the rule. The old forwarding targets (an array of type Forwarding_Rule_Entry). This is the list of entries that is being replaced with the call to SetForwardingRule. The specified Condition is not supported by this connection, or the number of chained SupportedForwardingConditions should be checked prior to calling SetForwardingRule. A Handle that has been supplied is invalid.