From c40accaad90c1ec16cf734e478d13247812c0e0c Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Thu, 27 Nov 2008 00:06:46 +0000 Subject: Ticket #10: handle redirection response in the invite session git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@2370 74dad513-b988-da41-8d7b-12977e46ad98 --- pjsip/include/pjsip-ua/sip_inv.h | 97 +++++++++++++++++++- pjsip/include/pjsip/sip_dialog.h | 2 + pjsip/include/pjsip/sip_util.h | 189 +++++++++++++++++++++++++++++++++++++++ pjsip/include/pjsua-lib/pjsua.h | 74 +++++++++++++++ 4 files changed, 361 insertions(+), 1 deletion(-) (limited to 'pjsip/include') diff --git a/pjsip/include/pjsip-ua/sip_inv.h b/pjsip/include/pjsip-ua/sip_inv.h index ba9858a8..0d878573 100644 --- a/pjsip/include/pjsip-ua/sip_inv.h +++ b/pjsip/include/pjsip-ua/sip_inv.h @@ -115,7 +115,6 @@ typedef struct pjsip_inv_callback */ void (*on_state_changed)(pjsip_inv_session *inv, pjsip_event *e); - /** * This callback is called when the invite usage module has created * a new dialog and invite because of forked outgoing request. @@ -214,6 +213,54 @@ typedef struct pjsip_inv_callback */ void (*on_send_ack)(pjsip_inv_session *inv, pjsip_rx_data *rdata); + /** + * This callback is called when the session 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 inv The invite session. + * @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 + * session will immediately resend INVITE request + * to the target. + * - PJSIP_REDIRECT_REJECT: immediately reject this + * target. The session 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_state_changed() 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 #pjsip_inv_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 #pjsip_inv_process_redirect() + * context. + */ + void (*on_redirected)(pjsip_inv_session *inv, const pjsip_uri *target, + pjsip_redirect_op *cmd, const pjsip_event *e); + } pjsip_inv_callback; @@ -276,6 +323,7 @@ struct pjsip_inv_session unsigned options; /**< Options in use. */ pjmedia_sdp_neg *neg; /**< Negotiator. */ pjsip_transaction *invite_tsx; /**< 1st invite tsx. */ + pjsip_tx_data *invite_req; /**< Saved invite req */ pjsip_tx_data *last_answer; /**< Last INVITE resp. */ pjsip_tx_data *last_ack; /**< Last ACK request */ pj_int32_t last_ack_cseq; /**< CSeq of last ACK */ @@ -474,6 +522,53 @@ PJ_DECL(pj_status_t) pjsip_inv_terminate( pjsip_inv_session *inv, pj_bool_t notify ); +/** + * Restart UAC session and prepare the session for a new initial INVITE. + * This function can be called for example when the application wants to + * follow redirection response with a new call reusing this session so + * that the new call will have the same Call-ID and From headers. After + * the session is restarted, application may create and send a new INVITE + * request. + * + * @param inv The invite session. + * @param new_offer Should be set to PJ_TRUE since the application will + * restart the session. + * + * @return PJ_SUCCESS on successful operation. + */ +PJ_DECL(pj_status_t) pjsip_inv_uac_restart(pjsip_inv_session *inv, + pj_bool_t new_offer); + + +/** + * Accept or reject redirection response. Application MUST call this function + * after it signaled PJSIP_REDIRECT_PENDING in the \a on_redirected() + * callback, to notify the invite session whether to accept or reject the + * redirection to the current target. Application can use the combination of + * PJSIP_REDIRECT_PENDING command in \a on_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 + * session disconnection callback will be called before this function returns. + * And if the application rejects the target, the \a on_redirected() callback + * may also be called before this function returns if there is another target + * to try. + * + * @param inv The invite session. + * @param cmd Redirection operation. The semantic of this argument + * is similar to the description in the \a on_redirected() + * callback, except that the PJSIP_REDIRECT_PENDING is + * not accepted here. + * @param e Should be set to NULL. + * + * @return PJ_SUCCESS on successful operation. + */ +PJ_DECL(pj_status_t) pjsip_inv_process_redirect(pjsip_inv_session *inv, + pjsip_redirect_op cmd, + pjsip_event *e); + + /** * Create the initial INVITE request for this session. This function can only * be called for UAC session. If local media capability is specified when diff --git a/pjsip/include/pjsip/sip_dialog.h b/pjsip/include/pjsip/sip_dialog.h index 182c7a2e..e41f7b51 100644 --- a/pjsip/include/pjsip/sip_dialog.h +++ b/pjsip/include/pjsip/sip_dialog.h @@ -29,6 +29,7 @@ #include #include #include +#include #include #include @@ -121,6 +122,7 @@ struct pjsip_dialog /* Dialog's session properties. */ pjsip_dialog_state state; /**< Dialog state. */ pjsip_uri *target; /**< Current target. */ + pjsip_target_set target_set; /**< Target set, for UAC only. */ pjsip_hdr inv_hdr; /**< Headers from hparam in dest URL */ pjsip_dlg_party local; /**< Local party info. */ pjsip_dlg_party remote; /**< Remote party info. */ diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h index 4a5a4716..1314e361 100644 --- a/pjsip/include/pjsip/sip_util.h +++ b/pjsip/include/pjsip/sip_util.h @@ -25,6 +25,195 @@ PJ_BEGIN_DECL +/** + * @defgroup PJSIP_ENDPT_TARGET_URI Target URI Management + * @ingroup PJSIP_CORE_CORE + * @brief Management of target URI's in case of redirection + * @{ + * This module provides utility functions to manage target set for UAC. + * The target set is provided as pjsip_target_set structure. Initially, + * the target set for UAC contains only one target, that is the target of + * the initial request. When 3xx/redirection class response is received, + * the UAC can use the functionality of this module to add the URI's listed + * in the Contact header(s) in the response to the target set, and retry + * sending the request to the next destination/target. The UAC may retry + * this sequentially until one of the target answers with succesful/2xx + * response, or one target returns global error/6xx response, or all targets + * are exhausted. + * + * This module is currently used by the \ref PJSIP_INV. + */ + +/** + * This structure describes a target, which can be chained together to form + * a target set. Each target contains an URI, priority (as q-value), and + * the last status code and reason phrase received from the target, if the + * target has been contacted. If the target has not been contacted, the + * status code field will be zero. + */ +typedef struct pjsip_target +{ + PJ_DECL_LIST_MEMBER(struct pjsip_target);/**< Standard list element */ + pjsip_uri *uri; /**< The target URI */ + int q1000; /**< q-value multiplied by 1000 */ + pjsip_status_code code; /**< Last status code received */ + pj_str_t reason; /**< Last reason phrase received */ +} pjsip_target; + + +/** + * This describes a target set. A target set contains a linked-list of + * pjsip_target. + */ +typedef struct pjsip_target_set +{ + pjsip_target head; /**< Target linked-list head */ + pjsip_target *current; /**< Current target. */ +} pjsip_target_set; + + +/** + * These enumerations specify the action to be performed to a redirect + * response. + */ +typedef enum pjsip_redirect_op +{ + /** + * Reject the redirection to the current target. The UAC will + * select the next target from the target set if exists. + */ + PJSIP_REDIRECT_REJECT, + + /** + * Accept the redirection to the current target. The INVITE request + * will be resent to the current target. + */ + PJSIP_REDIRECT_ACCEPT, + + /** + * Defer the redirection decision, for example to request permission + * from the end user. + */ + PJSIP_REDIRECT_PENDING, + + /** + * Stop the whole redirection process altogether. This will cause + * the invite session to be disconnected. + */ + PJSIP_REDIRECT_STOP + +} pjsip_redirect_op; + + +/** + * Initialize target set. This will empty the list of targets in the + * target set. + * + * @param tset The target set. + */ +PJ_INLINE(void) pjsip_target_set_init(pjsip_target_set *tset) +{ + pj_list_init(&tset->head); + tset->current = NULL; +} + + +/** + * Add an URI to the target set, if the URI is not already in the target set. + * The URI comparison rule of pjsip_uri_cmp() will be used to determine the + * equality of this URI compared to existing URI's in the target set. The + * URI will be cloned using the specified memory pool before it is added to + * the list. + * + * The first URI added to the target set will also be made current target + * by this function. + * + * @param tset The target set. + * @param pool The memory pool to be used to duplicate the URI. + * @param uri The URI to be checked and added. + * @param q1000 The q-value multiplied by 1000. + * + * @return PJ_SUCCESS if the URI was added to the target set, + * or PJ_EEXISTS if the URI already exists in the target + * set, or other error codes. + */ +PJ_DECL(pj_status_t) pjsip_target_set_add_uri(pjsip_target_set *tset, + pj_pool_t *pool, + const pjsip_uri *uri, + int q1000); + +/** + * Extract URI's in the Contact headers of the specified (response) message + * and add them to the target set. This function will also check if the + * URI's already exist in the target set before adding them to the list. + * + * @param tset The target set. + * @param pool The memory pool to be used to duplicate the URI's. + * @param msg SIP message from which the Contact headers will be + * scanned and the URI's to be extracted, checked, and + * added to the target set. + * + * @return PJ_SUCCESS if at least one URI was added to the + * target set, or PJ_EEXISTS if all URI's in the message + * already exists in the target set or if the message + * doesn't contain usable Contact headers, or other error + * codes. + */ +PJ_DECL(pj_status_t) pjsip_target_set_add_from_msg(pjsip_target_set *tset, + pj_pool_t *pool, + const pjsip_msg *msg); + +/** + * Get the next target to be retried. This function will scan the target set + * for target which hasn't been tried, and return one target with the + * highest q-value, if such target exists. This function will return NULL + * if there is one target with 2xx or 6xx code or if all targets have been + * tried. + * + * @param tset The target set. + * + * @return The next target to be tried, or NULL if all targets have + * been tried or at least one target returns 2xx or 6xx + * response. + */ +PJ_DECL(pjsip_target*) +pjsip_target_set_get_next(const pjsip_target_set *tset); + + +/** + * Set the specified target as the current target in the target set. The + * current target may be used by application to keep track on which target + * is currently being operated on. + * + * @param tset The target set. + * @param target The target to be set as current target. + * + * @return PJ_SUCCESS or the appropriate error code. + */ +PJ_DECL(pj_status_t) pjsip_target_set_set_current(pjsip_target_set *tset, + pjsip_target *target); + + +/** + * Set the status code and reason phrase of the specified target. + * + * @param target The target. + * @param pool The memory pool to be used to duplicate the reason phrase. + * @param code The SIP status code to be set to the target. + * @param reason The reason phrase to be set to the target. + * + * @return PJ_SUCCESS on successful operation or the appropriate + * error code. + */ +PJ_DECL(pj_status_t) pjsip_target_assign_status(pjsip_target *target, + pj_pool_t *pool, + int status_code, + const pj_str_t *reason); + +/** + * @} + */ + /** * @defgroup PJSIP_ENDPT_STATELESS Message Creation and Stateless Operations * @ingroup PJSIP_CORE_CORE 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 -- cgit v1.2.3