- Documentation updates

- Doxygen for lcr

README-MODULES

@@ -41,7 +41,7 @@ auth_identity
 auth_radius		Radius authentication
 avpops			Attribute-value pair operations ("variables")
 carrierroute		A telephony routing module
-cfg_db
+cfg_db			Database driver for configuration API
 cfg_rpc
 ctl
 db_berkeley		Database :: Berkeley DB (Oracle)

doc/management_api.txt

@@ -0,0 +1,45 @@
+Management API's in SIP-router
+------------------------------
+
+SIP-router has an API based on RPC. This allows modules and core to expose commands that can be 
+issued by external applications. Commands can change states, read status variables or expose
+internal structures.
+
+There are multiple ways to integrate your application to this interface. By adding modules,
+you can adapt the interface to one of several protocols supported:
+
+- XML-rpc
+- binrpc over various transports
+- Kamailio's MI - the management interface
+
+The MI interfaces can often run over Unix fifo sockets, UDP or TCP connections.
+
+The "sercmd" application is the command line tool used to connect to SIP-router
+over the command line. Use it to discover available commands.
+
+For backwards compatibilty, the kamctrl and kamdbctrl commands are still supported.
+
+Detailed information about these interfaces are to be found on the main sip-router.org
+web site in the wiki section.
+
+Modules
+-------
+
+mi_rpc		Exports Kamailio's MI interface over SIP-router's RPC interface
+xmlrpc		Exports the RPC interface using XML-rpc
+ctl		Implements the binrpc transport interface for SER rpcs
+		Also implements the old SER fifo-based management interface.
+
+Kamailio modules (modules_k)
+----------------------------
+mi_datagram	Kamailio MI interface- UDP version
+mi_fifo		Kamailio MI interface- FIFO version
+mi_xmlrpc	Kamailio MI interface- XML-rpc version
+
+
+The Kamailio MI interface is considered deprecated and will be supported
+only for backwards compatibility. New development is encouraged to use the
+RPC interface through one of the modules used to connect to it.
+
+The modules that currently only has MI interfaces will be changed to support
+the RPC interface in a coming release.

modules/avpops/README

@@ -12,49 +12,48 @@ Ramona-Elena Modroiu
 
    Copyright © 2004, 2005 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
-                              (Mi, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
-
-              1.2.1. Kamailio Modules
-              1.2.2. External Libraries or Applications
-
-        1.3. AVP naming format
-        1.4. Exported Parameters
-
-              1.4.1. db_url (string)
-              1.4.2. avp_table (string)
-              1.4.3. use_domain (integer)
-              1.4.4. uuid_column (string)
-              1.4.5. username_column (string)
-              1.4.6. domain_column (string)
-              1.4.7. attribute_column (string)
-              1.4.8. value_column (string)
-              1.4.9. type_column (string)
-              1.4.10. db_scheme (string)
-
-        1.5. Exported Functions
-
-              1.5.1. avp_db_load(source,name)
-              1.5.2. avp_db_store(source,name)
-              1.5.3. avp_db_delete(source,name)
-              1.5.4. avp_db_query(query[,dest])
-              1.5.5. avp_delete(name)
-              1.5.6. avp_pushto(destination,name)
-              1.5.7. avp_check(name,op_value)
-              1.5.8. avp_copy(old_name,new_name)
-              1.5.9. avp_printf(dest, format)
-              1.5.10. avp_subst(avps, subst)
-              1.5.11. avp_op(name,op_value)
-              1.5.12. is_avp_set(name)
-              1.5.13. avp_print()
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. AVP naming format
+        4. Exported Parameters
+
+              4.1. db_url (string)
+              4.2. avp_table (string)
+              4.3. use_domain (integer)
+              4.4. uuid_column (string)
+              4.5. username_column (string)
+              4.6. domain_column (string)
+              4.7. attribute_column (string)
+              4.8. value_column (string)
+              4.9. type_column (string)
+              4.10. db_scheme (string)
+
+        5. Exported Functions
+
+              5.1. avp_db_load(source,name)
+              5.2. avp_db_store(source,name)
+              5.3. avp_db_delete(source,name)
+              5.4. avp_db_query(query[,dest])
+              5.5. avp_delete(name)
+              5.6. avp_pushto(destination,name)
+              5.7. avp_check(name,op_value)
+              5.8. avp_copy(old_name,new_name)
+              5.9. avp_printf(dest, format)
+              5.10. avp_subst(avps, subst)
+              5.11. avp_op(name,op_value)
+              5.12. is_avp_set(name)
+              5.13. avp_print()
 
    List of Examples
 
@@ -85,79 +84,130 @@ Ramona-Elena Modroiu
 
 Chapter 1. Admin Guide
 
-1.1. Overview
-
-   AVPops (AVP-operations) modules implements a set of script
-   functions which allow access and manipulation of user AVPs
-   (preferences) and pseudo-variables. AVPs are a powerful tool
-   for implementing services/preferences per user/domain. Now they
-   are usable directly from configuration script. Functions for
-   interfacing DB resources (loading/storing/removing), functions
-   for swapping information between AVPs and SIP messages,
-   function for testing/checking the value of an AVP.
+   Table of Contents
 
-   AVPs are persistent per SIP transaction, being available in
-   "route", "branch_route" and "failure_route". To make them
-   available in "onreply_route" armed via TM module, set
-   "onreply_avp_mode" parameter of TM module (note that in the
-   default "onreply_route", the AVPs of the transaction are not
-   available).
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. AVP naming format
+   4. Exported Parameters
+
+        4.1. db_url (string)
+        4.2. avp_table (string)
+        4.3. use_domain (integer)
+        4.4. uuid_column (string)
+        4.5. username_column (string)
+        4.6. domain_column (string)
+        4.7. attribute_column (string)
+        4.8. value_column (string)
+        4.9. type_column (string)
+        4.10. db_scheme (string)
+
+   5. Exported Functions
+
+        5.1. avp_db_load(source,name)
+        5.2. avp_db_store(source,name)
+        5.3. avp_db_delete(source,name)
+        5.4. avp_db_query(query[,dest])
+        5.5. avp_delete(name)
+        5.6. avp_pushto(destination,name)
+        5.7. avp_check(name,op_value)
+        5.8. avp_copy(old_name,new_name)
+        5.9. avp_printf(dest, format)
+        5.10. avp_subst(avps, subst)
+        5.11. avp_op(name,op_value)
+        5.12. is_avp_set(name)
+        5.13. avp_print()
+
+1. Overview
+
+   The AVPops (AVP-operations) module implements a set of script functions
+   which allow access and manipulation of user attribute-value pairs
+   (AVPs, preferences) and pseudo-variables. AVPs are a powerful tool for
+   implementing services/preferences per user/domain. With this module,
+   they are usable directly from configuration script.
+
+   The module implement functions for interfacing DB resources
+   (loading/storing/removing), functions for swapping information between
+   AVPs and SIP messages and a function for testing/checking the value of
+   an AVP.
+
+   AVPs are persistent per SIP transaction, being available in "route",
+   "branch_route" and "failure_route". To make them available in
+   "onreply_route" armed via TM module, set "onreply_avp_mode" parameter
+   of TM module (note that in the default "onreply_route", the AVPs of the
+   transaction are not available).
 
    An up-to-date tutorial providing more information (detailed
-   explanations and commented examples) can be found on Voice
-   Sistem documentation web page at
-   http://voice-system.ro/docs/avpops .
+   explanations and commented examples) can be found on the SIP-router web
+   site.
+
+2. Dependencies
 
-1.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:
      * Optionally a database module
 
-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:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * None
 
-1.3. AVP naming format
+3. AVP naming format
 
