Methods
SetForwardingRule | (u: Condition, a(uu): Forwards) | → | a(uu): Old_Forwards |
Signals
ForwardingRuleChanged | (u: Condition, u: Timeout, a(uu): Forwards) |
Properties
SupportedForwardingConditions | a{uu} ( Supported_Forwarding_Conditions_Map) | Read only | ||
ForwardingRules | a{u(ua(uu))} ( Forwarding_Rule_Map) | Read only |
Types
Forwarding_Condition | Enum | u | |
Forwarding_Rule_Map | Mapping | a{u(ua(uu))} | |
Supported_Forwarding_Conditions_Map | Mapping | a{uu} | |
Forwarding_Rule_Entry | Struct | (uu) | |
Forwarding_Rule_Chain | Struct | (ua(uu)) |
Description
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 StreamedMedia 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.
Methods
SetForwardingRule (u: Condition, a(uu): Forwards) → a(uu): Old_Forwards
Parameters
- Condition — u (Forwarding_Condition)
- Forwards — a(uu) (Forwarding_Rule_Entry_List)
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.
Returns
- Old_Forwards — a(uu) (Forwarding_Rule_Entry_List)
Possible Errors
- Disconnected
- Network Error
- Not Available
- Invalid Handle
Rationale:
Signals
ForwardingRuleChanged (u: Condition, u: Timeout, a(uu): Forwards)
Parameters
- Condition — u (Forwarding_Condition)
- Timeout — u
- Forwards — a(uu) (Forwarding_Rule_Entry_List)
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.
Properties
SupportedForwardingConditions — a{uu} (Supported_Forwarding_Conditions_Map)
A map of forwarding conditions supported on this connection to maximum number of Forwarding_Rule_Entry supported for the specific condition.
Rationale:
When forwarding is done by the provider, different providers might support different chain sizes, or provider and local implementation chain sizes might differ.
ForwardingRules — a{u(ua(uu))} (Forwarding_Rule_Map)
The current forwarding rules that are enabled for this connection. Forwarding rules each contain an array of type Forwarding_Rule_Entry.
Types
Forwarding_Condition — u
- Unconditional (0)
- Busy (1)
- No_Reply (2)
- Not_Reachable (3)
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.
Forwarding_Rule_Map — a{u(ua(uu))}
- Condition — u (Forwarding_Condition)
- Rule_Chain — (ua(uu)) (Forwarding_Rule_Chain)
Supported_Forwarding_Conditions_Map — a{uu}
- Condition — u (Forwarding_Condition)
- Chain_Length — u
Forwarding_Rule_Entry — (uu)
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.
- Timeout — u
- Handle — u (Contact_Handle)
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.
Forwarding_Rule_Chain — (ua(uu))
- InitialTimeout — u
- Rules — a(uu) (Forwarding_Rule_Entry_List)