uac: readme regenerated

modules/uac/README

@@ -14,9 +14,9 @@ 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
@@ -191,9 +191,12 @@ Chapter 1. Admin Guide
 
    Known limitations in this version:
      * 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
+     * CSeq is not increased automatically by uac_auth() during
+       authentication - the follow up request may be rejected. CSeq can be
+       increased when authenticating INVITE requests - dialog module has
+       to be used, with CSeq tracking feature enabled (see the readme of
+       dialog module).
+     * 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.
 
@@ -207,9 +210,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
@@ -242,7 +245,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
 ...
@@ -254,7 +257,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
 ...
@@ -265,16 +268,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
 ...
@@ -366,9 +369,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
 ...
@@ -380,9 +383,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
 ...
@@ -394,9 +397,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
 ...
@@ -443,7 +446,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
 ...
@@ -475,7 +478,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.
 
@@ -518,7 +521,7 @@ uac_replace_from("","sip:[email protected]");
 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.
 
@@ -531,7 +534,7 @@ uac_replace_from("","");
 uac_replace_from("sip:[email protected]");
 ...
 
-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
@@ -544,7 +547,7 @@ uac_replace_from("sip:[email protected]");
 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.
 
@@ -569,7 +572,7 @@ uac_replace_to("","sip:[email protected]");
 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.
 
@@ -600,7 +603,7 @@ uac_replace_to("","");
 uac_replace_to("sip:[email protected]");
 ...
 
-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
@@ -613,7 +616,7 @@ uac_replace_to("sip:[email protected]");
 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
@@ -623,10 +626,34 @@ uac_restore_to();
 
    Example 1.23. uac_auth usage
 ...
-uac_auth();
+modparam("uac","auth_username_avp","$avp(auser)")
+modparam("uac","auth_password_avp","$avp(apass)")
+modparam("uac","auth_realm_avp","$avp(arealm)")
+
+request_route {
+   ...
+   if(is_method("INVITE")) {
+      t_on_failure("TRUNKAUTH");
+   }
+   ...
+}
+
+failure_route[TRUNKAUTH] {
+
+    if (t_is_canceled()) {
+        exit;
+    }
+    if(t_check_status("401|407")) {
+        $avp(auser) = "test";
+        $avp(apass) = "test";
+        uac_auth();
+        t_relay();
+        exit;
+    }
+}
 ...
 
-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.
@@ -644,7 +671,7 @@ $uac_req(callid)=$(mb{s.md5});
 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.
@@ -660,7 +687,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
@@ -704,7 +731,7 @@ failure_route[REMOTE_AUTH] {
 
    6.1. event_route[uac:reply]
 
-6.1.  event_route[uac:reply]
+6.1. event_route[uac:reply]
 
    Event route executed for the final reply to the request set with
    uac_req_send(). The associated $uac_req(evroute) has to be set to 1.
@@ -741,7 +768,7 @@ event_route[uac:reply] {
    8.5. uac.reg_reload
    8.6. uac.reg_refresh
 
-8.1.  uac.reg_dump
+8.1. uac.reg_dump
 
    Dump the content of remote registration table from memory.
 
@@ -750,7 +777,7 @@ event_route[uac:reply] {
    kamcmd uac.reg_dump
 ...
 
-8.2.  uac.reg_info
+8.2. uac.reg_info
 
    Return the details of a remote registration record based on a filter.
    The command has two parameter: attribute and value. The attribute can
@@ -763,7 +790,7 @@ event_route[uac:reply] {
    kamcmd uac.reg_info l_uuid account123
 ...
 
-8.3.  uac.reg_enable
+8.3. uac.reg_enable
 
    Enable a remote registration record based on a filter. The command has
    two parameter: attribute and value. The attribute can be: l_uuid,
@@ -776,7 +803,7 @@ event_route[uac:reply] {
    kamcmd uac.reg_enable l_uuid account123
 ...
 
-8.4.  uac.reg_disable
+8.4. uac.reg_disable
 
    Disable a remote registration record based on a filter. The command has
    two parameter: attribute and value. The attribute can be: l_uuid,
@@ -789,7 +816,7 @@ event_route[uac:reply] {
    kamcmd uac.reg_disable l_uuid account123
 ...
 
-8.5.  uac.reg_reload
+8.5. uac.reg_reload
 
    Reload the records from database for remote registrations.
 
@@ -798,7 +825,7 @@ event_route[uac:reply] {
    kamcmd uac.reg_reload
 ...
 
-8.6.  uac.reg_refresh
+8.6. uac.reg_refresh
 
    Load one record by l_uuid from database for remote registrations. If
    the record exists in memory, its authentication password is updated,