-   The format of the parameters specifying an AVP in functions
-   exported by this module is: $avp(avp_flags:avp_name) or
-   $avp(avp_alias).
-     * avp_flags = type_flags [script_flags]; type_flags = 'I' |
-       'i' | 'S' | 's'; script_flags = 0..255
-       'I' or 'i' means that the type of avp name is integer (ID)
+   The format of the parameters specifying an AVP in functions exported by
+   this module is: $avp(avp_flags:avp_name) or $avp(avp_alias).
+     * avp_flags = type_flags [script_flags]; type_flags = 'I' | 'i' | 'S'
+       | 's'; script_flags = 0..255
+       'I' or 'i' means that the type of avp name is an integer (ID)
        'S' or 's' means that the type of avp name is string
-       The type flag is mandatory.
-       script_flags must be an 8 bit unsigned number, therefore
-       can be set up to 8 flags. If no script flag is provided,
-       the name will match all AVPs, regardless they have or not a
-       script flag set (preserves the compatibility with the old
-       naming schema).
+       The type flag is mandatory. Please note that the type flag only
+       indicates type of name, not type of variable. An avp with name type
+       "i" may very well contain text strings.
+       script_flags must be an 8 bit unsigned number, therefore can be set
+       up to 8 flags. If no script flag is provided, the name will match
+       all AVPs, regardless they have or not a script flag set (preserves
+       the compatibility with the old naming schema).
      * avp_name = string | integer
-       string - might be any alphanumeric string, wich contain
-       following characters: [a-z] [A-Z] [0-9] '_'
-       integer - might be an unsigned integer, greater than zero,
-       up to 2^16-1
+       string - might be any alphanumeric string, wich contain following
+       characters: [a-z] [A-Z] [0-9] '_'
+       integer - might be an unsigned integer, greater than zero, up to
+       2^16-1
      * avp_alias = string
-       string - might be any alphanumeric string, wich contain
-       following characters: [a-z] [A-Z] [0-9] '_'
+       string - might be any alphanumeric string, wich contain following
+       characters: [a-z] [A-Z] [0-9] '_'
 
    Example 1.1. AVP naming examples
 ...
 $avp(i:11) - the AVP identified by integer 11
 $avp(s:foo) - the AVP identified by the string 'foo'
 $avp(bar) - the AVP identified by the AVP alias 'bar'
-$avp(i3:123) - the AVP identified by the integer 123 which has script fl
-ags 1
+$avp(i3:123) - the AVP identified by the integer 123 which has script flags 1
     and 2 set
 ...
 
-1.4. Exported Parameters
+4. Exported Parameters
 
-1.4.1. db_url (string)
+   4.1. db_url (string)
+   4.2. avp_table (string)
+   4.3. use_domain (integer)
+   4.4. uuid_column (string)
+   4.5. username_column (string)
+   4.6. domain_column (string)
+   4.7. attribute_column (string)
+   4.8. value_column (string)
+   4.9. type_column (string)
+   4.10. db_scheme (string)
+
+4.1. db_url (string)
 
    DB URL for database connection.
 
@@ -168,22 +218,22 @@ ags 1
 modparam("avpops","db_url","mysql://user:passwd@host/database")
 ...
 
-1.4.2. avp_table (string)
+4.2. avp_table (string)
 
    DB table to be used.
 
-   This parameter is optional, it's default value being NULL. But
-   if you specify a db_url, you need also setup this parameter.
+   This parameter is optional, it's default value being NULL. But if you
+   specify a db_url, you need also setup this parameter.
 
    Example 1.3. Set avp_table parameter
 ...
 modparam("avpops","avp_table","avptable")
 ...
 
-1.4.3. use_domain (integer)
+4.3. use_domain (integer)
 
-   If the domain part of the an URI should be used for identifying
-   an AVP in DB operations.
+   If the domain part of the URI should be used for identifying an AVP in
+   DB operations.
 
    Default value is 0 (no).
 
@@ -192,7 +242,7 @@ modparam("avpops","avp_table","avptable")
 modparam("avpops","use_domain",1)
 ...
 
-1.4.4. uuid_column (string)
+4.4. uuid_column (string)
 
    Name of column containing the uuid (unique user id).
 
@@ -203,7 +253,7 @@ modparam("avpops","use_domain",1)
 modparam("avpops","uuid_column","uuid")
 ...
 
-1.4.5. username_column (string)
+4.5. username_column (string)
 
    Name of column containing the username.
 
@@ -214,7 +264,7 @@ modparam("avpops","uuid_column","uuid")
 modparam("avpops","username_column","username")
 ...
 
-1.4.6. domain_column (string)
+4.6. domain_column (string)
 
    Name of column containing the domain name.
 
@@ -225,7 +275,7 @@ modparam("avpops","username_column","username")
 modparam("avpops","domain_column","domain")
 ...
 
-1.4.7. attribute_column (string)
+4.7. attribute_column (string)
 
    Name of column containing the attribute name (AVP name).
 
@@ -236,7 +286,7 @@ modparam("avpops","domain_column","domain")
 modparam("avpops","attribute_column","attribute")
 ...
 
-1.4.8. value_column (string)
+4.8. value_column (string)
 
    Name of column containing the AVP value.
 
@@ -247,7 +297,7 @@ modparam("avpops","attribute_column","attribute")
 modparam("avpops","value_column","value")
 ...
 
-1.4.9. type_column (string)
+4.9. type_column (string)
 
    Name of integer column containing the AVP type.
 
@@ -264,7 +314,7 @@ modparam("avpops","value_column","value")
 modparam("avpops","type_column","type")
 ...
 
-1.4.10. db_scheme (string)
+4.10. db_scheme (string)
 
    Definition of a DB scheme to be used for non-standard access to
    Database information.
@@ -287,36 +337,48 @@ modparam("avpops","db_scheme",
 "scheme1:table=subscriber;uuid_col=uuid;value_col=first_name")
 ...
 
-1.5. Exported Functions
+5. Exported Functions
+
+   5.1. avp_db_load(source,name)
+   5.2. avp_db_store(source,name)
+   5.3. avp_db_delete(source,name)
+   5.4. avp_db_query(query[,dest])
+   5.5. avp_delete(name)
+   5.6. avp_pushto(destination,name)
+   5.7. avp_check(name,op_value)
+   5.8. avp_copy(old_name,new_name)
+   5.9. avp_printf(dest, format)
+   5.10. avp_subst(avps, subst)
+   5.11. avp_op(name,op_value)
+   5.12. is_avp_set(name)
+   5.13. avp_print()
 
-1.5.1.  avp_db_load(source,name)
+5.1. avp_db_load(source,name)
 
-   Loads from DB into memory the AVPs corresponding to the given
-   source. If given, it sets the script flags for loaded AVPs. It
-   returns true if it loaded some values in AVPs, false otherwise
-   (db error, no avp loaded ...).
+   Loads from DB into memory the AVPs corresponding to the given source.
+   If given, it sets the script flags for loaded AVPs. It returns true if
+   it loaded some values in AVPs, false otherwise (db error, no avp loaded
+   ...).
 
    Meaning of the parameters is as follows:
-     * source - what info is used for identifying the AVPs.
-       Parameter syntax:
+     * source - what info is used for identifying the AVPs. Parameter
+       syntax:
           + source = (pvar|str_value)
             ['/'('username'|'domain'|'uri'|'uuid')])
-          + pvar = any pseudo variable defined in Kamailio. If the
-            pvar is $ru (request uri), $fu (from uri), $tu (to
-            uri) or $ou (original uri), then the implicit flag is
-            'uri'. Otherwise, the implicit flag is 'uuid'.
-     * name - which AVPs will be loaded from DB into memory.
-       Parameter syntax is:
+          + pvar = any pseudo variable defined in Kamailio. If the pvar is
+            $ru (request uri), $fu (from uri), $tu (to uri) or $ou
+            (original uri), then the implicit flag is 'uri'. Otherwise,
+            the implicit flag is 'uuid'.
+     * name - which AVPs will be loaded from DB into memory. Parameter
+       syntax is:
           + name = avp_spec['/'(table_name|'$'db_scheme)]
-          + avp_spec =
-            matching_flags|$avp(avp_name)|$avp(avp_alias)
+          + avp_spec = matching_flags|$avp(avp_name)|$avp(avp_alias)
           + matching_flags = 'a' | 'A' | 'i' | 'I' | 's' | 'S'
             [script_flags]
