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

4 files changed, 361 insertions, 1 deletions

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   */
@@ -475,6 +523,53 @@ PJ_DECL(pj_status_t) pjsip_inv_terminate( pjsip_inv_session *inv,
 
 
 /**
+ * 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 
  * the invite session was created, then this function will put an SDP offer 
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 <pjsip/sip_auth.h>
 #include <pjsip/sip_errno.h>
 #include <pjsip/sip_transport.h>
+#include <pjsip/sip_util.h>
 #include <pj/sock.h>
 #include <pj/assert.h>
 
@@ -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
@@ -26,6 +26,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
  * @brief Utilities to create various messages and base function to send messages.
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