modules:uac updated README after avoiding quotes in display.

modules/uac/README

@@ -14,55 +14,55 @@ Ramona-Elena Modroiu
 
    <[email protected]>
 
-   Copyright © 2009-2010 asipto.com
+   Copyright © 2009-2010 asipto.com
 
-   Copyright © 2005 Voice Sistem
+   Copyright © 2005 Voice Sistem
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1. Overview
-        2. Dependencies
-
-              2.1. Kamailio Modules
-              2.2. External Libraries or Applications
-
-        3. Parameters
-
-              3.1. rr_from_store_param (string)
-              3.2. rr_to_store_param (string)
-              3.3. restore_mode (string)
-              3.4. restore_dlg (int)
-              3.5. restore_passwd (string)
-              3.6. restore_from_avp (string)
-              3.7. restore_to_avp (string)
-              3.8. credential (string)
-              3.9. auth_realm_avp (string)
-              3.10. auth_username_avp (string)
-              3.11. auth_password_avp (string)
-              3.12. reg_db_url (string)
-              3.13. reg_timer_interval (string)
-              3.14. reg_retry_interval (int)
-              3.15. reg_db_table (string)
-              3.16. reg_contact_addr (string)
-
-        4. Functions
-
-              4.1. uac_replace_from(display,uri)
-              4.2. uac_replace_from(uri)
-              4.3. uac_restore_from()
-              4.4. uac_replace_to(display,uri)
-              4.5. uac_replace_to(uri)
-              4.6. uac_restore_to()
-              4.7. uac_auth()
-              4.8. uac_req_send()
-              4.9. uac_reg_lookup(uuid, dst)
-              4.10. uac_reg_request_to(user, mode)
-
-        5. Exported pseudo-variables
-        6. Remote Registration
+        1.1. Overview
+        1.2. Dependencies
+
+              1.2.1. Kamailio Modules
+              1.2.2. External Libraries or Applications
+
+        1.3. Parameters
+
+              1.3.1. rr_from_store_param (string)
+              1.3.2. rr_to_store_param (string)
+              1.3.3. restore_mode (string)
+              1.3.4. restore_dlg (int)
+              1.3.5. restore_passwd (string)
+              1.3.6. restore_from_avp (string)
+              1.3.7. restore_to_avp (string)
+              1.3.8. credential (string)
+              1.3.9. auth_realm_avp (string)
+              1.3.10. auth_username_avp (string)
+              1.3.11. auth_password_avp (string)
+              1.3.12. reg_db_url (string)
+              1.3.13. reg_timer_interval (string)
+              1.3.14. reg_retry_interval (int)
+              1.3.15. reg_db_table (string)
+              1.3.16. reg_contact_addr (string)
+
+        1.4. Functions
+
+              1.4.1. uac_replace_from(display,uri)
+              1.4.2. uac_replace_from(uri)
+              1.4.3. uac_restore_from()
+              1.4.4. uac_replace_to(display,uri)
+              1.4.5. uac_replace_to(uri)
+              1.4.6. uac_restore_to()
+              1.4.7. uac_auth()
+              1.4.8. uac_req_send()
+              1.4.9. uac_reg_lookup(uuid, dst)
+              1.4.10. uac_reg_request_to(user, mode)
+
+        1.5. Exported pseudo-variables
+        1.6. Remote Registration
 
    List of Examples
 
@@ -96,50 +96,7 @@ Ramona-Elena Modroiu
 
 Chapter 1. Admin Guide
 
-   Table of Contents
-
-   1. Overview
-   2. Dependencies
-
-        2.1. Kamailio Modules
-        2.2. External Libraries or Applications
-
-   3. Parameters
-
-        3.1. rr_from_store_param (string)
-        3.2. rr_to_store_param (string)
-        3.3. restore_mode (string)
-        3.4. restore_dlg (int)
-        3.5. restore_passwd (string)
-        3.6. restore_from_avp (string)
-        3.7. restore_to_avp (string)
-        3.8. credential (string)
-        3.9. auth_realm_avp (string)
-        3.10. auth_username_avp (string)
-        3.11. auth_password_avp (string)
-        3.12. reg_db_url (string)
-        3.13. reg_timer_interval (string)
-        3.14. reg_retry_interval (int)
-        3.15. reg_db_table (string)
-        3.16. reg_contact_addr (string)
-
-   4. Functions
-
-        4.1. uac_replace_from(display,uri)
-        4.2. uac_replace_from(uri)
-        4.3. uac_restore_from()
-        4.4. uac_replace_to(display,uri)
-        4.5. uac_replace_to(uri)
-        4.6. uac_restore_to()
-        4.7. uac_auth()
-        4.8. uac_req_send()
-        4.9. uac_reg_lookup(uuid, dst)
-        4.10. uac_reg_request_to(user, mode)
-
-   5. Exported pseudo-variables
-   6. Remote Registration
-
-1. Overview
+1.1. Overview
 
    The UAC (User Agent Client) module provides some basic UAC
    functionalities like sending SIP requests, registering with a remote