-            'a' or 'A' means matching any of AVP name types ('i'
-            and 's') (NOTE: matching_flags cannot be used with
-            $db_scheme because the name of AVP to save in cannot
-            be specified), the rest have the meaning descriped in
-            'AVP naming format' chapter.
+            'a' or 'A' means matching any of AVP name types ('i' and 's')
+            (NOTE: matching_flags cannot be used with $db_scheme because
+            the name of AVP to save in cannot be specified), the rest have
+            the meaning descriped in 'AVP naming format' chapter.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
@@ -329,13 +391,12 @@ avp_db_load("$uuid","$avp(s:404fwd)/fwd_table");
 avp_db_load("$ru","$avp(i1:123)/$some_scheme");
 ...
 
-1.5.2.  avp_db_store(source,name)
+5.2. avp_db_store(source,name)
 
    Stores to DB the AVPs corresponding to the given source.
 
    The meaning and usage of the parameters are identical as for
-   avp_db_load(source,name) function. Please refer to its
-   description.
+   avp_db_load(source,name) function. Please refer to its description.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
@@ -346,13 +407,12 @@ avp_db_store("$tu","$avp(i:678)");
 avp_db_store("$ru/username","$avp(email)");
 ...
 
-1.5.3.  avp_db_delete(source,name)
+5.3. avp_db_delete(source,name)
 
    Deletes from DB the AVPs corresponding to the given source.
 
    The meaning and usage of the parameters are identical as for
-   avp_db_load(source,name) function. Please refer to its
-   description.
+   avp_db_load(source,name) function. Please refer to its description.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
@@ -364,34 +424,31 @@ avp_db_delete("$ru/username","$avp(email)");
 avp_db_delete("$uuid","$avp(s:404fwd)/fwd_table");
 ...
 
-1.5.4.  avp_db_query(query[,dest])
+5.4. avp_db_query(query[,dest])
 
    Make a database query and store the result in AVPs.
 
    The meaning and usage of the parameters:
-     * query - must be a valid SQL query. The parameter can
-       contain pseudo-variables.
-       You must escape any pseudo-variables manually to prevent
-       SQL injection attacks. You can use the existing
-       transformations escape.common and unescape.common to escape
-       and unescape the content of any pseudo-variable. Failing to
-       escape the variables used in the query makes you vulnerable
-       to SQL injection, e.g. make it possible for an outside
-       attacker to alter your database content.
-     * dest - a list with AVP names where to store the result. The
-       format is "$avp(name1);$avp(name2);...". If this parameter
-       is ommited, the result is stored in
-       "$avp(i:1);$avp(i:2);...". If the result gives many rows,
-       then multiple AVPs with corresponding name will be added.
-       The value type of the AVP (string or integer) will be
-       derived from the type of the columns. Please note that only
-       this two datatypes are supported, so its not possible for
-       example to return floating point or big integer values this
-       way.
+     * query - must be a valid SQL query. The parameter can contain
+       pseudo-variables.
+       You must escape any pseudo-variables manually to prevent SQL
+       injection attacks. You can use the existing transformations
+       escape.common and unescape.common to escape and unescape the
+       content of any pseudo-variable. Failing to escape the variables
+       used in the query makes you vulnerable to SQL injection, e.g. make
+       it possible for an outside attacker to alter your database content.
+     * dest - a list with AVP names where to store the result. The format
+       is "$avp(name1);$avp(name2);...". If this parameter is ommited, the
+       result is stored in "$avp(i:1);$avp(i:2);...". If the result gives
+       many rows, then multiple AVPs with corresponding name will be
+       added. The value type of the AVP (string or integer) will be
+       derived from the type of the columns. Please note that only this
+       two datatypes are supported, so its not possible for example to
+       return floating point or big integer values this way.
 
    The function delivers the following return-codes:
-     * -1 - An error occured while querying the database (e.g.
-       wrong SQL or database error)
+     * -1 - An error occured while querying the database (e.g. wrong SQL
+       or database error)
      * 1 - Query was successful
      * -2 - Query was successful, but no rows where returned.
 
@@ -400,22 +457,19 @@ avp_db_delete("$uuid","$avp(s:404fwd)/fwd_table");
 
    Example 1.15. avp_db_query usage
 ...
