[sr-dev] git:4.0: modules/uac: update README after avoiding adding quotes in uac_replace_* functions

[Vicente Hernando]

Module: sip-router
Branch: 4.0
Commit: 9a75da1e9a302868729b171ad76dcf15404487e5
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=9a75da1e9a302868729b171ad76dcf15404487e5

Author: Vicente Hernando <vhernando at systemonenoc.com>
Committer: Vicente Hernando <vhernando at systemonenoc.com>
Date:   Fri May 17 12:34:54 2013 +0200

modules/uac: update README after avoiding adding quotes in uac_replace_* functions

---

 modules/uac/README |   78 +++++++++++++++++++++++++++++----------------------
 1 files changed, 44 insertions(+), 34 deletions(-)

diff --git a/modules/uac/README b/modules/uac/README
index d1f4e37..cd5cf5c 100644
--- a/modules/uac/README
+++ b/modules/uac/README
@@ -14,9 +14,9 @@ Ramona-Elena Modroiu
 
    <ramona at rosdev.ro>
 
-   Copyright © 2009-2010 asipto.com
+   Copyright © 2009-2010 asipto.com
 
-   Copyright © 2005 Voice Sistem
+   Copyright © 2005 Voice Sistem
      __________________________________________________________________
 
    Table of Contents
@@ -158,7 +158,7 @@ Chapter 1. Admin Guide
      * Authentication does not support qop auth-int, just qop auth;
      * CSeq is not increased during authentication - the response may be
        rejected.
-     * The "uac_replace_*" functions can only be run once on the same SIP
+     * The “uac_replace_*” functions can only be run once on the same SIP
        request. Try to save needed changes in a pseudovariable and apply
        them once.
 
@@ -172,9 +172,9 @@ Chapter 1. Admin Guide
    The following modules must be loaded before this module:
      * TM - Transaction Module
      * RR - Record-Route Module, but only if restore mode for From: URI is
-       set to "auto".
+       set to “auto”.
      * Dialog Module, but only if restore mode for From: URI is set to
-       "auto" and you want uac_replace_from or uac_replace_to to store the
+       “auto” and you want uac_replace_from or uac_replace_to to store the
        values of the URIs as dialog variables.
 
 2.2. External Libraries or Applications
@@ -207,7 +207,7 @@ Chapter 1. Admin Guide
    Name of Record-Route header parameter that will be used to store an
    encoded version of the original FROM URI.
 
-   This parameter is optional, it's default value being "vsf".
+   This parameter is optional, it's default value being “vsf”.
 
    Example 1.1. Set rr_from_store_param parameter
 ...
@@ -219,7 +219,7 @@ modparam("uac","rr_from_store_param","my_param")
    Name of Record-Route header parameter that will be used to store
    (encoded) the original TO URI.
 
-   This parameter is optional, it's default value being "vst".
+   This parameter is optional, it's default value being “vst”.
 
    Example 1.2. Set rr_to_store_param parameter
 ...
@@ -230,16 +230,16 @@ modparam("uac","rr_to_store_param","my_param")
 
    There are 3 modes of restoring the original FROM URI and the original
    TO URI:
-     * "none" - no information about original URI is stored; restoration
+     * “none” - no information about original URI is stored; restoration
        is not possible.
-     * "manual" - all following replies will be restored, but not also the
+     * “manual” - all following replies will be restored, but not also the
        sequential requests - this must be manually updated based on
        original URI.
-     * "auto" - all sequential requests and replies will be automatically
+     * “auto” - all sequential requests and replies will be automatically
        updated based on stored original URI. For this option you have to
-       set "modparam("rr", "append_fromtag", 1)".
+       set “modparam("rr", "append_fromtag", 1)”.
 
-   This parameter is optional, it's default value being "auto".
+   This parameter is optional, it's default value being “auto”.
 
    Example 1.3. Set restore_mode parameter
 ...
@@ -331,9 +331,9 @@ modparam("uac","credential","username:domain:password")
    This can be used if the realm upstream will be using is not known in
    advance.
 
-   If you define it, you also need to define "auth_username_avp"
-   (Section 3.10, "auth_username_avp (string)") and "auth_username_avp"
-   (Section 3.11, "auth_password_avp (string)").
+   If you define it, you also need to define “auth_username_avp”
+   (Section 3.10, “auth_username_avp (string)”) and “auth_username_avp”
+   (Section 3.11, “auth_password_avp (string)”).
 
    Example 1.9. Set auth_realm_avp parameter
 ...
@@ -345,9 +345,9 @@ modparam("uac","auth_realm_avp","$avp(i:10)")
    The definition of an AVP that might contain the username to be used to
    perform authentication.
 
-   If you define it, you also need to define "auth_realm_avp"
-   (Section 3.9, "auth_realm_avp (string)") and "auth_username_avp"
-   (Section 3.11, "auth_password_avp (string)").
+   If you define it, you also need to define “auth_realm_avp”
+   (Section 3.9, “auth_realm_avp (string)”) and “auth_username_avp”
+   (Section 3.11, “auth_password_avp (string)”).
 
    Example 1.10. Set auth_username_avp parameter
 ...