@@ -158,95 +115,75 @@ 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.
 
-2. Dependencies
+1.2. Dependencies
 
-   2.1. Kamailio Modules
-   2.2. External Libraries or Applications
-
-2.1. Kamailio Modules
+1.2.1. Kamailio Modules
 
    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
+1.2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * None
 
-3. Parameters
-
-   3.1. rr_from_store_param (string)
-   3.2. rr_to_store_param (string)
-   3.3. restore_mode (string)
-   3.4. restore_dlg (int)
-   3.5. restore_passwd (string)
-   3.6. restore_from_avp (string)
-   3.7. restore_to_avp (string)
-   3.8. credential (string)
-   3.9. auth_realm_avp (string)
-   3.10. auth_username_avp (string)
-   3.11. auth_password_avp (string)
-   3.12. reg_db_url (string)
-   3.13. reg_timer_interval (string)
-   3.14. reg_retry_interval (int)
-   3.15. reg_db_table (string)
-   3.16. reg_contact_addr (string)
-
-3.1. rr_from_store_param (string)
+1.3. Parameters
+
+1.3.1. rr_from_store_param (string)
 
    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
 ...
 modparam("uac","rr_from_store_param","my_param")
 ...
 
-3.2. rr_to_store_param (string)
+1.3.2. rr_to_store_param (string)
 
    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
 ...
 modparam("uac","rr_to_store_param","my_param")
 ...
 
-3.3. restore_mode (string)
+1.3.3. restore_mode (string)
 
    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
 ...
 modparam("uac","restore_mode","auto")
 ...
 
-3.4. restore_dlg (int)
+1.3.4. restore_dlg (int)
 
    If set to 1, the module uses dialog variables to store initial and new
    values for From/To headers. The Dialog module has to be loaded and all
@@ -259,7 +196,7 @@ modparam("uac","restore_mode","auto")
 modparam("uac", "restore_dlg", 1)
 ...
 
-3.5. restore_passwd (string)
+1.3.5. restore_passwd (string)
 
    String password to be used to encrypt the RR storing parameters. If
    empty, no encryption will be used.
@@ -271,7 +208,7 @@ modparam("uac", "restore_dlg", 1)
 modparam("uac","restore_passwd","my_secret_passwd")
 ...
 
-3.6. restore_from_avp (string)
+1.3.6. restore_from_avp (string)
 
    If defined and restore_mode is manual or auto, the avp is used to save
    the original from uri in order to be able to restore it in replies.
@@ -290,7 +227,7 @@ modparam("uac","restore_passwd","my_secret_passwd")
 modparam("uac","restore_from_avp","$avp(original_uri_from)")
 ...
 
-3.7. restore_to_avp (string)
+1.3.7. restore_to_avp (string)
 
    If defined and restore_mode is manual or auto, the avp is used to save
    the original To URI in order to be able to restore it in replies. That
@@ -309,7 +246,7 @@ modparam("uac","restore_from_avp","$avp(original_uri_from)")
 modparam("uac","restore_to_avp","$avp(original_uri_to)")
 ...
 
-3.8. credential (string)
+1.3.8. credential (string)
 
    Contains a multiple definition of credentials used to perform
    authentication.
@@ -321,7 +258,7 @@ modparam("uac","restore_to_avp","$avp(original_uri_to)")
 modparam("uac","credential","username:domain:password")
 ...
 
-3.9. auth_realm_avp (string)
+1.3.9. auth_realm_avp (string)
 
    The definition of an PV that might contain the realm to be used to
    perform authentication.
@@ -331,44 +268,44 @@ 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 1.3.10, “auth_username_avp (string)�) and “auth_username_avp�
+   (Section 1.3.11, “auth_password_avp (string)�).
 
    Example 1.9. Set auth_realm_avp parameter
 ...
 modparam("uac","auth_realm_avp","$avp(i:10)")
 ...
 
-3.10. auth_username_avp (string)
+1.3.10. auth_username_avp (string)
 
    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 1.3.9, “auth_realm_avp (string)�) and “auth_username_avp�
+   (Section 1.3.11, “auth_password_avp (string)�).
 
    Example 1.10. Set auth_username_avp parameter
 ...
 modparam("uac","auth_username_avp","$avp(i:11)")
 ...
 
-3.11. auth_password_avp (string)
+1.3.11. auth_password_avp (string)
 
    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 1.3.11, “auth_password_avp (string)�) and “auth_username_avp�
+   (Section 1.3.11, “auth_password_avp (string)�).
 
    Example 1.11. Set auth_password_avp parameter
 ...
 modparam("uac","auth_password_avp","$avp(i:12)")
 ...
 
-3.12. reg_db_url (string)
+1.3.12. reg_db_url (string)
 
    DB URL to fetch account profiles for registration.
 
@@ -378,7 +315,7 @@ modparam("uac", "reg_db_url",
     "mysql://kamailio:kamailiorw@localhost/kamailio")
 ...
 
-3.13. reg_timer_interval (string)
+1.3.13. reg_timer_interval (string)
 
    Timer interval (in seconds) at which registrations are managed, e.g.
    renewed as needed.
@@ -390,7 +327,7 @@ modparam("uac", "reg_db_url",
 modparam("uac", "reg_timer_interval", 60)
 ...
 
-3.14. reg_retry_interval (int)
+1.3.14. reg_retry_interval (int)
 
    Failed registration attempts will be retried after this interval (in
    seconds). The interval is not exact, retries may be attempted as much
@@ -404,18 +341,18 @@ modparam("uac", "reg_timer_interval", 60)
 modparam("uac", "reg_retry_interval", 300)
 ...
 
-3.15. reg_db_table (string)
+1.3.15. reg_db_table (string)
 
    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
 ...
 modparam("uac", "reg_db_table", "uacreg")
 ...
 
-3.16. reg_contact_addr (string)
+1.3.16. reg_contact_addr (string)
 
    Address to be used to build contact address. Must be at least host
    part, can have port and parameters. Must not include 'sip:'. The
@@ -427,20 +364,9 @@ modparam("uac", "reg_db_table", "uacreg")
 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
 ...
 
-4. Functions
+1.4. Functions
 
-   4.1. uac_replace_from(display,uri)
-   4.2. uac_replace_from(uri)
-   4.3. uac_restore_from()
-   4.4. uac_replace_to(display,uri)
-   4.5. uac_replace_to(uri)
-   4.6. uac_restore_to()
-   4.7. uac_auth()
-   4.8. uac_req_send()
-   4.9. uac_reg_lookup(uuid, dst)
-   4.10. uac_reg_request_to(user, mode)
-
-4.1. uac_replace_from(display,uri)
+1.4.1.  uac_replace_from(display,uri)
 
    Replace in FROM header the display name and the URI part.
 
@@ -448,6 +374,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 +401,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:[email protected]");
 # remove display and do not touch uri
 uac_replace_from("","");
 ...
 
-4.2. uac_replace_from(uri)
+1.4.2.  uac_replace_from(uri)
 
    Replace in FROM header the URI part without altering the display name.
 
@@ -491,7 +422,7 @@ uac_replace_from("","");
 uac_replace_from("sip:[email protected]");
 ...
 
-4.3. uac_restore_from()
+1.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 +435,7 @@ uac_replace_from("sip:[email protected]");
 uac_restore_from();
 ...
 
-4.4. uac_replace_to(display,uri)
+1.4.4.  uac_replace_to(display,uri)
 
    Replace in TO header the display name and the URI part.
 
@@ -512,19 +443,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:[email protected]");
 # remove display and do not touch uri
 uac_replace_to("","");
 ...
 
-4.5. uac_replace_to(uri)
+1.4.5.  uac_replace_to(uri)
 
    Replace in TO header the URI part without altering the display name.
 
@@ -555,7 +491,7 @@ uac_replace_to("","");
 uac_replace_to("sip:[email protected]");
 ...
 
-4.6. uac_restore_to()
+1.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 +504,7 @@ uac_replace_to("sip:[email protected]");
 uac_restore_to();
 ...
 
-4.7. uac_auth()
+1.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 +517,7 @@ uac_restore_to();
 uac_auth();
 ...
 
-4.8. uac_req_send()
+1.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 +534,7 @@ $uac_req(turi)="sip:kamailio.org";
 uac_req_send();
 ...
 
-4.9. uac_reg_lookup(uuid, dst)
+1.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 +550,7 @@ if(uac_reg_lookup("$rU", "$ru"))
 }
 ...
 
-4.10. uac_reg_request_to(user, mode)
+1.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
@@ -647,14 +583,14 @@ failure_route[REMOTE_AUTH] {
 }
 ...
 
-5. Exported pseudo-variables
+1.5. Exported pseudo-variables
 
      * $uac_req(key)
 
    Exported pseudo-variables are documented at
    http://www.kamailio.org/wiki/.
 
-6. Remote Registration
+1.6. Remote Registration
 
    The module can register contact addresses to remote REGISTRAR servers.
    You have to add records to uacreg table. The table stores following