-avp_db_query("select password, ha1 from subscriber where username='$tu'"
-,
+avp_db_query("select password, ha1 from subscriber where username='$tu'",
         "$avp(i:678);$avp(i:679)");
 avp_db_query("delete from subscriber");
 ...
 
-1.5.5.  avp_delete(name)
+5.5. avp_delete(name)
 
    Deletes from memory the AVPs with name or, if empty, all AVPs.
 
    Meaning of the parameters is as follows:
-     * name - which AVPs will be deleted from memory. Parameter
-       syntax is:
+     * name - which AVPs will be deleted from memory. Parameter syntax is:
           + name = (matching_flags|avp_name|avp_alias)['/'flag]
-          + matching_flags = please refer to avp_db_load()
-            function
+          + matching_flags = please refer to avp_db_load() function
           + flag = 'g'|'G'
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
@@ -429,22 +483,21 @@ avp_delete("i");
 avp_delete("a3");
 ...
 
-1.5.6.  avp_pushto(destination,name)
+5.6. avp_pushto(destination,name)
 
    Pushes the value of AVP(s) into the SIP message.
 
    Meaning of the parameters is as follows:
      * destination - as what will be the AVP value pushed into SIP
        message. Parameter syntax:
-          + destination = '$ru' ['/'('username'|'domain')] | '$du'
-            | '$br'
-          + $ru '['/'('username'|'domain')] - write the AVP in the
-            request URI or in username/domain part of it
+          + destination = '$ru' ['/'('username'|'domain')] | '$du' | '$br'
+          + $ru '['/'('username'|'domain')] - write the AVP in the request
+            URI or in username/domain part of it
           + $du - write the AVP in 'dst_uri' field
-          + $br - write the AVP directly as a new branch (does not
-            affect RURI)
-     * name - which AVP(s)/pseudo-variable should be pushed into
-       the SIP message. Parameter syntax is:
+          + $br - write the AVP directly as a new branch (does not affect
+            RURI)
+     * name - which AVP(s)/pseudo-variable should be pushed into the SIP
+       message. Parameter syntax is:
           + name = ( avp_name | avp_alias | pvar_name )['/'flags]
           + flags = 'g' - effective only with AVPs
 
@@ -460,18 +513,18 @@ avp_pushto("$du","$avp(i:679)");
 avp_pushto("$br","$avp(i:680)");
 ...
 
-1.5.7.  avp_check(name,op_value)
+5.7. avp_check(name,op_value)
 
    Checks the value of the AVP(s) against an operator and value.
 
    Meaning of the parameters is as follows:
      * name - which AVP(s) should be checked. Parameter syntax is:
           + name = ( pseudo-variable )
-     * op_value - define the operator, the value and flags for
-       checking. Parameter syntax is:
+     * op_value - define the operator, the value and flags for checking.
+       Parameter syntax is:
           + op_value = operator '/' value ['/'flags]
-          + operator = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' |
-            're' | 'fm' | 'and' | 'or' | 'xor'
+          + operator = 'eq' | 'ne' | 'lt' | 'le' | 'gt' | 'ge' | 're' |
+            'fm' | 'and' | 'or' | 'xor'
           + value = pseudo-variable | fix_value
           + fix_value = 'i:'integer | 's:'string | string
           + flags = 'g' | 'G' | 'i' | 'I'
@@ -502,16 +555,15 @@ avp_check("$avp(s:foo)","re/sip:.*@bar.net/g");
 avp_check("$avp(s:foo)","fm/$avp(fm_avp)/g");
 ...
 
-1.5.8.  avp_copy(old_name,new_name)
+5.8. avp_copy(old_name,new_name)
 
    Copy / move an avp under a new name.
 
    Meaning of the parameters is as follows:
-     * name1 - which AVP(s) should be copied/moved. Parameter
-       syntax is:
+     * name1 - which AVP(s) should be copied/moved. Parameter syntax is:
           + name = ( avp_name | avp_alias )
-     * name2 - the new name of the copied/moved AVP(s). Parameter
-       syntax is:
+     * name2 - the new name of the copied/moved AVP(s). Parameter syntax
+       is:
           + name = ( avp_name | avp_alias ) ['/'flags]
           + flags = 'g' | 'G' | 'd' | 'D' | 'n' | 'N' | 's' | 'S'
 
@@ -524,19 +576,19 @@ avp_copy("$avp(i:678)", "$avp(s:345)/g");
 avp_copy("$avp(old)","$avp(new)/gd");
 ...
 
-1.5.9.  avp_printf(dest, format)
+5.9. avp_printf(dest, format)
 
-   NOTE: since Kamailio 1.3.0 the function has been moved to core
-   and it is an alias to pv_printf().
+   NOTE: since Kamailio 1.3.0 the function has been moved to core and it
+   is an alias to pv_printf().
 
-   Prints the formatted string 'format' in the AVP 'dest'. The
-   'format' parameter can include any pseudo-variable defined in
-   Kamailio. The list with all pseudo-variables in Kamailio can be
-   found at: http://kamailio.org/dokuwiki/.
+   Prints the formatted string 'format' in the AVP 'dest'. The 'format'
+   parameter can include any pseudo-variable defined in Kamailio. The list
+   with all pseudo-variables in Kamailio can be found at:
+   http://kamailio.org/dokuwiki/.
 
    Meaning of the parameters is as follows:
-     * dest - in which AVP should be stored the result. Parameter
-       syntax is:
+     * dest - in which AVP should be stored the result. Parameter syntax
+       is:
           + name = ( avp_name | avp_alias )
      * format - the formatted string to be printed in 'dest' AVP.
 
@@ -545,32 +597,29 @@ avp_copy("$avp(old)","$avp(new)/gd");
 
    Example 1.20. avp_printf usage
 ...
-avp_printf("$avp(i:20)", "This is a $rm request with call-id $hdr(call-i
-d)");
+avp_printf("$avp(i:20)", "This is a $rm request with call-id $hdr(call-id)");
 ...
 
-1.5.10.  avp_subst(avps, subst)
+5.10. avp_subst(avps, subst)
 
    Perl/sed-like subst applied to AVPs having string value.
 
    Meaning of the parameters is as follows:
-     * avps - source AVP, destination AVP and flags. Parameter
-       syntax is:
+     * avps - source AVP, destination AVP and flags. Parameter syntax is:
           + avps = src_avp [ '/' dst_avp [ '/' flags ] ]
           + src_avp = ( avp_name | avp_alias )
-          + dst_avp = ( avp_name | avp_alias ) - if dst_avp is
-            missing then the value of src_avp will be replaced
-          + flags = ( d | D | g | G ) -- (d, D - delete source
-            avp; g, G - apply to all avps matching src_avp name)
-     * subst - perl/sed-like reqular expression. Parameter syntax
-       is:
+          + dst_avp = ( avp_name | avp_alias ) - if dst_avp is missing
+            then the value of src_avp will be replaced
+          + flags = ( d | D | g | G ) -- (d, D - delete source avp; g, G -
+            apply to all avps matching src_avp name)
+     * subst - perl/sed-like reqular expression. Parameter syntax is:
           + subst = "/regexp/replacement/flags"
           + regexp - regular expression
-          + replacement - replacement string, can include
-            pseudo-variables and \1, ..., \9 for matching tokens,
-            \0 for whole matching text
-          + flags = 'g' | 'G' | 'i' | 'i' (g, G - replace all
-            matching tokens; i, I - match ignore case)
+          + replacement - replacement string, can include pseudo-variables
+            and \1, ..., \9 for matching tokens, \0 for whole matching
+            text
+          + flags = 'g' | 'G' | 'i' | 'i' (g, G - replace all matching
+            tokens; i, I - match ignore case)
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
@@ -587,30 +636,29 @@ avp_subst("$avp(i:678)", "/(.*)@(.*)/\1@$rd/");
 avp_subst("$avp(i:678)/$avp(i:679)/g", "/(.*)@(.*)/\1@$rd/");
 ...
 
-   IMPORTANT NOTE: if the replacement string includes src_avp or
-   dst_avp you will get something that you may not expect. In case
-   you have many src_avp and you make the substitution to be
-   applied to all of them, after the first src_avp is processed,
-   it will be added in avp list and next processing will use it.
+   IMPORTANT NOTE: if the replacement string includes src_avp or dst_avp
+   you will get something that you may not expect. In case you have many
+   src_avp and you make the substitution to be applied to all of them,
+   after the first src_avp is processed, it will be added in avp list and
+   next processing will use it.
 
-1.5.11.  avp_op(name,op_value)
+5.11. avp_op(name,op_value)
 
    Different integer operations with avps.
 
    Meaning of the parameters is as follows:
-     * name - 'source_avp/destination_avp' - which AVP(s) should
-       be processed and where to store the result. If
-       'destination_avp' is missing, same name as 'source_avp' is
-       used to store the result.
+     * name - 'source_avp/destination_avp' - which AVP(s) should be
+       processed and where to store the result. If 'destination_avp' is
+       missing, same name as 'source_avp' is used to store the result.
        Parameter syntax is:
           + name = ( source_avp[/destination_avp] )
             source_avp = ( avp_name | avp_alias )
             destination_avp = ( avp_name | avp_alias )
-     * op_value - define the operation, the value and flags.
-       Parameter syntax is:
+     * op_value - define the operation, the value and flags. Parameter
+       syntax is:
           + op_value = operator '/' value ['/'flags]
-          + operator = 'add' | 'sub' | 'mul' | 'div' | 'mod' |
-            'and' | 'or' | 'xor' | 'not'
+          + operator = 'add' | 'sub' | 'mul' | 'div' | 'mod' | 'and' |
+            'or' | 'xor' | 'not'
           + value = pseudo-variable | fix_value
           + fix_value = 'i:'integer
           + flags = 'g' | 'G' | 'd' | 'D'
@@ -626,15 +674,15 @@ avp_op("$avp(i:678)", "add/i:345/g");
 avp_op("$avp(number)","sub/$avp(number2)/d");
 ...
 
-1.5.12.  is_avp_set(name)
+5.12. is_avp_set(name)
 
    Check if any AVP with name is set.
 
    Meaning of the parameters is as follows:
      * name - name of AVP to look for. Parameter syntax is:
           + name = avp_name|avp_alias [ '/' flags ])
-            flags = ('e'|'s'|'n') - e = empty value; s = value
-            string; n = value number (int)
+            flags = ('e'|'s'|'n') - e = empty value; s = value string; n =
+            value number (int)
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE, LOCAL_ROUTE and ONREPLY_ROUTE.
@@ -645,7 +693,7 @@ if(is_avp_set("$avp(i:678)"))
     log("AVP with integer id 678 exists\n");
 ...
 
-1.5.13.  avp_print()
+5.13. avp_print()
 
    Prints the list with all the AVPs from memory. This is only a
    helper/debug function.

modules/avpops/doc/avpops_admin.xml

@@ -18,13 +18,14 @@
 	<section>
 		<title>Overview</title>
 		<para>
-		AVPops (AVP-operations) modules implements a set of script
-		functions which allow access and manipulation of user AVPs
-		(preferences) and pseudo-variables. AVPs are a powerful tool
-		for implementing services/preferences per user/domain. Now they
-		are usable directly from configuration script. Functions for
+		The AVPops (AVP-operations) module implements a set of script
+		functions which allow access and manipulation of user attribute-value pairs (AVPs,
+		preferences) and pseudo-variables. AVPs are a powerful tool
+		for implementing services/preferences per user/domain. With this module, they
+		are usable directly from configuration script. </para>
+		<para>The module implement functions for
 		interfacing DB resources (loading/storing/removing), functions
