Closed #1696: IP change detection (Contact rewrite method) based on REGISTER final response

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@4586 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 76 insertions, 26 deletions

diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h
index 9e393813..80c7a331 100644
--- a/pjsip/include/pjsip-ua/sip_regc.h
+++ b/pjsip/include/pjsip-ua/sip_regc.h
@@ -84,6 +84,22 @@ struct pjsip_regc_cbparam
 typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param);
 
 /**
+ * Structure to hold parameters when calling application's callback
+ * specified in #pjsip_regc_set_reg_tsx_cb().
+ * To update contact address, application can set the field contact_cnt
+ * and contact inside the callback.
+ */
+struct pjsip_regc_tsx_cb_param
+{
+    struct pjsip_regc_cbparam   cbparam;
+    int                         contact_cnt;
+    pj_str_t                    contact[PJSIP_REGC_MAX_CONTACT];
+};
+
+/** Type declaration for callback set in #pjsip_regc_set_reg_tsx_cb(). */
+typedef void pjsip_regc_tsx_cb(struct pjsip_regc_tsx_cb_param *param);
+
+/**
  * Client registration information.
  */
 struct pjsip_regc_info
@@ -191,6 +207,21 @@ PJ_DECL(pj_status_t) pjsip_regc_init(pjsip_regc *regc,
 				     pj_uint32_t expires);
 
 /**
+ * Set callback to be called when the registration received a final response.
+ * This callback is different with the one specified during creation via
+ * #pjsip_regc_create(). This callback will be called for any final response
+ * (including 401/407/423) and before any subsequent requests are sent.
+ * In case of unregistration, this callback will not be called.
+ *
+ * @param regc	    The client registration structure.
+ * @param tsx_cb    Pointer to callback function to receive registration status.
+ *
+ * @return	    PJ_SUCCESS on success.
+ */
+PJ_DECL(pj_status_t) pjsip_regc_set_reg_tsx_cb(pjsip_regc *regc,
+				               pjsip_regc_tsx_cb *tsx_cb);
+
+/**
  * Set the "sent-by" field of the Via header for outgoing requests.
  *
  * @param regc	    The client registration structure.
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h
index ad261561..beb0762e 100644
--- a/pjsip/include/pjsua-lib/pjsua.h
+++ b/pjsip/include/pjsua-lib/pjsua.h
@@ -569,6 +569,39 @@ typedef enum pjsua_create_media_transport_flag
 
 
 /**
+ * This enumeration specifies the contact rewrite method.
+ */
+typedef enum pjsua_contact_rewrite_method
+{
+    /**
+      * The Contact update will be done by sending unregistration
+      * to the currently registered Contact, while simultaneously sending new
+      * registration (with different Call-ID) for the updated Contact.
+      */
+    PJSUA_CONTACT_REWRITE_UNREGISTER = 1,
+
+    /**
+      * The Contact update will be done in a single, current
+      * registration session, by removing the current binding (by setting its
+      * Contact's expires parameter to zero) and adding a new Contact binding,
+      * all done in a single request.
+      */
+    PJSUA_CONTACT_REWRITE_NO_UNREG = 2,
+
+    /**
+      * The Contact update will be done when receiving any registration final
+      * response. If this flag is not specified, contact update will only be
+      * done upon receiving 2xx response. This flag MUST be used with
+      * PJSUA_CONTACT_REWRITE_UNREGISTER or PJSUA_CONTACT_REWRITE_NO_UNREG
+      * above to specify how the Contact update should be performed when
+      * receiving 2xx response.
+      */
+    PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE = 4
+
+} pjsua_contact_rewrite_method;
+
+
+/**
  * Call settings.
  */
 typedef struct pjsua_call_setting
@@ -2540,25 +2573,18 @@ PJ_DECL(pj_status_t) pjsua_transport_close( pjsua_transport_id id,
 
 /**
  * This macro specifies the default value for \a contact_rewrite_method
- * field in pjsua_acc_config. I specifies  how Contact update will be
+ * field in pjsua_acc_config. It specifies how Contact update will be
  * done with the registration, if \a allow_contact_rewrite is enabled in
- *  the account config.
- *
- * If set to 1, the Contact update will be done by sending unregistration
- * to the currently registered Contact, while simultaneously sending new
- * registration (with different Call-ID) for the updated Contact.
+ * the account config. See \a pjsua_contact_rewrite_method for the options.
  *
- * If set to 2, the Contact update will be done in a single, current
- * registration session, by removing the current binding (by setting its
- * Contact's expires parameter to zero) and adding a new Contact binding,
- * all done in a single request.
+ * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
  *
- * Value 1 is the legacy behavior.
- *
- * Default value: 2
+ * Default value: PJSUA_CONTACT_REWRITE_NO_UNREG(2) |
+ *                PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE(4)
  */
 #ifndef PJSUA_CONTACT_REWRITE_METHOD
-#   define PJSUA_CONTACT_REWRITE_METHOD		2
+#   define PJSUA_CONTACT_REWRITE_METHOD	   (PJSUA_CONTACT_REWRITE_NO_UNREG | \
+                                           PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
 #endif
 
 
@@ -3010,20 +3036,13 @@ typedef struct pjsua_acc_config
 
     /**
      * Specify how Contact update will be done with the registration, if
-     * \a allow_contact_rewrite is enabled.
-     *
-     * If set to 1, the Contact update will be done by sending unregistration
-     * to the currently registered Contact, while simultaneously sending new
-     * registration (with different Call-ID) for the updated Contact.
-     *
-     * If set to 2, the Contact update will be done in a single, current
-     * registration session, by removing the current binding (by setting its
-     * Contact's expires parameter to zero) and adding a new Contact binding,
-     * all done in a single request.
+     * \a allow_contact_rewrite is enabled. The value is bitmask combination of
+     * \a pjsua_contact_rewrite_method. See also pjsua_contact_rewrite_method.
      *
-     * Value 1 is the legacy behavior.
+     * Value PJSUA_CONTACT_REWRITE_UNREGISTER(1) is the legacy behavior.
      *
-     * Default value: PJSUA_CONTACT_REWRITE_METHOD (2)
+     * Default value: PJSUA_CONTACT_REWRITE_METHOD
+     * (PJSUA_CONTACT_REWRITE_NO_UNREG | PJSUA_CONTACT_REWRITE_ALWAYS_UPDATE)
      */
     int		     contact_rewrite_method;