Ticket #930:

 - Updated semantic of contact param in functions pjsip_dlg_create_uac(), pjsip_dlg_create_uas(), pjsip_endpt_create_request() and also variable pjsua_acc.contact to be Contact header value (was Contact URI).
 - Updated docs related to above modifications.
 - Fixed pjsua_im_send() in generating contact header, it should use pjsua_acc.contact instead, if it is set.




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

5 files changed, 63 insertions, 21 deletions

diff --git a/pjsip/include/pjsip-ua/sip_regc.h b/pjsip/include/pjsip-ua/sip_regc.h
index 91adaa4f..eb8b33c0 100644
--- a/pjsip/include/pjsip-ua/sip_regc.h
+++ b/pjsip/include/pjsip-ua/sip_regc.h
@@ -166,7 +166,15 @@ PJ_DECL(pj_pool_t*) pjsip_regc_get_pool(pjsip_regc *regc);
  * @param to_url    The address of record for which the registration is targetd, must
  *		    be a SIP/SIPS URL.
  * @param ccnt	    Number of contacts in the array.
- * @param contact   Array of contacts.
+ * @param contact   Array of contacts, each contact item must be formatted
+ *		    as described in RFC 3261 Section 20.10:
+ *		    When the header field value contains a display 
+ *		    name, the URI including all URI parameters is 
+ *		    enclosed in "<" and ">".  If no "<" and ">" are 
+ *		    present, all parameters after the URI are header
+ *		    parameters, not URI parameters.  The display name 
+ *		    can be tokens, or a quoted string, if a larger 
+ *		    character set is desired.
  * @param expires   Default expiration interval (in seconds) to be applied for
  *		    contact URL that doesn't have expiration settings. If the
  *		    value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then 
@@ -303,8 +311,8 @@ PJ_DECL(pj_status_t) pjsip_regc_unregister_all(pjsip_regc *regc,
 
 /**
  * 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
+ * contact, if the contact is not found in existing contact, it will be
+ * added to the Contact list. If it 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.
@@ -317,7 +325,15 @@ PJ_DECL(pj_status_t) pjsip_regc_unregister_all(pjsip_regc *regc,
  *
  * @param regc	    The client registration structure.
  * @param ccnt	    Number of contacts.
- * @param contact   Array of contact URIs.
+ * @param contact   Array of contacts, each contact item must be formatted
+ *		    as described in RFC 3261 Section 20.10:
+ *		    When the header field value contains a display 
+ *		    name, the URI including all URI parameters is 
+ *		    enclosed in "<" and ">".  If no "<" and ">" are 
+ *		    present, all parameters after the URI are header
+ *		    parameters, not URI parameters.  The display name 
+ *		    can be tokens, or a quoted string, if a larger 
+ *		    character set is desired.
  * @return	    PJ_SUCCESS if sucessfull.
  */
 PJ_DECL(pj_status_t) pjsip_regc_update_contact( pjsip_regc *regc,
diff --git a/pjsip/include/pjsip/sip_dialog.h b/pjsip/include/pjsip/sip_dialog.h
index 03098df6..6b748b3a 100644
--- a/pjsip/include/pjsip/sip_dialog.h
+++ b/pjsip/include/pjsip/sip_dialog.h
@@ -183,9 +183,18 @@ PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m);
  *
  * @param ua		    The user agent module instance.
  * @param local_uri	    Dialog local URI (i.e. From header).
- * @param local_contact_uri Optional dialog local Contact URI. 
- *			    If this argument is NULL, the Contact will be
- *			    taken from the local URI.
+ * @param local_contact	    Optional dialog local Contact to be put as Contact
+ *			    header value, hence the format must follow
+ *			    RFC 3261 Section 20.10:
+ *			    When the header field value contains a display 
+ *			    name, the URI including all URI parameters is 
+ *			    enclosed in "<" and ">".  If no "<" and ">" are 
+ *			    present, all parameters after the URI are header
+ *			    parameters, not URI parameters.  The display name 
+ *			    can be tokens, or a quoted string, if a larger 
+ *			    character set is desired.
+ *			    If this argument is NULL, the Contact will be taken
+ *			    from the local URI.
  * @param remote_uri	    Dialog remote URI (i.e. To header).
  * @param target	    Optional initial remote target. If this argument
  *			    is NULL, the initial target will be set to
@@ -196,7 +205,7 @@ PJ_DECL(pj_bool_t) pjsip_method_creates_dialog(const pjsip_method *m);
  */
 PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua,
 					   const pj_str_t *local_uri,
-					   const pj_str_t *local_contact_uri,
+					   const pj_str_t *local_contact,
 					   const pj_str_t *remote_uri,
 					   const pj_str_t *target,
 					   pjsip_dialog **p_dlg);