-		for swapping information between AVPs and SIP messages, function for 
+		for swapping information between AVPs and SIP messages and a function for 
 		testing/checking the value of an AVP.
 		</para>
 		<para>
@@ -36,8 +37,8 @@
 		</para>
 		<para>
 		An up-to-date tutorial providing more information (detailed
-		explanations and commented examples) can be found on Voice Sistem
-		documentation web page at http://voice-system.ro/docs/avpops .
+		explanations and commented examples) can be found on the SIP-router
+		web site.
 		</para>
 	</section>
 	<section>
@@ -85,13 +86,14 @@
 			<emphasis>avp_flags</emphasis> = type_flags [script_flags]; type_flags = 'I' | 'i' | 'S' | 's'; script_flags = 0..255
 		</para>
 		<para>
-		'I' or 'i' means that the type of avp name is integer (ID)
+		'I' or 'i' means that the type of avp name is an integer (ID)
 		</para>
 		<para>
 		'S' or 's' means that the type of avp name is string
 		</para>
 		<para>
 		The type flag is mandatory.
+		Please note that the type flag only indicates type of name, not type of variable. An avp with name type "i" may very well contain text strings.
 		</para>
 		<para>
 		script_flags must be an 8 bit unsigned number, therefore can be set
@@ -179,7 +181,7 @@ modparam("avpops","avp_table","avptable")
 		<section>
 			<title><varname>use_domain</varname> (integer)</title>
 			<para>
-				If the domain part of the an URI should be used for 
+				If the domain part of the URI should be used for 
 				identifying an AVP in DB operations.
 			</para>
 			<para>

modules/cfg_db/README

@@ -1,49 +1,61 @@
-
-cfg_db module
+1. cfg_db module
 
 Tomas Mandys
 
    Iptel.org
 
-   Copyright © 2008 Tomas Mandys
+   Copyright © 2008 Tomas Mandys
    Revision History
    Revision $Revision$ $Date$
-     _________________________________________________________________
-
-Overview
-
-   The module implements driver for config params API. When config parameters
-   are being declared (typically when is starting) API then driver is notified
-   and  has chance set value (of any parameter) based on value taken from
-   database. It's primarily targeted for interfacing with 3rd party software
-   which is aware of configuration.
-
-   Parameter is uniquely identified by group_name plus name. Hence the driver
-   checks  a  value  can be found regarding particular parameter. Because
-   configuration parameters may be spread in many tables, translation table
-   telling where parameters will be sniffed, is used first. More look-up tables
-   may be defined for single parameter, tables are sniffed in the first round
-   by exact match until parameter is found, all tables listed with wildcard
-   (asterisk) in group name are sniffed in the second round. If parameter is
-   not found then its value is left unchanged.
-
-   Config  parameters  are  normally  declared  in C code and this module
-   additionally supports also declaring custom parameters in extra table. Such
-   parameters may be used typically in script only. All parameters listed in
-   the table are declared in the first step, values are initialized in the
-   second step using the same procedure as C-code params.
-
-   The module does not reflect changes made in parameters when ser is running.
-   It just declares variable and assings value when ser is starting. That's
-   all.
-
-Dependencies
+     __________________________________________________________________
+
+   1.1. Overview
+   1.2. Dependencies
+   1.3. Parameters
+
+        1.3.1. db_url (string)
+        1.3.2. transl_tbl (string) := "cfg_transl"
+        1.3.3. custom_tbl (string) := "cfg_custom"
+
+   1.4. Functions
+   1.5. Examples
+
+1.1. Overview
+
+   The module implements a database driver for the configuration
+   parameters API. When configuration parameters are being declared
+   (typically when starting) API then driver is notified and has chance to
+   set value (of any parameter) based on value taken from database. It's
+   primarily targeted for interfacing with 3rd party software which is
+   aware of configuration.
+
+   Parameter is uniquely identified by group_name plus name, which is used
+   by the driver to check if a value can be found. Because configuration
+   parameters may be spread in many tables, a translation table is used to
+   indicate where to start searching. Multiple look-up tables may be
+   defined for single parameter, tables are searched in the first round by
+   exact match until parameter is found, all tables listed with wildcard
+   (asterisk) in group name are searched in the second round. If a
+   parameter is not found then its value is left unchanged.
+
+   Configuration parameters are normally declared in C code and this
+   module additionally supports also declaring custom parameters in extra
+   table. Such parameters may be used typically in script only. All
+   parameters listed in the table are declared in the first step, values
+   are initialized in the second step using the same procedure as C-code
+   parameters.
+
+   The module does not reflect changes made in parameters when SER is
+   running. It just declares variables and assigns values when SER is
+   starting. That's all.
+
+1.2. Dependencies
 
    A loaded database module.
 
-Parameters
+1.3. Parameters
 
-db_url (string)
+1.3.1. db_url (string)
 
    Default database URL.
 
@@ -54,41 +66,42 @@ db_url (string)
         loadmodule("mysql.so");
         loadmodule("cfg_db.so");
         ...
-        modparam("cfg_db", "db_url", "mysql://ser:[email protected]:12345/ser");
+        modparam("cfg_db", "db_url", "mysql://SER:[email protected]:12345/SER");
         ...
 
-transl_tbl (string) := "cfg_transl"
+1.3.2. transl_tbl (string) := "cfg_transl"
 
-   Name  of table used for pointing group_name+name into config table. If
-   empty/null field values are found then default values will be used. The
-   default values are declared in record having group_name called <default>.
-   The C-code "absolutely" default values ("cfg_var", "group_name", "name",
-   "value"). The other keyword is asterisk * which matches all parameters and
-   will be used if parameter is not explicitely mentioned.
+   Name of table used for pointing group_name+name into configuration
+   table. If empty/null field values are found then default values will be
+   used. The default values are declared in record having group_name
+   called <default>. The C-code "absolutely" default values ("cfg_var",
+   "group_name", "name", "value"). The other keyword is asterisk * which
+   matches all parameters and will be used if parameter is not explicitely
+   mentioned.
 
-custom_tbl (string) := "cfg_custom"
+1.3.3. custom_tbl (string) := "cfg_custom"
 
    Name of table used for extra param declaration (group_name, name, type,
    min/max value, description).
 
-Functions
+1.4. Functions
 
    None.
 
-Examples
+1.5. Examples
 
    Example 2. Content of tables
         cfg_transl table:
-        group_name|name|cfg_table|cfg_table_group_name_field|cfg_table_name_fie
-ld|cfg_table_value_field
+        group_name|name|cfg_table|cfg_table_group_name_field|cfg_table_name_fiel
+d|cfg_table_value_field
         core|use_dst_blacklist|cfg_dns|||
         core|dst_blacklist_mem|cfg_dns|||
         core|dst_blacklist_expire|||
-        my|route_addr|cfg_my|my_group_name|my_name|my_value     ; overrides <de
-fault> values
+        my|route_addr|cfg_my|my_group_name|my_name|my_value     ; overrides <def
+ault> values
         my|use_rtp_proxy|cfg_my|my_group_name|my_name|my_value
-        *|*|||| ; matches all param ids, points to tables defined in row <defau
-lt>
+        *|*|||| ; matches all param ids, points to tables defined in row <defaul
+t>
         <default>||cfg_var|group_name|name|value  ; default cfg_table* values
 
         cfg_custom table:

modules/cfg_db/doc/cfg_db.xml

@@ -1,6 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
 
 <section id="cfg_db" xmlns:xi="http://www.w3.org/2001/XInclude">
     <sectioninfo>
@@ -31,34 +36,32 @@
 	<section id="cfg_db.overview">
 		<title>Overview</title>
 		<para>
