modules/uac: update README

modules/uac/README

@@ -23,46 +23,46 @@ Ramona-Elena Modroiu
 
    1. Admin Guide
 
-        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
+        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
 
    List of Examples
 
@@ -96,7 +96,50 @@ Ramona-Elena Modroiu
 
 Chapter 1. Admin Guide
 
-1.1. Overview
+   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
 
    The UAC (User Agent Client) module provides some basic UAC
    functionalities like sending SIP requests, registering with a remote
@@ -119,9 +162,12 @@ Chapter 1. Admin Guide
        request. Try to save needed changes in a pseudovariable and apply
        them once.
 
-1.2. Dependencies
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
 
-1.2.1. Kamailio Modules
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * TM - Transaction Module
@@ -131,15 +177,32 @@ Chapter 1. Admin Guide
        “auto” and you want uac_replace_from or uac_replace_to to store the
        values of the URIs as dialog variables.
 
-1.2.2. External Libraries or Applications
+2.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * None
 
-1.3. Parameters
-
-1.3.1. rr_from_store_param (string)
+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)
 
    Name of Record-Route header parameter that will be used to store an
    encoded version of the original FROM URI.
@@ -151,7 +214,7 @@ Chapter 1. Admin Guide
 modparam("uac","rr_from_store_param","my_param")
 ...
 
-1.3.2. rr_to_store_param (string)
+3.2. rr_to_store_param (string)
 
    Name of Record-Route header parameter that will be used to store
    (encoded) the original TO URI.
@@ -163,7 +226,7 @@ modparam("uac","rr_from_store_param","my_param")
 modparam("uac","rr_to_store_param","my_param")
 ...
 
-1.3.3. restore_mode (string)
+3.3. restore_mode (string)
 
    There are 3 modes of restoring the original FROM URI and the original
    TO URI:
@@ -183,7 +246,7 @@ modparam("uac","rr_to_store_param","my_param")
 modparam("uac","restore_mode","auto")
 ...
 
-1.3.4. restore_dlg (int)
+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
@@ -196,7 +259,7 @@ modparam("uac","restore_mode","auto")
 modparam("uac", "restore_dlg", 1)
 ...
 
-1.3.5. restore_passwd (string)
+3.5. restore_passwd (string)
 
    String password to be used to encrypt the RR storing parameters. If
    empty, no encryption will be used.
@@ -208,7 +271,7 @@ modparam("uac", "restore_dlg", 1)
 modparam("uac","restore_passwd","my_secret_passwd")
 ...
 
-1.3.6. restore_from_avp (string)
+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.
@@ -227,7 +290,7 @@ modparam("uac","restore_passwd","my_secret_passwd")
 modparam("uac","restore_from_avp","$avp(original_uri_from)")
 ...
 
-1.3.7. restore_to_avp (string)
+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
@@ -246,7 +309,7 @@ modparam("uac","restore_from_avp","$avp(original_uri_from)")
 modparam("uac","restore_to_avp","$avp(original_uri_to)")
 ...
 
-1.3.8. credential (string)
+3.8. credential (string)
 
    Contains a multiple definition of credentials used to perform
    authentication.
@@ -258,7 +321,7 @@ modparam("uac","restore_to_avp","$avp(original_uri_to)")
 modparam("uac","credential","username:domain:password")
 ...
 
-1.3.9. auth_realm_avp (string)
+3.9. auth_realm_avp (string)
 
    The definition of an PV that might contain the realm to be used to
    perform authentication.
@@ -269,43 +332,43 @@ modparam("uac","credential","username:domain:password")
    advance.
 
    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)”).
+   (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
 ...
 modparam("uac","auth_realm_avp","$avp(i:10)")
 ...
 
-1.3.10. auth_username_avp (string)
+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 1.3.9, “auth_realm_avp (string)”) and “auth_username_avp”
-   (Section 1.3.11, “auth_password_avp (string)”).
+   (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
 ...
 modparam("uac","auth_username_avp","$avp(i:11)")
 ...
 
-1.3.11. auth_password_avp (string)
+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 1.3.11, “auth_password_avp (string)”) and “auth_username_avp”
-   (Section 1.3.11, “auth_password_avp (string)”).
+   (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
 ...
 modparam("uac","auth_password_avp","$avp(i:12)")
 ...
 
-1.3.12. reg_db_url (string)
+3.12. reg_db_url (string)
 
    DB URL to fetch account profiles for registration.
 
@@ -315,7 +378,7 @@ modparam("uac", "reg_db_url",
     "mysql://kamailio:kamailiorw@localhost/kamailio")
 ...
 
-1.3.13. reg_timer_interval (string)
+3.13. reg_timer_interval (string)
 
    Timer interval (in seconds) at which registrations are managed, e.g.
    renewed as needed.
@@ -327,7 +390,7 @@ modparam("uac", "reg_db_url",
 modparam("uac", "reg_timer_interval", 60)
 ...
 
-1.3.14. reg_retry_interval (int)
+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
@@ -341,7 +404,7 @@ modparam("uac", "reg_timer_interval", 60)
 modparam("uac", "reg_retry_interval", 300)
 ...
 
-1.3.15. reg_db_table (string)
+3.15. reg_db_table (string)
 
    DB table name to fetch user profiles for registration.
 
@@ -352,7 +415,7 @@ modparam("uac", "reg_retry_interval", 300)
 modparam("uac", "reg_db_table", "uacreg")
 ...
 
-1.3.16. reg_contact_addr (string)
+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
@@ -364,9 +427,20 @@ modparam("uac", "reg_db_table", "uacreg")
 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
 ...
 
-1.4. Functions
+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)
 
-1.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.
 
@@ -409,7 +483,7 @@ uac_replace_from("","sip:[email protected]");
 uac_replace_from("","");
 ...
 
-1.4.2.  uac_replace_from(uri)
+4.2.  uac_replace_from(uri)
 
    Replace in FROM header the URI part without altering the display name.
 
@@ -422,7 +496,7 @@ uac_replace_from("","");
 uac_replace_from("sip:[email protected]");
 ...
 
-1.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
@@ -435,7 +509,7 @@ uac_replace_from("sip:[email protected]");
 uac_restore_from();
 ...
 
-1.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.
 
@@ -460,7 +534,7 @@ uac_replace_to("","sip:[email protected]");
 uac_replace_to("","");
 ...
 
-1.4.5.  uac_replace_to(uri)
+4.5.  uac_replace_to(uri)
 
    Replace in TO header the URI part without altering the display name.
 
@@ -491,7 +565,7 @@ uac_replace_to("","");
 uac_replace_to("sip:[email protected]");
 ...
 
-1.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
@@ -504,7 +578,7 @@ uac_replace_to("sip:[email protected]");
 uac_restore_to();
 ...
 
-1.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
@@ -517,7 +591,7 @@ uac_restore_to();
 uac_auth();
 ...
 
-1.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.
@@ -534,7 +608,7 @@ $uac_req(turi)="sip:kamailio.org";
 uac_req_send();
 ...
 
-1.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.
@@ -550,7 +624,7 @@ if(uac_reg_lookup("$rU", "$ru"))
 }
 ...
 
-1.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
@@ -583,14 +657,14 @@ failure_route[REMOTE_AUTH] {
 }
 ...
 
-1.5. Exported pseudo-variables
+5. Exported pseudo-variables
 
      * $uac_req(key)
 
    Exported pseudo-variables are documented at
    http://www.kamailio.org/wiki/.
 
-1.6. Remote Registration
+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