Ticket #534: Client register/registration support for various registrar brokenness

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

2 files changed, 68 insertions, 9 deletions

diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h
index 03c71d9b..71a553e3 100644
--- a/pjsip/include/pjsip-ua/sip_regc.h
+++ b/pjsip/include/pjsip-ua/sip_regc.h
@@ -62,8 +62,14 @@ typedef struct pjsip_regc pjsip_regc;
 struct pjsip_regc_cbparam
 {
     pjsip_regc		*regc;	    /**< Client registration structure.	    */
-    void		*token;	    /**< Arbitrary token.		    */
-    pj_status_t		 status;    /**< Error status.			    */
+    void		*token;	    /**< Arbitrary token set by application */
+
+    /** Error status. If this value is non-PJ_SUCCESS, some error has occured.
+     *  Note that even when this contains PJ_SUCCESS the registration might
+     *  have failed; in this case the \a code field will contain non
+     *  successful (non-2xx status class) code
+     */
+    pj_status_t		 status;
     int			 code;	    /**< SIP status code received.	    */
     pj_str_t		 reason;    /**< SIP reason phrase received.	    */
     pjsip_rx_data	*rdata;	    /**< The complete received response.    */
@@ -295,19 +301,31 @@ PJ_DECL(pj_status_t) pjsip_regc_unregister_all(pjsip_regc *regc,
 					       pjsip_tx_data **p_tdata);
 
 /**
- * Update Contact details in the client registration structure.
+ * Update Contact details in the client registration structure. For each
+ * contact URI, if the uri is not found in existing contact, it will be
+ * added to the Contact list. If the URI matches existing contact, nothing
+ * will be added. This function will also mark existing contacts which
+ * are not specified in the new contact list as to be removed, by adding
+ * "expires=0" parameter to these contacts.
+ *
+ * Once the contact list has been updated, application must update the
+ * registration by creating a new REGISTER request and send it to the
+ * registrar. This request will contain both old and new contacts; the
+ * old contacts will have it's expires parameter set to zero to instruct
+ * the registrar to remove the bindings.
  *
  * @param regc	    The client registration structure.
  * @param ccnt	    Number of contacts.
- * @param contact   Array of contacts.
- * @return	    zero if sucessfull.
+ * @param contact   Array of contact URIs.
+ * @return	    PJ_SUCCESS if sucessfull.
  */
 PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc,
 					        int ccnt,
 						const pj_str_t contact[] );
 
 /**
- * Update the expires value.
+ * Update the expires value. The next REGISTER request will contain
+ * new expires value for the registration.
  *
  * @param regc	    The client registration structure.
  * @param expires   The new expires value.
diff --git a/pjsip/include/pjsip/sip_config.h b/pjsip/include/pjsip/sip_config.h
index ded28ebd..a63e2250 100644
--- a/pjsip/include/pjsip/sip_config.h
+++ b/pjsip/include/pjsip/sip_config.h
@@ -108,7 +108,7 @@ typedef struct pjsip_cfg_t
     struct {
 	/**
 	 * Specify whether client registration should check for its 
-	 * registered contact in Contact header of successful REGISTE 
+	 * registered contact in Contact header of successful REGISTER 
 	 * response to determine whether registration has been successful. 
 	 * This setting may be disabled if non-compliant registrar is unable
 	 * to return correct Contact header.
@@ -117,6 +117,17 @@ typedef struct pjsip_cfg_t
 	 */
 	pj_bool_t   check_contact;
 
+	/**
+	 * Specify whether client registration should add "x-uid" extension
+	 * parameter in all Contact URIs that it registers to assist the
+	 * matching of Contact URIs in the 200/OK REGISTER response, in 
+	 * case the registrar is unable to return exact Contact URI in the
+	 * 200/OK response.
+	 *
+	 * Default is PJSIP_REGISTER_CLIENT_ADD_XUID_PARAM.
+	 */
+	pj_bool_t   add_xuid_param;
+
     } regc;
 
 } pjsip_cfg_t;
@@ -713,7 +724,17 @@ PJ_INLINE(pjsip_cfg_t*) pjsip_cfg(void)
 #   define PJSIP_HAS_DIGEST_AKA_AUTH	    0
 #endif
 
-PJ_END_DECL
+
+/**
+ * Specify the number of seconds to refresh the client registration
+ * before the registration expires.
+ *
+ * Default: 5 seconds
+ */
+#ifndef PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH
+#   define PJSIP_REGISTER_CLIENT_DELAY_BEFORE_REFRESH  5
+#endif
+
 
 /**
  * Specify whether client registration should check for its registered
@@ -721,7 +742,8 @@ PJ_END_DECL
  * whether registration has been successful. This setting may be disabled
  * if non-compliant registrar is unable to return correct Contact header.
  *
- * This setting can be changed in run-time with using pjsip_cfg().
+ * This setting can be changed in run-time by settting \a regc.check_contact
+ * field of pjsip_cfg().
  *
  * Default is 1
  */
@@ -731,6 +753,25 @@ PJ_END_DECL
 
 
 /**
+ * Specify whether client registration should add "x-uid" extension
+ * parameter in all Contact URIs that it registers to assist the
+ * matching of Contact URIs in the 200/OK REGISTER response, in 
+ * case the registrar is unable to return exact Contact URI in the
+ * 200/OK response.
+ *
+ * This setting can be changed in run-time by setting 
+ * \a regc.add_xuid_param field of pjsip_cfg().
+ *
+ * Default is 0.
+ */
+#ifndef PJSIP_REGISTER_CLIENT_ADD_XUID_PARAM
+#   define PJSIP_REGISTER_CLIENT_ADD_XUID_PARAM	0
+#endif
+
+
+PJ_END_DECL
+
+/**
  * @}
  */