-		The module implements driver for config params API. When
-		config parameters are being declared (typically when is starting)
-		API then driver is notified and has chance set value (of any
+		The module implements a database driver for the configuration parameters API. When
+		configuration parameters are being declared (typically when starting)
+		API then driver is notified and has chance to set value (of any
 		parameter) based on value taken from database. It's primarily
 		targeted for interfacing with 3rd party software which is aware
 		of configuration.
 		</para>
 		<para>
 		Parameter is uniquely identified by <emphasis>group_name</emphasis> plus 
-		<emphasis>name</emphasis>. Hence the driver checks a value can be found
-		regarding particular parameter. Because configuration parameters may
-		be spread in many tables, translation table telling where parameters 
-		will be sniffed, is used first. More look-up tables may be defined for
-		single parameter, tables are sniffed in the first round by exact match
+		<emphasis>name</emphasis>, which is used by the driver to check if a value can be found.
+		Because configuration parameters may be spread in many tables, a translation table 
+		is used to indicate where to start searching.  Multiple look-up tables may be 
+		defined for single parameter, tables are searched in the first round by exact match
 		until parameter is found, all tables listed with wildcard (asterisk) in group name
-		are sniffed in the second round. If parameter is not found
-		then its value is left unchanged.
+		are searched in the second round. If a parameter is not found then its value is left unchanged.
 		</para>
 		<para>
-		Config parameters are normally declared in C code and this module
+		Configuration parameters are normally declared in C code and this module
 		additionally supports also declaring custom parameters in extra table.
 		Such parameters may be used typically in script only. All parameters
 		listed in the table are declared in the first step, values are initialized
-		in the second step using the same procedure as C-code params.
+		in the second step using the same procedure as C-code parameters.
 		</para>
 		<para>
-		The module does not reflect changes made in parameters when ser is running.
-		It just declares variable and assings value when ser is starting. That's all.
+		The module does not reflect changes made in parameters when &ser; is running.
+		It just declares variables and assigns values when &ser; is starting. That's all.
 		</para>
 	</section>
 
@@ -92,7 +95,7 @@
 	loadmodule("mysql.so");
 	loadmodule("cfg_db.so");
 	...
-	modparam("cfg_db", "db_url", "mysql://ser:[email protected]:12345/ser");
+	modparam("cfg_db", "db_url", "mysql://&ser;:[email protected]:12345/&ser;");
 	...
 				</programlisting>
 			</example>
@@ -102,7 +105,7 @@
 			<title><varname>transl_tbl</varname> (string) := "cfg_transl"</title>
 			<para>
 				Name of table used for pointing group_name+name into
-				config table. If empty/null field values are found
+				configuration table. If empty/null field values are found
 				then default values will be used. The default
 				values are declared in record having <emphasis>group_name</emphasis>
 				called <emphasis>&lt;default&gt;</emphasis>. The C-code

modules/cfg_rpc/README

@@ -13,8 +13,9 @@ Miklos Tirpak
 1.1. Overview
 
    The module implements RPC functions to set and get configuration
-   variables on-the-fly, that are declared by SER core and by the modules.
-   It can be used to fine-tune or debug SER without the need of restart.
+   variables on-the-fly, that are declared by SIP Router core and by the
+   modules. It can be used to fine-tune or debug SIP Router without the
+   need of restart.
 
 1.2. RPC Interface
 

modules/cfg_rpc/doc/cfg_rpc.xml

@@ -1,6 +1,11 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
 
 <section id="gflags" xmlns:xi="http://www.w3.org/2001/XInclude">
     <sectioninfo>
@@ -24,8 +29,8 @@
 	<para>
 	    The module implements RPC functions to set and get
 	    configuration variables on-the-fly, that are declared
-	    by SER core and by the modules. It can be used to fine-tune
-	    or debug SER without the need of restart.
+	    by &siprouter; core and by the modules. It can be used to fine-tune
+	    or debug &siprouter; without the need of restart.
 	</para>
     </section>
 

modules/lcr/README

@@ -189,48 +189,52 @@ Chapter 1. Admin Guide
 
 1. Overview
 
-   Least cost routing (LCR) module implements capability to serially
+   The Least Cost Routing (LCR) module implements capability to serially
    forward a request to one or more gateways so that the order in which
    the gateways is tried is based on admin defined "least cost" rules.
 
-   LCR module supports many independent LCR instances (gateways and least
-   cost rules). Each such instance has its own LCR identifier.
+   The LCR module supports many independent LCR instances (gateways and
+   least cost rules). Each such instance has its own LCR identifier.
 
    For the purpose of facilitating least cost routing of requests, each
    gateway of an LCR instance belongs to a gateway group and each gateway
    group is associated with one or more <prefix, from pattern, priority>
-   tuples. A gateway matches a request if user part of Request URI matches
-   a prefix and caller's URI matches a from pattern in a tuple that
-   belongs to the group of the gateway.
-
-   When function load_gws() is called, matching gateways (that are not
-   currently designated as defunct) are ordered for forwarding purpose (1)
-   according to longest user part match, (2) according to tuple's
-   priority, and (3) gateway's randomized weight within its group. Prefix
-   is a string of characters or NULL. From pattern is a regular expression
-   (see 'man pcresyntax' for syntax), an empty string, or NULL. Empty or
-   NULL from pattern or prefix matches anything. Smaller priority value
-   means higher priority (highest priority value being 0). Weight is an
-   integer value from 1 to 254.
-
-   Function next_gw() can then be used to select one gateway at a time for
-   forwarding. Upon each call, user part of original Request URI is first
-   stripped by the number of characters as specified by the gateway's
-   strip count and then prefixed by gateway's tag. Upon first call, if
-   gateway's hostname is NULL, Request URI is rewritten based on gateway's
-   URI scheme, IP address, port, and transport protocol. If hostname is
-   not NULL, Request-URI is rewritten based on gateway's URI scheme and
-   hostname, and destination URI is set based on gateway's URI scheme, IP
-   address, port, and transport protocol. Upon subsequent calls, the same
-   is done, but instead of rewriting Request URI, a new branch is added.
+   tuples. A gateway matches a request if the user part of the Request URI
+   matches a "prefix" and the caller's URI matches a "from" pattern in a
+   tuple that belongs to the group of the gateway.
+
+   When the function load_gws() is called, matching gateways (that are not
+   currently designated as defunct) are ordered for forwarding purposes in
+   the following order:
+     * (1) according to longest user part match
+     * (2) according to tuple's priority
+     * (3) gateway's randomized weight within its group
+
+   Prefix is a string of characters or NULL. From pattern is a regular
+   expression (see 'man pcresyntax' for syntax), an empty string, or NULL.
+   An empty or NULL from pattern or prefix matches anything. Smaller
+   priority value means higher priority (highest priority value being 0).
+   Weight is an integer value from 1 to 254.
+
+   The function next_gw() can then be used to select one gateway at a time
+   for forwarding. Upon each call, the user part of the original request
+   URI is first stripped by the number of characters as specified by the
+   gateway's strip count and then prefixed by the gateway's tag. Upon
+   first call, if a gateway's hostname is NULL, the request URI will be
+   rewritten based on gateway's URI scheme, IP address, port, and
+   transport protocol. If hostname is not NULL, the request-URI is
+   rewritten based on the gateway's URI scheme and hostname, and
+   destination URI is set based on gateway's URI scheme, IP address, port,
+   and transport protocol. Upon subsequent calls, the same is done, but
+   instead of rewriting the Request URI, a new branch is added.
 
    Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently
    valid transport protocol values are NULL = none, 1 = udp, 2 = tcp, 3 =
    tls, and 4 = sctp.
 
-   As a side effect of gateway selection, gateway's flags (that may
-   contain information about capabilities of the gateway) are stored into
-   an AVP.
+   As a side effect of the gateway selection, the gateway's flags (that
+   may contain information about capabilities of the gateway) are stored
+   into an AVP.
 
 2. Dependencies
 
@@ -304,7 +308,7 @@ modparam("lcr","gw_table","gw")
 
 3.3. lcr_id_column (string)
 
-   Name of the column holding the identifier of LCR instance. Common to
+   Name of the column holding the identifier of an LCR instance. Common to
    both gw and lcr tables.
 
    Default value is "lcr_id".