@@ -359,9 +359,9 @@ modparam("uac","auth_username_avp","$avp(i:11)")
    The definition of an AVP that might contain the password to be used to
    perform authentication.
 
-   If you define it, you also need to define "auth_password_avp"
-   (Section 3.11, "auth_password_avp (string)") and "auth_username_avp"
-   (Section 3.11, "auth_password_avp (string)").
+   If you define it, you also need to define “auth_password_avp”
+   (Section 3.11, “auth_password_avp (string)”) and “auth_username_avp”
+   (Section 3.11, “auth_password_avp (string)”).
 
    Example 1.11. Set auth_password_avp parameter
 ...
@@ -408,7 +408,7 @@ modparam("uac", "reg_retry_interval", 300)
 
    DB table name to fetch user profiles for registration.
 
-   This parameter is optional, it's default value being "uacreg".
+   This parameter is optional, it's default value being “uacreg”.
 
    Example 1.15. Set reg_db_table parameter
 ...
@@ -440,7 +440,7 @@ modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
    4.9. uac_reg_lookup(uuid, dst)
    4.10. uac_reg_request_to(user, mode)
 
-4.1. uac_replace_from(display,uri)
+4.1.  uac_replace_from(display,uri)
 
    Replace in FROM header the display name and the URI part.
 
@@ -448,6 +448,10 @@ modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
 
    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
 
+   NOTE: Previous versions of this function added double quotes
+   automatically to display variable. That is no longer the case, if you
+   expect that behavior, you will have to add the quotes by yourself.
+
    If you set restore_mode to AUTO, the URI will be modified automatically
    in all subsequent requests and replies in that dialog.
 
@@ -471,14 +475,15 @@ modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
 # replace both display and uri
 uac_replace_from("$avp(s:display)","$avp(s:uri)");
 # replace only display and do not touch uri
-uac_replace_from("batman","");
+uac_replace_from("batman","");   # display is replaced with: batman
+uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
 # remove display and replace uri
 uac_replace_from("","sip:robin at gotham.org");
 # remove display and do not touch uri
 uac_replace_from("","");
 ...
 
-4.2. uac_replace_from(uri)
+4.2.  uac_replace_from(uri)
 
    Replace in FROM header the URI part without altering the display name.
 
@@ -491,7 +496,7 @@ uac_replace_from("","");
 uac_replace_from("sip:batman at gotham.org");
 ...
 
-4.3. uac_restore_from()
+4.3.  uac_restore_from()
 
    This function will check if the FROM URI was modified and will use the
    information stored in header parameter to restore the original FROM URI
@@ -504,7 +509,7 @@ uac_replace_from("sip:batman at gotham.org");
 uac_restore_from();
 ...
 
-4.4. uac_replace_to(display,uri)
+4.4.  uac_replace_to(display,uri)
 
    Replace in TO header the display name and the URI part.
 
@@ -512,19 +517,24 @@ uac_restore_from();
 
    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
 
+   NOTE: Previous versions of this function added double quotes
+   automatically to display variable. That is no longer the case, if you
+   expect that behavior, you will have to add the quotes by yourself.
+
    Example 1.20. uac_replace_to usage
 ...
 # replace both display and uri
 uac_replace_to("$avp(display)","$avp(uri)");
 # replace only display and do not touch uri
-uac_replace_to("batman","");
+uac_replace_to("batman","");   # display is replaced with: batman
+uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
 # remove display and replace uri
 uac_replace_to("","sip:robin at gotham.org");
 # remove display and do not touch uri
 uac_replace_to("","");
 ...
 
-4.5. uac_replace_to(uri)
+4.5.  uac_replace_to(uri)
 
    Replace in TO header the URI part without altering the display name.
 
@@ -555,7 +565,7 @@ uac_replace_to("","");
 uac_replace_to("sip:batman at gotham.org");
 ...
 
-4.6. uac_restore_to()
+4.6.  uac_restore_to()
 
    This function will check if the TO URI was modified and will use the
    information stored in header parameter to restore the original TO URI
@@ -568,7 +578,7 @@ uac_replace_to("sip:batman at gotham.org");
 uac_restore_to();
 ...
 
-4.7. uac_auth()
+4.7.  uac_auth()
 
    This function can be called only from failure route and will build the
    authentication response header and insert it into the request without
@@ -581,7 +591,7 @@ uac_restore_to();
 uac_auth();
 ...
 
-4.8. uac_req_send()
+4.8.  uac_req_send()
 
    This function sends a SIP message from the configuration file. The
    message is built out of $uac_req(...) pseudo-variable.
@@ -598,7 +608,7 @@ $uac_req(turi)="sip:kamailio.org";
 uac_req_send();
 ...
 
-4.9. uac_reg_lookup(uuid, dst)
+4.9.  uac_reg_lookup(uuid, dst)
 
    This function sets the PV dst to SIP URI that correspond to uuid in uac
    registations table. uuid and dst must be pseudo-variables.
@@ -614,7 +624,7 @@ if(uac_reg_lookup("$rU", "$ru"))
 }
 ...
 
-4.10. uac_reg_request_to(user, mode)
+4.10.  uac_reg_request_to(user, mode)
 
    This function can be used to send an authenticated request to a remote
    user in the uac registrations table. It sets the request-uri, dst-uri