dispatcher: added doc/Makefile

- makefile rules to generate documentation
- entities.xml => kam_entities.xml
- module_faq.xml => kam_module_faq.xml

modules_k/dispatcher/README

@@ -20,9 +20,8 @@ Carsten Bock
 
    Copyright © 2005 Voice-System.RO
    Revision History
-   Revision $Revision$ $Date: 2008-08-06 13:08:33 +0300
-                              (Wed, 06 Aug 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
@@ -114,10 +113,9 @@ Chapter 1. Admin Guide
 
 1.1. Overview
 
-   This modules implements a dispatcher for destination addresses.
-   It computes hashes over parts of the request and selects an
-   address from a destination set. The selected address is used
-   then as outbound proxy.
+   This modules implements a dispatcher for destination addresses. It
+   computes hashes over parts of the request and selects an address from a
+   destination set. The selected address is used then as outbound proxy.
 
    The module can be used as a stateless load balancer, having no
    guarantee of fair distribution.
@@ -131,8 +129,8 @@ Chapter 1. Admin Guide
 
 1.2.2. External libraries or applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module:
+   The following libraries or applications must be installed before
+   running Kamailio with this module:
      * none.
 
 1.3. Exported Parameters
@@ -151,21 +149,20 @@ modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
 
 1.3.2. db_url (string)
 
-   If you want to load the sets of gateways from the database you
-   must set this parameter.
+   If you want to load the sets of gateways from the database you must set
+   this parameter.
 
    Default value is "NULL" (disable DB support).
 
    Example 1.2. Set "db_url" parameter
 ...
-modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database
-")
+modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
 ...
 
 1.3.3. table_name (string)
 
-   If you want to load the sets of gateways from the database you
-   must set this parameter as the database name.
+   If you want to load the sets of gateways from the database you must set
+   this parameter as the database name.
 
    Default value is "dispatcher".
 
@@ -176,8 +173,7 @@ modparam("dispatcher", "table_name", "my_dispatcher")
 
 1.3.4. setid_col (string)
 
-   The column's name in the database storing the gateway's group
-   id.
+   The column's name in the database storing the gateway's group id.
 
    Default value is "setid".
 
@@ -188,8 +184,7 @@ modparam("dispatcher", "setid_col", "groupid")
 
 1.3.5. destination_col (string)
 
-   The column's name in the database storing the destination's sip
-   uri.
+   The column's name in the database storing the destination's sip uri.
 
    Default value is "destination".
 
@@ -200,8 +195,8 @@ modparam("dispatcher", "destination_col", "uri")
 
 1.3.6. flags_col (string)
 
-   The column's name in the database storing the flags for
-   destination uri.
+   The column's name in the database storing the flags for destination
+   uri.
 
    Default value is "flags".
 
@@ -212,8 +207,8 @@ modparam("dispatcher", "flags_col", "dstflags")
 
 1.3.7. priority_col (string)
 
-   The column's name in the database storing the priority for
-   destination uri.
+   The column's name in the database storing the priority for destination
+   uri.
 
    Default value is "priority".
 
@@ -224,8 +219,8 @@ modparam("dispatcher", "priority_col", "dstpriority")
 
 1.3.8. force_dst (int)
 
-   If set to 1, force overwriting of destination address when that
-   is already set.
+   If set to 1, force overwriting of destination address when that is
+   already set.
 
    Default value is "0".
 
@@ -236,17 +231,17 @@ modparam("dispatcher", "force_dst", 1)
 
 1.3.9. flags (int)
 
-   Various flags that affect dispatcher's behaviour. The flags are
-   defined as a bitmask on an integer value. If flag 1 is set only
-   the username part of the uri will be used when computing an uri
-   based hash. If no flags are set the username, hostname and port
-   will be used The port is used only if different from 5060
-   (normal sip uri) or 5061 (in the sips case).
+   Various flags that affect dispatcher's behaviour. The flags are defined
+   as a bitmask on an integer value. If flag 1 is set only the username
+   part of the uri will be used when computing an uri based hash. If no
+   flags are set the username, hostname and port will be used The port is
+   used only if different from 5060 (normal sip uri) or 5061 (in the sips
+   case).
 
-   If flag 2 is set, then the failover support is enabled. The
-   functions exported by the module will store the rest of
-   addresses from the destination set in AVP, and use these AVPs
-   to contact next address when the current-tried fails.
+   If flag 2 is set, then the failover support is enabled. The functions
+   exported by the module will store the rest of addresses from the
+   destination set in AVP, and use these AVPs to contact next address when
+   the current-tried fails.
 
    Default value is "0".
 
@@ -257,10 +252,10 @@ modparam("dispatcher", "force_dst", 1)
 
 1.3.10. use_default (int)
 
-   If the parameter is set to 1, the last address in destination
-   set is used as last option to send the message. For example, it
-   is good when wanting to send the call to an anouncement server
-   saying: "the gateways are full, try later".
+   If the parameter is set to 1, the last address in destination set is
+   used as last option to send the message. For example, it is good when
+   wanting to send the call to an anouncement server saying: "the gateways
+   are full, try later".
 
    Default value is "0".
 
@@ -271,18 +266,16 @@ modparam("dispatcher", "force_dst", 1)
 
 1.3.11. dst_avp (str)
 
-   The name of the avp which will hold the list with addresses, in
-   the order they have been selected by the chosen algorithm. If
-   use_default is 1, the value of last dst_avp_id is the last
-   address in destination set. The first dst_avp_id is the
-   selected destinations. All the other addresses from the
-   destination set will be added in the avp list to be able to
-   implement serial forking.
+   The name of the avp which will hold the list with addresses, in the
+   order they have been selected by the chosen algorithm. If use_default
+   is 1, the value of last dst_avp_id is the last address in destination
+   set. The first dst_avp_id is the selected destinations. All the other
+   addresses from the destination set will be added in the avp list to be
+   able to implement serial forking.
 
 Note
 
-   You must set this parameter if you want do do load balancing
-   fail over.
+   You must set this parameter if you want do do load balancing fail over.
 
    Default value is "null" - don't add AVPs.
 
@@ -293,13 +286,12 @@ Note
 
 1.3.12. grp_avp (str)
 
-   The name of the avp storing the group id of the destination
-   set. Good to have it for later usage or checks.
+   The name of the avp storing the group id of the destination set. Good
+   to have it for later usage or checks.
 
 Note
 
-   You must set this parameter if you want do do load balancing
-   fail over.
+   You must set this parameter if you want do do load balancing fail over.
 
    Default value is "null" - don't add AVP.
 
@@ -310,13 +302,12 @@ Note
 
 1.3.13. cnt_avp (str)
 
-   The name of the avp storing the number of destination addresses
-   kept in dst_avp avps.
+   The name of the avp storing the number of destination addresses kept in
+   dst_avp avps.
 
 Note
 
-   You must set this parameter if you want do do load balancing
-   fail over.
+   You must set this parameter if you want do do load balancing fail over.
 
    Default value is "null" - don't add AVP.
 
@@ -331,8 +322,8 @@ Note
 
 Note
 
-   You must set this parameter if you want do hashing over custom
-   message parts.
+   You must set this parameter if you want do hashing over custom message
+   parts.
 
    Default value is "null" - disabled.
 
@@ -348,8 +339,8 @@ Note
 
 1.3.15. setid_pvar (str)
 
-   The name of the PV where to store the set ID (group ID) when
-   calling ds_is_from_list() with no parameter.
+   The name of the PV where to store the set ID (group ID) when calling
+   ds_is_from_list() with no parameter.
 
    Default value is "null" - don't set PV.
 
@@ -360,9 +351,9 @@ Note
 
 1.3.16. ds_ping_method (string)
 
-   With this Method you can define, with which method you want to
-   probe the failed gateways. This method is only available, if
-   compiled with the probing of failed gateways enabled.
+   With this Method you can define, with which method you want to probe
+   the failed gateways. This method is only available, if compiled with
+   the probing of failed gateways enabled.
 
    Default value is "OPTIONS".
 
@@ -373,10 +364,9 @@ Note
 
 1.3.17. ds_ping_from (string)
 
-   With this Method you can define the "From:"-Line for the
-   request, sent to the failed gateways. This method is only
-   available, if compiled with the probing of failed gateways
-   enabled.
+   With this Method you can define the "From:"-Line for the request, sent
+   to the failed gateways. This method is only available, if compiled with
+   the probing of failed gateways enabled.
 
    Default value is "sip:dispatcher@localhost".
 
@@ -387,10 +377,9 @@ Note
 
 1.3.18. ds_ping_interval (int)
 
-   With this Method you can define the interval for sending a
-   request to a failed gateway. This parameter is only used, when
-   the TM-Module is loaded. If set to "0", the pinging of failed
-   requests is disabled.
+   With this Method you can define the interval for sending a request to a
+   failed gateway. This parameter is only used, when the TM-Module is
+   loaded. If set to "0", the pinging of failed requests is disabled.
 
    Default value is "10".
 
@@ -402,9 +391,8 @@ Note
 1.3.19. ds_probing_threshhold (int)
 
    If you want to set a gateway into probing mode, you will need a
-   specific number of requests until it will change from "active"
-   to probing. The number of attempts can be set with this
-   parameter.
+   specific number of requests until it will change from "active" to
+   probing. The number of attempts can be set with this parameter.
 
    Default value is "3".
 
@@ -415,11 +403,10 @@ Note
 
 1.3.20. ds_probing_mode (int)
 
-   Controls what gateways are tested to see if they are reachable.
-   If set to 0, only the gateways with state PROBING are tested,
-   if set to 1, all gateways are tested. If set to 1 and the
-   response is 408 (timeout), an active gateway is set to PROBING
-   state.
+   Controls what gateways are tested to see if they are reachable. If set
+   to 0, only the gateways with state PROBING are tested, if set to 1, all
+   gateways are tested. If set to 1 and the response is 408 (timeout), an
+   active gateway is set to PROBING state.
 
    Default value is "0".
 
@@ -430,8 +417,8 @@ Note
 
 1.3.21. ds_append_branch (int)
 
-   If set to 1, functions will automaticall append a new branch if
-   called in FAILURE_ROUTE. If set to 0, script writer has to call
+   If set to 1, functions will automaticall append a new branch if called
+   in FAILURE_ROUTE. If set to 0, script writer has to call
    append_branch() in config after calling dispatcher functions.
 
    Default value is "1".
@@ -448,28 +435,28 @@ Note
    The method selects a destination from addresses set.
 
    Meaning of the parameters is as follows:
-     * set - the id of the set from where to pick up destination
-       address. It is the first column in destination list file.
+     * set - the id of the set from where to pick up destination address.
+       It is the first column in destination list file.
      * alg - the algorithm used to select the destination address.
           + "0" - hash over callid
           + "1" - hash over from uri.
           + "2" - hash over to uri.
           + "3" - hash over request-uri.
           + "4" - round-robin (next destination).
-          + "5" - hash over authorization-username
-            (Proxy-Authorization or "normal" authorization). If no
-            username is found, round robin is used.
+          + "5" - hash over authorization-username (Proxy-Authorization or
+            "normal" authorization). If no username is found, round robin
+            is used.
           + "6" - random (using rand()).
-          + "7" - hash over the content of PVs string. Note: This
-            works only when the parameter hash_pvar is set.
+          + "7" - hash over the content of PVs string. Note: This works
+            only when the parameter hash_pvar is set.
           + "8" - use first destination (good for failover).
-          + "X" - if the algorithm is not implemented, the first
-            entry in set is chosen.
+          + "X" - if the algorithm is not implemented, the first entry in
+            set is chosen.
 
-   If the bit 2 in 'flags' is set, the rest of the addresses from
-   the destination set is stored in AVP list. You can use
-   'ds_next_dst()' to use next address to achieve serial forking
-   to all possible destinations.
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
+   destination set is stored in AVP list. You can use 'ds_next_dst()' to
+   use next address to achieve serial forking to all possible
+   destinations.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -480,75 +467,70 @@ ds_select_dst("1", "0");
 
 1.4.2.  ds_select_domain(set, alg)
 
-   The method selects a destination from addresses set and
-   rewrites the host and port from R-URI. The parameters have same
-   meaning as for ds_select_dst().
+   The method selects a destination from addresses set and rewrites the
+   host and port from R-URI. The parameters have same meaning as for
+   ds_select_dst().
 
-   If the bit 2 in 'flags' is set, the rest of the addresses from
-   the destination set is stored in AVP list. You can use
-   'ds_next_domain()' to use next address to achieve serial
-   forking to all possible destinations.
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
+   destination set is stored in AVP list. You can use 'ds_next_domain()'
+   to use next address to achieve serial forking to all possible
+   destinations.
 
    This function can be used from REQUEST_ROUTE.
 
 1.4.3.  ds_next_dst()
 
-   Takes the next destination address from the AVPs with id
-   'dst_avp_id' and sets the dst_uri (outbound proxy address).
+   Takes the next destination address from the AVPs with id 'dst_avp_id'
+   and sets the dst_uri (outbound proxy address).
 
    This function can be used from FAILURE_ROUTE.
 
 1.4.4.  ds_next_domain()
 
-   Takes the next destination address from the AVPs with id
-   'dst_avp_id' and sets the domain part of the request uri.
+   Takes the next destination address from the AVPs with id 'dst_avp_id'
+   and sets the domain part of the request uri.
 
    This function can be used from FAILURE_ROUTE.
 
 1.4.5.  ds_mark_dst()
 
-   Mark the last used address from destination set as inactive, in
-   order to be ingnored in the future. In this way it can be
-   implemented an automatic detection of failed gateways. When an
-   address is marked as inactive, it will be ignored by
-   'ds_select_dst' and 'ds_select_domain'.
+   Mark the last used address from destination set as inactive, in order
+   to be ingnored in the future. In this way it can be implemented an
+   automatic detection of failed gateways. When an address is marked as
+   inactive, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
 
    This function can be used from FAILURE_ROUTE.
 
 1.4.6.  ds_mark_dst("s")
 
    Mark the last used address from destination set as inactive
-   ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2").
-   With this function, an automatic detection of failed gateways
-   can be implemented. When an address is marked as inactive or
-   probing, it will be ignored by 'ds_select_dst' and
-   'ds_select_domain'.
+   ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2"). With this
+   function, an automatic detection of failed gateways can be implemented.
+   When an address is marked as inactive or probing, it will be ignored by
+   'ds_select_dst' and 'ds_select_domain'.
 
    possible parameters:
-     * "i", "I" or "0" - the last destination should be set to
-       inactive and will be ignored in future requests.
-     * "a", "A" or "1" - the last destination should be set to
-       active.
-     * "p", "P" or "2" - the last destination will be set to
-       probing. Note: You will need to call this function
-       "threshhold"-times, before it will be actually set to
-       probing.
+     * "i", "I" or "0" - the last destination should be set to inactive
+       and will be ignored in future requests.
+     * "a", "A" or "1" - the last destination should be set to active.
+     * "p", "P" or "2" - the last destination will be set to probing.
+       Note: You will need to call this function "threshhold"-times,
+       before it will be actually set to probing.
 
    This function can be used from FAILURE_ROUTE.
 
 1.4.7.  ds_is_from_list()
 
-   This function returns true, if the current request comes from a
-   host from the dispatcher-list; otherwise false.
+   This function returns true, if the current request comes from a host
+   from the dispatcher-list; otherwise false.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
 1.4.8.  ds_is_from_list("group")
 
-   This function returns true, if the current request comes from a
-   host in the given group of the dispatcher-list; otherwise
-   false.
+   This function returns true, if the current request comes from a host in
+   the given group of the dispatcher-list; otherwise false.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
@@ -557,8 +539,8 @@ ds_select_dst("1", "0");
 
 1.5.1.  ds_set_state
 
-   Sets the status for a destination address (can be use to mark
-   the destination as active or inactive).
+   Sets the status for a destination address (can be use to mark the
+   destination as active or inactive).
 
    Name: ds_set_state
 
@@ -604,13 +586,12 @@ ds_select_dst("1", "0");
 
 1.6.1. Destination List File
 
-   Each destination point must be on one line. First token is the
-   set id, followed by destination address. Optionally, the third
-   field can be flags value (1 - destination inactive, 2 -
-   destination in probing mod -- you can do bitwise OR to set both
-   flags). The set id must be an integer value. Destination
-   address must be a valid SIP URI. Empty lines or lines starting
-   with "#" are ignored.
+   Each destination point must be on one line. First token is the set id,
+   followed by destination address. Optionally, the third field can be
+   flags value (1 - destination inactive, 2 - destination in probing mod
+   -- you can do bitwise OR to set both flags). The set id must be an
+   integer value. Destination address must be a valid SIP URI. Empty lines
+   or lines starting with "#" are ignored.
 
    Example 1.24. dispatcher list file
 ...
@@ -689,18 +670,16 @@ Chapter 2. Frequently Asked Questions
 
        Does dispatcher provide a fair distribution?
 
-       There is no guarantee of that. You should do some measurements
-       to decide what distribution algorithm fits better in your
-       environment.
+       There is no guarantee of that. You should do some measurements to
+       decide what distribution algorithm fits better in your environment.
 
    2.2.
 
        Is dispatcher dialog stateful?
 
-       No. Dispatcher is stateless, although some distribution
-       algorithms are designed to select same destination for
-       subsequent requests of the same dialog (e.g., hashing the
-       call-id).
+       No. Dispatcher is stateless, although some distribution algorithms are
+       designed to select same destination for subsequent requests of the same
+       dialog (e.g., hashing the call-id).
 
    2.3.
 
@@ -712,17 +691,16 @@ Chapter 2. Frequently Asked Questions
 
        Where can I post a question about this module?
 
-       First at all check if your question was already answered on one
-       of our mailing lists:
+       First at all check if your question was already answered on one of our
+       mailing lists:
          * User Mailing List -
            http://lists.kamailio.org/cgi-bin/mailman/listinfo/users
          * Developer Mailing List -
            http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel
 
        E-mails regarding any stable version should be sent to
-       <[email protected]> and e-mail regarding development
-       versions or CVS snapshots should be send to
-       <[email protected]>.
+       <[email protected]> and e-mail regarding development versions or
+       CVS snapshots should be send to <[email protected]>.
 
        If you want to keep the mail private, send it to
        <[email protected]>.

modules_k/dispatcher/doc/Makefile

@@ -0,0 +1,40 @@
+#
+# The list of documents to build (without extensions)
+#
+DOCUMENTS = dispatcher
+
+#
+# The root directory containing Makefile.doc
+#
+ROOT_DIR=../../..
+
+#
+# Validate docbook documents before generating output
+# (may be slow)
+#
+#VALIDATE=1
+
+#
+# You can override the CSS used in generated
+# HTML documents here
+#
+#HTML_CSS=/style/docbook.css
+
+#
+# You can override the stylesheet used to generate
+# xhtml documents here
+#
+#XHTML_XSL=$(ROOT_DIR)/doc/stylesheets/xhtml.xsl
+
+#
+# You can override the stylesheet used to generate
+# plain text documents here
+#
+#TXT_XSL=$(XHTML_XSL)
+
+#
+# K documentation style
+#
+DOCBOOK_MODE=k
+
+include $(ROOT_DIR)/Makefile.doc

modules_k/dispatcher/doc/dispatcher.xml

@@ -9,7 +9,7 @@
 <!ENTITY dispatchercfg SYSTEM "dispatcher.cfg">
 
 <!-- Include general documentation entities -->
-<!ENTITY % docentities SYSTEM "../../../doc/entities.xml">
+<!ENTITY % docentities SYSTEM "../../../doc/kam_entities.xml">
 %docentities;
 
 ]>