@@ -353,13 +357,13 @@ modparam("lcr","ip_addr_column","ip_addr")
    Name of the column holding gateway's hostname that is used in
    Request-URI, when request is sent to the gateway. Note that request is
    not forwarded based on hostname, but based on gateway's IP address in
-   destination uri.
+   destination URI.
 
    Default value is "hostname".
 
    Example 1.7. Setting hostname_column module parameter
 ...
-modparam("lcr", "hostname_column","host")
+modparam("lcr", "hostname_column","hostname")
 ...
 
 3.8. port_column (string)
@@ -381,7 +385,7 @@ modparam("lcr","port_column","port")
 
    Example 1.9. Setting uri_scheme_column module parameter
 ...
-modparam("lcr","uri_scheme_column","scheme")
+modparam("lcr","uri_scheme_column","uri_scheme")
 ...
 
 3.10. transport_column (string)
@@ -503,7 +507,7 @@ modparam("lcr","priority_column","priority")
 
    Default value is 1.
 
-   Example 1.20.  Setting lcr_count module parameter
+   Example 1.20. Setting lcr_count module parameter
 ...
 modparam("lcr", "lcr_count", 10)
 ...
@@ -554,7 +558,7 @@ modparam("lcr", "flags_avp", "$avp(i:712)")
 
    Default value is 0.
 
-   Example 1.24.  Setting defunct_capability module parameter
+   Example 1.24. Setting defunct_capability module parameter
 ...
 modparam("lcr", "defunct_capability", 1)
 ...
@@ -594,7 +598,7 @@ modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)")
 
    Default value is 128.
 
-   Example 1.27.  Setting lcr_hash_size module parameter
+   Example 1.27. Setting lcr_hash_size module parameter
 ...
 modparam("lcr", "lcr_hash_size", 1024)
 ...
@@ -602,10 +606,10 @@ modparam("lcr", "lcr_hash_size", 1024)
 3.28. fetch_rows (integer)
 
    The number of the rows to be fetched at once from database when loading
-   data from lcr table. This value can be used to tune the load time at
-   startup. For 1MB of private memory (default) it should be below 3750.
-   In order for this parameter to have effect, database driver must
-   support fetch_result() capability.
+   data from the lcr table. This value can be used to tune the load time
+   at startup. For 1MB of private memory (default) it should be below
+   3750. In order for this parameter to have effect, the database driver
+   must support fetch_result() capability.
 
    Default value is "2000".
 
@@ -624,7 +628,7 @@ modparam("lcr", "fetch_rows", 3000)
    4.6. to_gw(lcr_id [, ip_addr])
    4.7. to_any_gw([ip_addr])
 
-4.1.  load_gws(lcr_id, caller_uri)
+4.1. load_gws(lcr_id, caller_uri)
 
    Loads URI schemes, IP addresses, hostnames, ports, and transports of
    matching gateways to gw_uri_avp (see Overview section). Argument lcr_id
@@ -648,7 +652,7 @@ if (!load_gws("1", "$var(caller_uri)")) {
 };
 ...
 
-4.2.  next_gw()
+4.2. next_gw()
 
    Upon first call, replaces URI scheme, host, port, and transport of
    Request-URI by the values stored in first gw_uri_avp and destroys that
@@ -685,7 +689,7 @@ if (!next_gw()) {
 };
 ...
 
-4.3.  defunct_gw(period)
+4.3. defunct_gw(period)
 
    Defuncts gateway selected by preceding next_gw() call for a period of
    seconds given as argument. Argument must be a positive integer constant
