Processing redirection (3xx) response
Note
This article is about processing SIP redirect (3xx)
response in outgoing calls, and not about sending redirection/3xx
response. Sending 3xx response in PJSUA-LIB can be accomplished by calling
pjsua_call_hangup()
and with the new targets in Contact header in
pjsua_msg_data
parameter.
Features
It is implemented all the way from PJSIP to PJSUA2 API level, to allow the usage on non-PJSUA-LIB based applications.
Handles multiple targets in the 3xx response (and targets that are returned in 3xx response of subsequent INVITE).
Allows application to accept or reject the redirection request on a per-target basis.
Allows application to defer the decision to accept or reject the redirection request, for example, to ask for user confirmation in the UI.
Remembers which targets have been sent INVITE and not retry the INVITE to these targets
Prioritize targets based on the q-value
Allows keeping or replacing the To URI in the subsequent INVITE requests, while keeping the same From, and Call-ID as the original INVITE.
Redirection with PJSIP API
Application MUST implement pjsip_inv_callback::on_redirected
callback
to handle redirection. If this callback is not implemented, the invite session will be
disconnected upon receipt of 3xx response.
Redirection handling is controlled by the return value of this callback. See
pjsip_redirect_op
for possible actions.
If application wishes to defer the redirection decision, it must return from the
callback with PJSIP_REDIRECT_PENDING
and call
pjsip_inv_process_redirect()
once it has decided
how to process the redirection.
The redirection usage scenarios will be explained below.
Accept redirection to this target
Return PJSIP_REDIRECT_ACCEPT
from the callback to accept the
redirection to this target. And INVITE session will be sent immediately
to the target.
Alternatively PJSIP_REDIRECT_ACCEPT_REPLACE
can be returned
to accept the redirection to the current target and
replace the To header in the INVITE request with the current target.
Reject redirection to this target
Return PJSIP_REDIRECT_REJECT
from the callback to reject the
redirection to this target. If there is another target to try, then the
callback will be called again with this next target, otherwise the
invite session will be disconnected immediately.
Stop redirection
Return PJSIP_REDIRECT_STOP
from the callback to stop the redirection
process and disconnect the call immediately, regardless of whether there
are more targets to try.
Defer the Decision
Return PJSIP_REDIRECT_PENDING
from the callback to tell the invite
session that a decision cannot be made that this time (for example to
ask for user approval), and the application will notify the invite
session about the decision later.
Once the application gets the user approval (or disapproval), it
MUST call pjsip_inv_process_redirect()
function to notify the
session about the decision. It may accept or reject the target, or stop
the redirection altogether by setting the appropriate value to the cmd
argument. It must not set PJSIP_REDIRECT_PENDING
to this argument.
Failure to call pjsip_inv_process_redirect()
will cause the invite
session to be kept alive indefinitely until the library is shutdown.
When the pjsip_inv_process_redirect()
function is called for the
next target in the context of this function (that is when this function
is called with reject command and next target is selected, hence the
callback is called), the event (e) argument passed to this function
will be passed down to the callback. And similarly when the disconnect
callback is called. If NULL is given to the event argument of this
function, this function will create a PJSIP_EVENT_USER
event with
NULL values, to be passed to the callbacks.
Because of this, application MUST be prepared to handle these type of
events in both the pjsip_inv_callback::on_redirected
and
pjsip_inv_callback::on_state_changed
callbacks. Traditionally only PJSIP_EVENT_TSX_STATE
event is passed
to pjsip_inv_callback::on_state_changed
callback.
Redirection with PJSUA-LIB API
Use the pjsua_callback::on_call_redirected
callback and
pjsua_call_process_redirect()
API to handle redirection.
See the PJSIP section above on how to use this feature.
Redirection with PJSUA2 API
Use the pj::Call::onCallRedirected()
and
pj::Call::processRedirect()
methods to handle redirection.
See the PJSIP section above on how to use this feature.
Redirection in pjsua application
Call redirection handling in pjsua is as follows:
Use command line argument
--accept-redirect
, with valid values:0
: reject/stop,1
: follow automatically (default),2
: ask
the default behavior is to follow redirection automatically
when
--accept-redirect
is set to 2 (ask), user can enterRa
,Rr
, orRd
to accept, reject, or stop/disconnect the redirection.