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.