@@ -703,7 +707,7 @@ if (!next_gw()) {
 defunct_gw("60");
 ...
 
-4.4.  from_gw(lcr_id [, ip_addr])
+4.4. from_gw(lcr_id [, ip_addr])
 
    Checks if request comes from IP address of a gateway in LCR instance
    specified by lcr_id argument, which can be an integer constant or a
@@ -729,17 +733,17 @@ if (from_gw("1", "$avp(s:real_source_addr)") {
 };
 ...
 
-4.5.  from_any_gw([ip_addr])
+4.5. from_any_gw([ip_addr])
 
    Checks if request comes from IP address of any gateway. IP address to
    be checked is either taken from source IP address of the request or (if
    present) from ip_addr pseudo variable argument.
 
    If any gateway has the IP address, function returns LCR identifier of
-   the gateway. Returns -1 on error or if request does not come from a
+   the gateway. Returns -1 on error or if the request does not come from a
    gateway.
 
-   If request comes from a gateway, gateway's flags are stored into
+   If request comes from a gateway, the gateway's flags are stored into
    flags_avp as side effect.
 
    Execution time of from_gw() function is M * O(log N), where M is number
@@ -753,7 +757,7 @@ if (from_gw("1", "$avp(s:real_source_addr)") {
 $var(lcr_id) = from_any_gw();
 ...
 
-4.6.  to_gw(lcr_id [, ip_addr])
+4.6. to_gw(lcr_id [, ip_addr])
 
    Checks if in-dialog request goes to a gateway in LCR instance specified
    by lcr_id argument. IP address to be checked is either taken from
@@ -775,7 +779,7 @@ if (to_gw("1")) {
 };
 ...
 
-4.7.  to_any_gw([ip_addr])
+4.7. to_any_gw([ip_addr])
 
    Checks if in-dialog request goes to any gateway. IP address to be
    checked is either taken from Request-URI hostpart or (if present) from

modules/lcr/doc/lcr_admin.xml

@@ -16,51 +16,59 @@
 	<section>
 	<title>Overview</title>
 	<para>
-	Least cost routing (LCR) module implements capability to
+	The Least Cost Routing (LCR) module implements capability to
 	serially forward a request to one or more gateways so that the
 	order in which the gateways is tried is based on admin defined
 	"least cost" rules.
 	</para>
 	<para>
-	LCR module supports many independent LCR instances (gateways and
-	least cost rules).  Each such instance has its own LCR
-	identifier.
+	The LCR module supports many independent LCR instances (gateways and
+	least cost rules).  Each such instance has its own <emphasis>LCR
+	identifier.</emphasis>
 	</para>
 	<para>
 	For the purpose of facilitating least cost routing of requests,
 	each gateway of an LCR instance belongs to a gateway group and
-	each gateway group
-	is associated with one or more &lt;prefix, from pattern, priority&gt;
-	tuples.  A gateway matches a request if	user part of Request URI
-	matches a prefix and caller's URI matches a from pattern in a
+	each gateway group is associated with one or more 
+	&lt;prefix, from pattern, priority&gt;
+	tuples.  A gateway matches a request if	the user part of the Request URI
+	matches a "prefix" and the caller's URI matches a "from" pattern in a
 	tuple that belongs to the group of the gateway.
 	</para>
 	<para>
-	When function load_gws() is called, matching gateways (that are
+	When the function <emphasis>load_gws()</emphasis> is called, matching gateways (that are
 	not currently designated as defunct) are ordered
-	for forwarding purpose (1) according to longest user part match,
-	(2) according to  
-	tuple's priority, and (3) gateway's randomized weight within its
-	group.  Prefix is a string of characters or NULL.  From
+	for forwarding purposes in the following order:
+	<itemizedlist>
+            <listitem>
+                <para>(1) according to longest user part match
+                </para>
+            </listitem>
+            <listitem>
+                <para>(2) according to tuple's priority
+                </para>
+            </listitem>
+            <listitem>
+                <para>(3) gateway's randomized weight within its group
+                </para>
+            </listitem>
+        </itemizedlist>
+	Prefix is a string of characters or NULL.  From
 	pattern is a regular expression (see 'man 
-	pcresyntax' for syntax), an empty string, or NULL.  Empty or
+	pcresyntax' for syntax), an empty string, or NULL.  An empty or
 	NULL from pattern or prefix matches anything. 
 	Smaller priority value means higher priority (highest priority
 	value being 0).  Weight is an integer value from 1 to 254.
 	</para>
 	<para>
-        Function next_gw() can then be used to select one gateway at a
-	time for forwarding.  Upon each call, user part of original
-	Request URI is first stripped by the number of characters as
-	specified by the gateway's strip count and then prefixed by
-	gateway's tag.  Upon first call, if gateway's hostname is NULL,
-	Request URI is rewritten based on gateway's URI scheme, IP
-	address, port, and transport protocol.  If hostname is not NULL,
-	Request-URI is rewritten based on gateway's URI scheme and
-	hostname, and destination URI is set based on gateway's URI
-	scheme, IP address, port, and transport protocol.  Upon
-	subsequent calls, the same is done, but instead of rewriting
-	Request URI, a new branch is added.
+        The function <emphasis>next_gw()</emphasis> can then be used to select one gateway at a
+	time for forwarding.  Upon each call, the user part of the original request URI is first 
+	stripped by the number of characters as specified by the gateway's strip count and then prefixed by
+	the gateway's tag.  Upon first call, if a gateway's hostname is NULL, the request URI will be 
+	rewritten based on gateway's URI scheme, IP address, port, and transport protocol.  If hostname is not NULL,
+	the request-URI is rewritten based on the gateway's URI scheme and hostname, and destination URI is set 
+	based on gateway's URI scheme, IP address, port, and transport protocol.  Upon
+	subsequent calls, the same is done, but instead of rewriting the Request URI, a new branch is added.
 	</para>
         <para>
         Valid URI scheme values are NULL = sip, 1 = sip and 2
@@ -68,7 +76,7 @@
 	none, 1 = udp, 2 = tcp, 3 = tls, and 4 = sctp.
 	</para>
 	<para>
-	As a side effect of gateway selection, gateway's flags (that may
+	As a side effect of the gateway selection, the gateway's flags (that may
 	contain information about capabilities of the gateway)
 	are stored into an AVP.
 	</para>
@@ -157,8 +165,7 @@ modparam("lcr","gw_table","gw")
 	<section>
 		<title><varname>lcr_id_column</varname> (string)</title>
 		<para>
-		Name of the column holding the identifier of LCR
-		instance.  Common to both gw and lcr tables.
+		Name of the column holding the identifier of an LCR instance.  Common to both gw and lcr tables.
 		</para>
 		<para>
 		<emphasis>
@@ -243,7 +250,7 @@ modparam("lcr","ip_addr_column","ip_addr")
 		used in Request-URI, when request is sent to the
 		gateway.  Note that request is not forwarded based on
 		hostname, but based on gateway's IP address in
-		destination uri.
+		destination URI.
 		</para>
 		<para>
 		<emphasis>
@@ -254,7 +261,7 @@ modparam("lcr","ip_addr_column","ip_addr")
 		<title>Setting <varname>hostname_column</varname> module parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("lcr", "hostname_column","host")
+modparam("lcr", "hostname_column","hostname")
 ...
 </programlisting>
 		</example>
@@ -295,7 +302,7 @@ modparam("lcr","port_column","port")
 		parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("lcr","uri_scheme_column","scheme")
+modparam("lcr","uri_scheme_column","uri_scheme")
 ...
 </programlisting>
 		</example>
@@ -557,8 +564,8 @@ modparam("lcr", "gw_uri_avp", "$avp(i:709)")
 	<section>
 		<title><varname>ruri_user_avp</varname> (AVP string)</title>
 		<para>
-   Internal AVP that next_gw function uses to store Request-URI user for
-   subsequent next_gw calls.
+   		Internal AVP that next_gw function uses to store Request-URI user for
+   		subsequent next_gw calls.
 		</para>
 		<para>
 		<emphasis>
@@ -647,9 +654,8 @@ modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)")
 	<section>
 		<title><varname>defunct_gw_avp</varname> (AVP string)</title>
 		<para>
-		Internal AVP that next_gw() function uses to store
-		IP address of the selected gateway for later use by
-		defunct_gw() function.  Only needed if
+		Internal AVP that next_gw() function uses to store IP address of the 
+		selected gateway for later use by defunct_gw() function.  Only needed if
 		gateway defunct capability has been activated.
 		</para>
 		<para>
@@ -698,10 +704,10 @@ modparam("lcr", "lcr_hash_size", 1024)
 		<title><varname>fetch_rows</varname> (integer)</title>
 		<para>
 		The number of the rows to be fetched at once from database
-		when loading data from lcr table. This value can be used to tune
+		when loading data from the lcr table. This value can be used to tune
 		the load time at startup.  For 1MB of private memory (default)
 		it should be below 3750. In order for this parameter to
-		have effect, database driver must support fetch_result()
+		have effect, the database driver must support fetch_result()
 		capability.
 		</para>
 		<para>
@@ -900,12 +906,11 @@ if (from_gw("1", "$avp(s:real_source_addr)") {
 		<para>
 		If any gateway has the IP address, function returns LCR
 		identifier 
-		of the gateway.  Returns -1 on error or if request does
+		of the gateway.  Returns -1 on error or if the request does
 		not come from a gateway. 
 		</para>
 		<para>
-		If request comes
-		from a gateway, gateway's flags are stored into flags_avp
+		If request comes from a gateway, the gateway's flags are stored into flags_avp
 		as side effect.
 		</para>
 		<para>

modules/lcr/hash.c

@@ -3,14 +3,14 @@
  *
  * Copyright (C) 2008-2009 Juha Heinanen
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -20,6 +20,12 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router LCR :: Header file for hash table functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
 
 #include "../../mem/shm_mem.h"
 #include "../../lib/kcore/hash_func.h"

modules/lcr/hash.h

@@ -20,6 +20,12 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router lcr :: Header file for hash table functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
 
 #ifndef _LCR_HASH_H_
 #define _LCR_HASH_H_

modules/lcr/lcr_mod.c

@@ -39,6 +39,22 @@
  *  2009-06-21  Added support for more than one lcr instance and
                 gw defunct capability (jh)
  */
+/*!
+ * \file
+ * \brief SIP-router LCR :: Module interface
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
+
+/*! \defgroup lcr SIP-router Least Cost Routing Module
+ *
+ * The Least Cost Routing (LCR) module implements capability to serially
+ * forward a request to one or more gateways so that the order in which
+ * the gateways is tried is based on admin defined "least cost" rules.
+
+ * The LCR module supports many independent LCR instances (gateways and
+ * least cost rules). Each such instance has its own LCR identifier.
+ */
 
 #include <stdio.h>
 #include <stdlib.h>

modules/lcr/lcr_mod.h

@@ -26,6 +26,13 @@
  * 2005-02-06: created by jh
  */
 
+/*!
+ * \file
+ * \brief SIP-router lcr :: Various LCR related functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
+
 
 #ifndef LCR_MOD_H
 #define LCR_MOD_H

modules/lcr/lcr_rpc.c

@@ -1,5 +1,5 @@
 /*
- * Various lcr related functions
+ * Various lcr related functions :: RPC API
  *
  * Copyright (C) 2005 Juha Heinanen
  *
@@ -25,6 +25,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router lcr :: rpc API interface
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
+
 #include "lcr_rpc.h"
 
 #ifdef RPC_SUPPORT

modules/lcr/lcr_rpc.h

@@ -24,6 +24,12 @@
  * along with this program; if not, write to the Free Software 
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
+/*!
+ * \file
+ * \brief SIP-router lcr :: RPC API functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
 
 #ifndef _LCR_RPC_H
 #define _LCR_RPC_H

modules/lcr/mi.c

@@ -26,6 +26,13 @@
  *  2006-10-05  created (bogdan)
  */
 
+/*!
+ * \file
+ * \brief SIP-router lcr :: Kamailio MI functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
+
 
 #include "lcr_mod.h"
 #include "../../dprint.h"

modules/lcr/mi.h

@@ -25,6 +25,12 @@
  * --------
  *  2006-10-05  created (bogdan)
  */
+/*!
+ * \file
+ * \brief SIP-router lcr :: Header file for Kamailio MI functions
+ * \ingroup lcr
+ * Module: \ref lcr
+ */
 
 
 #ifndef _LCR_MI_H_