diff options
Diffstat (limited to 'pjsip/include/pjsua-lib/pjsua.h')
| -rw-r--r-- | pjsip/include/pjsua-lib/pjsua.h | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h index 1818f428..efc1c188 100644 --- a/pjsip/include/pjsua-lib/pjsua.h +++ b/pjsip/include/pjsua-lib/pjsua.h @@ -1062,6 +1062,54 @@ typedef struct pjsua_callback */ void (*on_nat_detect)(const pj_stun_nat_detect_result *res); + /** + * This callback is called when the call is about to resend the + * INVITE request to the specified target, following the previously + * received redirection response. + * + * Application may accept the redirection to the specified target + * (the default behavior if this callback is implemented), reject + * this target only and make the session continue to try the next + * target in the list if such target exists, stop the whole + * redirection process altogether and cause the session to be + * disconnected, or defer the decision to ask for user confirmation. + * + * This callback is optional. If this callback is not implemented, + * the default behavior is to NOT follow the redirection response. + * + * @param call_id The call ID. + * @param target The current target to be tried. + * @param cmd Action to be performed for the target. Set this + * parameter to one of the value below: + * - PJSIP_REDIRECT_ACCEPT: immediately accept the + * redirection (default value). When set, the + * call will immediately resend INVITE request + * to the target. + * - PJSIP_REDIRECT_REJECT: immediately reject this + * target. The call will continue retrying with + * next target if present, or disconnect the call + * if there is no more target to try. + * - PJSIP_REDIRECT_STOP: stop the whole redirection + * process and immediately disconnect the call. The + * on_call_state() callback will be called with + * PJSIP_INV_STATE_DISCONNECTED state immediately + * after this callback returns. + * - PJSIP_REDIRECT_PENDING: set to this value if + * no decision can be made immediately (for example + * to request confirmation from user). Application + * then MUST call #pjsua_call_process_redirect() + * to either accept or reject the redirection upon + * getting user decision. + * @param e The event that caused this callback to be called. + * This could be the receipt of 3xx response, or + * 4xx/5xx response received for the INVITE sent to + * subsequent targets, or NULL if this callback is + * called from within #pjsua_call_process_redirect() + * context. + */ + void (*on_call_redirected)(pjsua_call_id call_id, const pjsip_uri *target, + pjsip_redirect_op *cmd, const pjsip_event *e); + } pjsua_callback; @@ -3132,6 +3180,32 @@ PJ_DECL(pj_status_t) pjsua_call_hangup(pjsua_call_id call_id, const pj_str_t *reason, const pjsua_msg_data *msg_data); +/** + * Accept or reject redirection response. Application MUST call this function + * after it signaled PJSIP_REDIRECT_PENDING in the \a on_call_redirected() + * callback, to notify the call whether to accept or reject the redirection + * to the current target. Application can use the combination of + * PJSIP_REDIRECT_PENDING command in \a on_call_redirected() callback and + * this function to ask for user permission before redirecting the call. + * + * Note that if the application chooses to reject or stop redirection (by + * using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the + * call disconnection callback will be called before this function returns. + * And if the application rejects the target, the \a on_call_redirected() + * callback may also be called before this function returns if there is + * another target to try. + * + * @param call_id The call ID. + * @param cmd Redirection operation to be applied to the current + * target. The semantic of this argument is similar + * to the description in the \a on_call_redirected() + * callback, except that the PJSIP_REDIRECT_PENDING is + * not accepted here. + * + * @return PJ_SUCCESS on successful operation. + */ +PJ_DECL(pj_status_t) pjsua_call_process_redirect(pjsua_call_id call_id, + pjsip_redirect_op cmd); /** * Put the specified call on hold. This will send re-INVITE with the |