@@ -220,8 +229,17 @@ PJ_DECL(pj_status_t) pjsip_dlg_create_uac( pjsip_user_agent *ua,
  * @param ua		    The user agent module instance.
  * @param rdata		    The incoming request that creates the dialog,
  *			    such as INVITE, SUBSCRIBE, or REFER.
- * @param contact	    Optional URI to be used as local Contact. If
- *			    this argument is NULL, the local contact will be
+ * @param contact	    Optional dialog local Contact to be put as Contact
+ *			    header value, hence the format must follow
+ *			    RFC 3261 Section 20.10:
+ *			    When the header field value contains a display 
+ *			    name, the URI including all URI parameters is 
+ *			    enclosed in "<" and ">".  If no "<" and ">" are 
+ *			    present, all parameters after the URI are header
+ *			    parameters, not URI parameters.  The display name 
+ *			    can be tokens, or a quoted string, if a larger 
+ *			    character set is desired.
+ *			    If this argument is NULL, the local contact will be
  *			    initialized from the value of To header in the
  *			    request.
  * @param p_dlg		    Pointer to receive the dialog.
diff --git a/pjsip/include/pjsip/sip_util.h b/pjsip/include/pjsip/sip_util.h
index b7b0078d..57a4821c 100644
--- a/pjsip/include/pjsip/sip_util.h
+++ b/pjsip/include/pjsip/sip_util.h
@@ -243,7 +243,15 @@ PJ_DECL(pj_status_t) pjsip_target_assign_status(pjsip_target *target,
  * @param target    Target URI.
  * @param from	    URL to put in From header.
  * @param to	    URL to put in To header.
- * @param contact   URL to put in Contact header.
+ * @param contact   Contact to be put as Contact header value, hence
+ *		    the format must follow RFC 3261 Section 20.10:
+ *		    When the header field value contains a display 
+ *		    name, the URI including all URI parameters is 
+ *		    enclosed in "<" and ">".  If no "<" and ">" are 
+ *		    present, all parameters after the URI are header
+ *		    parameters, not URI parameters.  The display name 
+ *		    can be tokens, or a quoted string, if a larger 
+ *		    character set is desired.
  * @param call_id   Optional Call-ID (put NULL to generate unique Call-ID).
  * @param cseq	    Optional CSeq (put -1 to generate random CSeq).
  * @param text	    Optional text body (put NULL to omit body).
@@ -280,9 +288,9 @@ PJ_DECL(pj_status_t) pjsip_endpt_create_request( pjsip_endpoint *endpt,
  * @param endpt	    Endpoint instance.
  * @param method    SIP Method.
  * @param target    Target URI.
- * @param from	    URL to put in From header.
- * @param to	    URL to put in To header.
- * @param contact   URL to put in Contact header.
+ * @param from	    From header.
+ * @param to	    To header.
+ * @param contact   Contact header.
  * @param call_id   Optional Call-ID (put NULL to generate unique Call-ID).
  * @param cseq	    Optional CSeq (put -1 to generate random CSeq).
  * @param text	    Optional text body (put NULL to omit body).
diff --git a/pjsip/include/pjsua-lib/pjsua.h b/pjsip/include/pjsua-lib/pjsua.h
index 023acb6b..e06019d9 100644
--- a/pjsip/include/pjsua-lib/pjsua.h
+++ b/pjsip/include/pjsua-lib/pjsua.h
@@ -2163,11 +2163,11 @@ PJ_DECL(pj_status_t) pjsua_acc_create_request(pjsua_acc_id acc_id,
 
 
 /**
- * Create a suitable URI to be put as Contact based on the specified
- * target URI for the specified account.
+ * Create a suitable Contact header value, based on the specified target URI 
+ * for the specified account.
  *
  * @param pool		Pool to allocate memory for the string.
- * @param contact	The string where the Contact URI will be stored.
+ * @param contact	The string where the Contact will be stored.
  * @param acc_id	Account ID.
  * @param uri		Destination URI of the request.
  *
@@ -2181,11 +2181,11 @@ PJ_DECL(pj_status_t) pjsua_acc_create_uac_contact( pj_pool_t *pool,
 
 
 /**
- * Create a suitable URI to be put as Contact based on the information
- * in the incoming request.
+ * Create a suitable Contact header value, based on the information in the 
+ * incoming request.
  *
  * @param pool		Pool to allocate memory for the string.
- * @param contact	The string where the Contact URI will be stored.
+ * @param contact	The string where the Contact will be stored.
  * @param acc_id	Account ID.
  * @param rdata		Incoming request.
  *
diff --git a/pjsip/include/pjsua-lib/pjsua_internal.h b/pjsip/include/pjsua-lib/pjsua_internal.h
index a144c97d..d80f5d1d 100644
--- a/pjsip/include/pjsua-lib/pjsua_internal.h
+++ b/pjsip/include/pjsua-lib/pjsua_internal.h
@@ -118,7 +118,7 @@ typedef struct pjsua_acc
     int		     index;	    /**< Index in accounts array.	*/
     pj_str_t	     display;	    /**< Display name, if any.		*/
     pj_str_t	     user_part;	    /**< User part of local URI.	*/
-    pj_str_t	     contact;	    /**< Our Contact URI for REGISTER	*/
+    pj_str_t	     contact;	    /**< Our Contact header.		*/
 
     pj_str_t	     srv_domain;    /**< Host part of reg server.	*/
     int		     srv_port;	    /**< Port number of reg server.	*/