Processing Outgoing Call Redirection in PJSUA-LIB

This article describes SIP redirection support in PJSUA-LIB, that is implemented by ticket #456.

Outgoing Call Redirection and Multiple Targets

The redirection in this article is about following (or not) redirection response (SIP 3xx code) in outgoing call, and not about sending redirection/3xx response. Sending 3xx response in PJSUA-LIB is easy; just use pjsua_call_hangup() and give the new targets in Contact header in msg_data parameter.

The SIP redirection support in PJSUA-LIB is implemented as subset of generic multiple call targeting support. Multiple call targeting is a neat new feature in PJSUA-LIB that allows a single outgoing call to have multiple targets, which will be called sequentially until one of the target picks up the call. Some use cases of this feature are as follows.

Redirection

Redirection (by means of SIP 3xx response) is a natural use case of multiple call targeting. In this scenario, the original INVITE is rejected with redirection response (SIP 300-399 code) containing one or more targets (Contact header). Application then may instruct the call to follow the redirection, and the library will send a fresh INVITE request to the new target. This second INVITE may be redirected too, and once again application may instruct the call to follow the new target. And so on, the process continues until one of the target picks up the call, or all targets have been tried but none of them can accept the call, or the call has reached it's maximum number of targets allowed in a single call.

The process of retrying new targets will happen automatically without application having to make a new call (although it may do that if it wants to), and all invite requests belong to the same call id. That said, application still has the full control over accepting the redirection instruction. It may reject the redirection, it may accept it, it may accept only partial list of targets, and it may delay the acceptance if it wants to ask for user permission first.

Multiple Call Targeting

This is a neat feature of PJSUA-LIB, to give multiple targets to the outgoing call without having to receive 3xx response. Here is a sample use case.

Suppose you want to reach anybody in PJSIP, for example you have a show-stopper bug that needs to be fixed urgently. You do not care who should pick up the phone, all you care is that someone in PJSIP should answer your call (say, you are boiling mad that the application crashed, and you want somebody in PJSIP to hear about this). You know the SIP address of two persons in PJSIP, Perry and me.

So you dial Perry's URI, and also configure the (same) call with my URI as alternate target. If Perry picks up the phone, good, you can offload your rants to him. If he doesn't pick up the phone, the call will go to its alternate target, which is me (as long as Perry doesn't also redirect the call to his voice mail). Of course this is bad news for me, but you, the customer, is happy, and that's the main thing.

Configuring Multiple Targets

Both call redirection and multiple call targets are done with the same function below:

  PJ_DECL(pj_status_t) pjsua_call_manage_target(pjsua_call_id call_id,
                                                const pj_str_t *target,
                                                pjsip_status_code tgt_code,
                                                const pj_str_t *referer,
                                                float qvalue,
                                                const pjsua_msg_data *msg_data);

The parameters of the function are as follows:

call_id

The call ID of an outgoing call which status is not disconnected yet.

target

Target URI.

tgt_code

Operation to be applied to the target:

• value 100-199: the target will be added, but it will not be called until it's code is set to 2xx.
• value 200-299: the target will be added and called as soon as possible.
• value 300-699: the target will be removed from the list, if it's present.

referer

Optionally specify the URI of the referer, that is the URI of the original target which returned redirection response containing this target. This referer URI is used to calculate the priority of this new target. If referer is not used, the target priority will be calculated from the qvalue parameter instead.

qvalue

Priority value, from 0 to 1. Target with lower priority number will be called first. If application specify zero, then this target will be selected first for the next call, and if 1, this target will be called last.

msg_data

Optional list of headers etc to be added to outgoing call to this target.

Fore more information, please see the function documentation for details.

Redirection

For call redirection, there is new callback in pjsua_callback to notify application about redirection response from callee:

    void (*on_call_redirected)(pjsua_call_id call_id, 
			       unsigned target_cnt,
			       const pj_str_t target[],
			       pjsip_event *e);

Application would have to implement on_call_redirected() callback above, and call pjsua_call_manage_target() for each target that it wants the call to follow. As soon as the callback returns, the call will proceed with sending fresh invite to the new targets (provided that there is at least one target to try immediately. See pjsua_call_manage_target() documentation for more info).

Configuring Alternate Targets

For configuring alternate target to outgoing call without waiting for 3xx response, application can simply add the target with pjsua_call_manage_target() at any time before the call is disconnected (the best time would be immediately after making the call, if the alternate target has been known beforehand). This target will be tried as soon as the first target fails.