Merge pull request #13 from alezzandro/master

dispatcher: fixing some misspelled words and adding support for custom number of successful probing requests

modules/dispatcher/README

@@ -22,13 +22,21 @@ Olle E. Johansson
 
    Edvina AB
 
-   Copyright © 2004 FhG FOKUS
+Edited by
+
+Alessandro Arrichiello
+
+   Hewlett Packard
 
-   Copyright © 2005 Voice Sistem
+   Copyright © 2004 FhG FOKUS
 
-   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+   Copyright © 2005 Voice Sistem
 
-   Copyright © 2014 Olle E. Johansson, Edvina AB
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+
+   Copyright © 2014 Olle E. Johansson, Edvina AB
+
+   Copyright © 2015 Alessandro Arrichiello, Hewlett Packard
      __________________________________________________________________
 
    Table of Contents
@@ -66,14 +74,15 @@ Olle E. Johansson
               3.21. ds_ping_from (string)
               3.22. ds_ping_interval (int)
               3.23. ds_probing_threshold (int)
-              3.24. ds_ping_reply_codes (string)
-              3.25. ds_probing_mode (int)
-              3.26. ds_hash_size (int)
-              3.27. ds_hash_expire (int)
-              3.28. ds_hash_initexpire (int)
-              3.29. ds_hash_check_interval (int)
-              3.30. outbound_proxy (str)
-              3.31. ds_default_socket (str)
+              3.24. ds_inactive_threshold (int)
+              3.25. ds_ping_reply_codes (string)
+              3.26. ds_probing_mode (int)
+              3.27. ds_hash_size (int)
+              3.28. ds_hash_expire (int)
+              3.29. ds_hash_initexpire (int)
+              3.30. ds_hash_check_interval (int)
+              3.31. outbound_proxy (str)
+              3.32. ds_default_socket (str)
 
         4. Functions
 
@@ -117,45 +126,46 @@ Olle E. Johansson
 
    List of Examples
 
-   1.1. Set the "list_file" parameter
-   1.2. Set "db_url" parameter
-   1.3. Set "table_name" parameter
-   1.4. Set "setid_col" parameter
-   1.5. Set "destination_col" parameter
-   1.6. Set "flags_col" parameter
-   1.7. Set "priority_col" parameter
-   1.8. Set the "force_dst" parameter
-   1.9. Set the "flags" parameter
-   1.10. Set the "use_default" parameter
-   1.11. Set the "dst_avp" parameter
-   1.12. Set the "grp_avp" parameter
-   1.13. Set the "cnt_avp" parameter
-   1.14. Set the "dstid_avp" parameter
-   1.15. Set the "attrs_avp" parameter
-   1.16. Set the "sock_avp" parameter
+   1.1. Set the “list_file� parameter
+   1.2. Set “db_url� parameter
+   1.3. Set “table_name� parameter
+   1.4. Set “setid_col� parameter
+   1.5. Set “destination_col� parameter
+   1.6. Set “flags_col� parameter
+   1.7. Set “priority_col� parameter
+   1.8. Set the “force_dst� parameter
+   1.9. Set the “flags� parameter
+   1.10. Set the “use_default� parameter
+   1.11. Set the “dst_avp� parameter
+   1.12. Set the “grp_avp� parameter
+   1.13. Set the “cnt_avp� parameter
+   1.14. Set the “dstid_avp� parameter
+   1.15. Set the “attrs_avp� parameter
+   1.16. Set the “sock_avp� parameter
    1.17. Use $avp(i:273) for hashing:
    1.18. Use combination of PVs for hashing:
-   1.19. Set the "setid_pvname" parameter
-   1.20. Set the "attrs_pvname" parameter
-   1.21. Set the "ds_ping_method" parameter
-   1.22. Set the "ds_ping_from" parameter
-   1.23. Set the "ds_ping_interval" parameter
-   1.24. Set the "ds_probing_threshhold" parameter
-   1.25. Set the "ds_ping_reply_codes" parameter
-   1.26. Set the "ds_probing_mode" parameter
-   1.27. Set the "ds_hash_size" parameter
-   1.28. Set the "ds_hash_expire" parameter
-   1.29. Set the "ds_hash_initexpire" parameter
-   1.30. Set the "ds_hash_check_interval" parameter
-   1.31. Set the "outbound_proxy" parameter
-   1.32. Set the "ds_default_socket" parameter
-   1.33. ds_select_dst usage
-   1.34. ds_mark_dst usage
-   1.35. ds_list_exist usage
-   1.36. ds_mark_dst usage
-   1.37. ds_load_unset usage
-   1.38. dispatcher list file
-   1.39. Kamailio config script - sample dispatcher usage
+   1.19. Set the “setid_pvname� parameter
+   1.20. Set the “attrs_pvname� parameter
+   1.21. Set the “ds_ping_method� parameter
+   1.22. Set the “ds_ping_from� parameter
+   1.23. Set the “ds_ping_interval� parameter
+   1.24. Set the “ds_probing_threshold� parameter
+   1.25. Set the “ds_inactive_threshold� parameter
+   1.26. Set the “ds_ping_reply_codes� parameter
+   1.27. Set the “ds_probing_mode� parameter
+   1.28. Set the “ds_hash_size� parameter
+   1.29. Set the “ds_hash_expire� parameter
+   1.30. Set the “ds_hash_initexpire� parameter
+   1.31. Set the “ds_hash_check_interval� parameter
+   1.32. Set the “outbound_proxy� parameter
+   1.33. Set the “ds_default_socket� parameter
+   1.34. ds_select_dst usage
+   1.35. ds_mark_dst usage
+   1.36. ds_list_exist usage
+   1.37. ds_mark_dst usage
+   1.38. ds_load_unset usage
+   1.39. dispatcher list file
+   1.40. Kamailio config script - sample dispatcher usage
 
 Chapter 1. Admin Guide
 
@@ -192,14 +202,15 @@ Chapter 1. Admin Guide
         3.21. ds_ping_from (string)
         3.22. ds_ping_interval (int)
         3.23. ds_probing_threshold (int)
-        3.24. ds_ping_reply_codes (string)
-        3.25. ds_probing_mode (int)
-        3.26. ds_hash_size (int)
-        3.27. ds_hash_expire (int)
-        3.28. ds_hash_initexpire (int)
-        3.29. ds_hash_check_interval (int)
-        3.30. outbound_proxy (str)
-        3.31. ds_default_socket (str)
+        3.24. ds_inactive_threshold (int)
+        3.25. ds_ping_reply_codes (string)
+        3.26. ds_probing_mode (int)
+        3.27. ds_hash_size (int)
+        3.28. ds_hash_expire (int)
+        3.29. ds_hash_initexpire (int)
+        3.30. ds_hash_check_interval (int)
+        3.31. outbound_proxy (str)
+        3.32. ds_default_socket (str)
 
    4. Functions
 
@@ -298,23 +309,24 @@ Chapter 1. Admin Guide
    3.21. ds_ping_from (string)
    3.22. ds_ping_interval (int)
    3.23. ds_probing_threshold (int)
-   3.24. ds_ping_reply_codes (string)
-   3.25. ds_probing_mode (int)
-   3.26. ds_hash_size (int)
-   3.27. ds_hash_expire (int)
-   3.28. ds_hash_initexpire (int)
-   3.29. ds_hash_check_interval (int)
-   3.30. outbound_proxy (str)
-   3.31. ds_default_socket (str)
+   3.24. ds_inactive_threshold (int)
+   3.25. ds_ping_reply_codes (string)
+   3.26. ds_probing_mode (int)
+   3.27. ds_hash_size (int)
+   3.28. ds_hash_expire (int)
+   3.29. ds_hash_initexpire (int)
+   3.30. ds_hash_check_interval (int)
+   3.31. outbound_proxy (str)
+   3.32. ds_default_socket (str)
 
 3.1. list_file (string)
 
    Path to the file with destination sets.
 
-   Default value is "/etc/kamailio/dispatcher.list" or
-   "/usr/local/etc/kamailio/dispatcher.list".
+   Default value is “/etc/kamailio/dispatcher.list� or
+   “/usr/local/etc/kamailio/dispatcher.list�.
 
-   Example 1.1. Set the "list_file" parameter
+   Example 1.1. Set the “list_file� parameter
 ...
 modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
 ...
@@ -324,9 +336,9 @@ modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
    If you want to load the sets of gateways from the database you must set
    this parameter.
 
-   Default value is "NULL" (disable DB support).
+   Default value is “NULL� (disable DB support).
 
-   Example 1.2. Set "db_url" parameter
+   Example 1.2. Set “db_url� parameter
 ...
 modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
 ...
@@ -336,9 +348,9 @@ modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
    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".
+   Default value is “dispatcher�.
 
-   Example 1.3. Set "table_name" parameter
+   Example 1.3. Set “table_name� parameter
 ...
 modparam("dispatcher", "table_name", "my_dispatcher")
 ...
@@ -347,9 +359,9 @@ modparam("dispatcher", "table_name", "my_dispatcher")
 
    The column's name in the database storing the gateway's group id.
 
-   Default value is "setid".
+   Default value is “setid�.
 
-   Example 1.4. Set "setid_col" parameter
+   Example 1.4. Set “setid_col� parameter
 ...
 modparam("dispatcher", "setid_col", "groupid")
 ...
@@ -358,9 +370,9 @@ modparam("dispatcher", "setid_col", "groupid")
 
    The column's name in the database storing the destination sip URI.
 
-   Default value is "destination".
+   Default value is “destination�.
 
-   Example 1.5. Set "destination_col" parameter
+   Example 1.5. Set “destination_col� parameter
 ...
 modparam("dispatcher", "destination_col", "uri")
 ...
@@ -370,9 +382,9 @@ modparam("dispatcher", "destination_col", "uri")
    The column's name in the database storing the flags for the destination
    URI.
 
-   Default value is "flags".
+   Default value is “flags�.
 
-   Example 1.6. Set "flags_col" parameter
+   Example 1.6. Set “flags_col� parameter
 ...
 modparam("dispatcher", "flags_col", "dstflags")
 ...
@@ -382,9 +394,9 @@ modparam("dispatcher", "flags_col", "dstflags")
    The column's name in the database storing the priority for destination
    URI.
 
-   Default value is "priority".
+   Default value is “priority�.
 
-   Example 1.7. Set "priority_col" parameter
+   Example 1.7. Set “priority_col� parameter
 ...
 modparam("dispatcher", "priority_col", "dstpriority")
 ...
@@ -395,9 +407,9 @@ modparam("dispatcher", "priority_col", "dstpriority")
    when that is already set. If set to 0, will return error when the
    destination address is already set.
 
-   Default value is "1".
+   Default value is “1�.
 
-   Example 1.8. Set the "force_dst" parameter
+   Example 1.8. Set the “force_dst� parameter
 ...
 modparam("dispatcher", "force_dst", 1)
 ...
@@ -416,9 +428,9 @@ modparam("dispatcher", "force_dst", 1)
    destination set in the AVP, and use these AVPs to contact next address
    if the current-tried destination fails.
 
-   Default value is "0".
+   Default value is “0�.
 
-   Example 1.9. Set the "flags" parameter
+   Example 1.9. Set the “flags� parameter
  ...
  modparam("dispatcher", "flags", 3)
  ...
@@ -430,9 +442,9 @@ modparam("dispatcher", "force_dst", 1)
    useful when wanting to send the call to an anouncement server saying:
    "the gateways are full, try later".
 
-   Default value is "0".
+   Default value is “0�.
 
-   Example 1.10. Set the "use_default" parameter
+   Example 1.10. Set the “use_default� parameter
  ...
  modparam("dispatcher", "use_default", 1)
  ...
@@ -450,9 +462,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is "null" - don't add AVPs.
+   Default value is “null� - don't add AVPs.
 
-   Example 1.11. Set the "dst_avp" parameter
+   Example 1.11. Set the “dst_avp� parameter
  ...
  modparam("dispatcher", "dst_avp", "$avp(dsdst)")
  ...
@@ -466,9 +478,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is "null" - don't add AVP.
+   Default value is “null� - don't add AVP.
 
-   Example 1.12. Set the "grp_avp" parameter
+   Example 1.12. Set the “grp_avp� parameter
  ...
  modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
  ...
@@ -482,9 +494,9 @@ Note
 
    You must set this parameter if you want to do load balancing fail over.
 
-   Default value is "null" - don't add AVP.
+   Default value is “null� - don't add AVP.
 
-   Example 1.13. Set the "cnt_avp" parameter
+   Example 1.13. Set the “cnt_avp� parameter
  ...
  modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
  ...
@@ -499,9 +511,9 @@ Note
    You must set this parameter if you want to do load balancing on call
    load (alg 10).
 
-   Default value is "null" - don't add AVP.
+   Default value is “null� - don't add AVP.
 
-   Example 1.14. Set the "dstid_avp" parameter
+   Example 1.14. Set the “dstid_avp� parameter
  ...
  modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
  ...
@@ -512,9 +524,9 @@ Note
 
 Note
 
-   Default value is "null" - don't add AVP.
+   Default value is “null� - don't add AVP.
 
-   Example 1.15. Set the "attrs_avp" parameter
+   Example 1.15. Set the “attrs_avp� parameter
  ...
  modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
  ...
@@ -529,9 +541,9 @@ Note
    If you want to do load balancing fail over, you have to set this
    parameter to use the correct socket for each gateway.
 
-   Default value is "null" - don't add AVPs.
+   Default value is “null� - don't add AVPs.
 
-   Example 1.16. Set the "sock_avp" parameter
+   Example 1.16. Set the “sock_avp� parameter
  ...
  modparam("dispatcher", "sock_avp", "$avp(dssocket)")
  ...
@@ -545,7 +557,7 @@ Note
    You must set this parameter if you want do hashing over custom message
    parts.
 
-   Default value is "null" - disabled.
+   Default value is “null� - disabled.
 
    Example 1.17. Use $avp(i:273) for hashing:
  ...
@@ -562,9 +574,9 @@ Note
    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.
+   Default value is “null� - don't set PV.
 
-   Example 1.19. Set the "setid_pvname" parameter
+   Example 1.19. Set the “setid_pvname� parameter
  ...
  modparam("dispatcher", "setid_pvname", "$var(setid)")
  ...
@@ -574,9 +586,9 @@ Note
    The name of the PV where to store the attributes of matching address
    when calling ds_is_from_list().
 
-   Default value is "null" - don't set PV.
+   Default value is “null� - don't set PV.
 
-   Example 1.20. Set the "attrs_pvname" parameter
+   Example 1.20. Set the “attrs_pvname� parameter
  ...
  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
  ...
@@ -587,9 +599,9 @@ Note
    the gateways. Pinging gateways feature depends on ds_ping_interval
    parameter.
 
-   Default value is "OPTIONS".
+   Default value is “OPTIONS�.
 
-   Example 1.21. Set the "ds_ping_method" parameter
+   Example 1.21. Set the “ds_ping_method� parameter
  ...
  modparam("dispatcher", "ds_ping_method", "INFO")
  ...
@@ -600,9 +612,9 @@ Note
    to the failed gateways. This method is only available, if compiled with
    the probing of failed gateways enabled.
 
-   Default value is "sip:dispatcher@localhost".
+   Default value is “sip:dispatcher@localhost�.
 
-   Example 1.22. Set the "ds_ping_from" parameter
+   Example 1.22. Set the “ds_ping_from� parameter
  ...
  modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
  ...
@@ -612,11 +624,11 @@ Note
    With this parameter you can define the interval for sending a request
    to a gateway marked as inactive upon a failed request routing to it.
    This parameter is only used, when the TM-Module is loaded. If set to
-   "0", the pinging of inactive gateway is disabled.
+   “0�, the pinging of inactive gateway is disabled.
 
-   Default value is "0".
+   Default value is “0�.
 
-   Example 1.23. Set the "ds_ping_interval" parameter
+   Example 1.23. Set the “ds_ping_interval� parameter
  ...
  modparam("dispatcher", "ds_ping_interval", 30)
  ...
@@ -630,14 +642,29 @@ Note
    The number of attempts can be set with this parameter. This parameter
    can be modified via ser config framework.
 
-   Default value is "1" (set inactive with first failure).
+   Default value is “1� (set inactive with first failure).
+
+   Example 1.24. Set the “ds_probing_threshold� parameter
+ ...
+ modparam("dispatcher", "ds_probing_threshold", 10)
+ ...
+
+3.24. ds_inactive_threshold (int)
+
+   If you want to set a gateway into active mode (after being inactive),
+   there can be a specific number of successful requests until it will
+   change from "inactive" to "active". The number of attempts can be set
+   with this parameter. This parameter can be modified via ser config
+   framework.
+
+   Default value is “1� (set active with first success).
 
-   Example 1.24. Set the "ds_probing_threshhold" parameter
+   Example 1.25. Set the “ds_inactive_threshold� parameter
  ...
- modparam("dispatcher", "ds_probing_threshhold", 10)
+ modparam("dispatcher", "ds_inactive_threshold", 10)
  ...
 
-3.24. ds_ping_reply_codes (string)
+3.25. ds_ping_reply_codes (string)
 
    This parameter defines the valid response codes, which are accepted as
    a valid reply to the PING-Method. It is a list separated by colons,
@@ -647,15 +674,15 @@ Note
    valid response). This parameter can be modified via ser config
    framework.
 
-   Default value is "" (only 200 OK is accepted).
+   Default value is “� (only 200 OK is accepted).
 
-   Example 1.25. Set the "ds_ping_reply_codes" parameter
+   Example 1.26. Set the “ds_ping_reply_codes� parameter
  ...
- modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
-3")
+ modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class
+=3")
  ...
 
-3.25. ds_probing_mode (int)
+3.26. 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
@@ -663,76 +690,76 @@ Note
    probing mode set are tested. If set to 1 and there is a failure of
    keepalive to an active gateway, then it is set to TRYING state.
 
-   Default value is "0".
+   Default value is “0�.
 
-   Example 1.26. Set the "ds_probing_mode" parameter
+   Example 1.27. Set the “ds_probing_mode� parameter
  ...
  modparam("dispatcher", "ds_probing_mode", 1)
  ...
 
-3.26. ds_hash_size (int)
+3.27. ds_hash_size (int)
 
    The value to be used as power of two to set the number of slots to hash
    table storing data for call load dispatching (e.g., value 8 will create
    a hash table with 256 slots). It must be greater than 0 to enable call
    load dispatching feature (alg 10).
 
-   Default value is "0".
+   Default value is “0�.
 
-   Example 1.27. Set the "ds_hash_size" parameter
+   Example 1.28. Set the “ds_hash_size� parameter
  ...
  modparam("dispatcher", "ds_hash_size", 9)
  ...
 
-3.27. ds_hash_expire (int)
+3.28. ds_hash_expire (int)
 
    Expiration time in seconds to remove the load on a destination if no
    BYE was received meanwhile.
 
-   Default value is "7200".
+   Default value is “7200�.
 
-   Example 1.28. Set the "ds_hash_expire" parameter
+   Example 1.29. Set the “ds_hash_expire� parameter
  ...
  modparam("dispatcher", "ds_hash_expire", 3600)
  ...
 
-3.28. ds_hash_initexpire (int)
+3.29. ds_hash_initexpire (int)
 
    Expiration time in seconds to remove the load on a destination if no
    200 for INVITE was received meanwhile and state updated with
    ds_load_update().
 
-   Default value is "7200".
+   Default value is “7200�.
 
-   Example 1.29. Set the "ds_hash_initexpire" parameter
+   Example 1.30. Set the “ds_hash_initexpire� parameter
  ...
  modparam("dispatcher", "ds_hash_initexpire", 60)
  ...
 
-3.29. ds_hash_check_interval (int)
+3.30. ds_hash_check_interval (int)
 
    Time interval in seconds to scan internal hash table with call load
    dispatching data for expired items.
 
-   Default value is "30".
+   Default value is “30�.
 
-   Example 1.30. Set the "ds_hash_check_interval" parameter
+   Example 1.31. Set the “ds_hash_check_interval� parameter
  ...
  modparam("dispatcher", "ds_hash_check_interval", 60)
  ...
 
-3.30. outbound_proxy (str)
+3.31. outbound_proxy (str)
 
    SIP URI of outbound proxy to be used when sending pings.
 
    By default no outbound proxy is defined.
 
-   Example 1.31. Set the "outbound_proxy" parameter
+   Example 1.32. Set the “outbound_proxy� parameter
  ...
  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
  ...
 
-3.31. ds_default_socket (str)
+3.32. ds_default_socket (str)
 
    Default socket to be used for sending pings and dispatching requests
    when a gateway has no send socket configured.
@@ -740,7 +767,7 @@ Note
    By default no default socket is defined, the first configuration script
    listen directive is used.
 
-   Example 1.32. Set the "ds_default_socket" parameter
+   Example 1.33. Set the “ds_default_socket� parameter
  ...
  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
  ...
@@ -757,7 +784,7 @@ Note
    4.8. ds_load_update()
    4.9. ds_load_unset()
 
-4.1. ds_select_dst(set, alg[, limit])
+4.1.  ds_select_dst(set, alg[, limit])
 
    The method selects a destination from addresses set. It returns true if
    a new destination is set. The selected address is set to dst_uri field
@@ -776,21 +803,21 @@ Note
        be an integer or a variable holding an integer.
      * alg - the algorithm used to select the destination address. The
        parameter can be an integer or a variable holding an interger.
-          + "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
+          + “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.
-          + "6" - random (using rand()).
-          + "7" - hash over the content of PVs string. Note: This works
+          + “6� - random (using rand()).
+          + “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).
-          + "9" - use weight based load distribution. You have to set the
+          + “8� - use first destination (good for failover).
+          + “9� - use weight based load distribution. You have to set the
             attribute 'weight' per each address in destination set.
-          + "10" - use call load distribution. You have to set the
+          + “10� - use call load distribution. You have to set the
             attribute 'duid' (as an unique string id) per each address in
             destination set. Also, you must set parameters 'dstid_avp' and
             'ds_hash_size'.
@@ -805,7 +832,7 @@ Note
             on each address can change.
             This algorithm can be used only for dispatching INVITE
             requests as it is the only SIP method creating a SIP call.
-          + "X" - if the algorithm is not implemented, the first entry in
+          + “X� - if the algorithm is not implemented, the first entry in
             set is chosen.
      * limit - the maximum number of items to be stored in AVP list for
        further failovers (the first selected destination and default
@@ -818,7 +845,7 @@ Note
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.33. ds_select_dst usage
+   Example 1.34. ds_select_dst usage
 ...
 ds_select_dst("1", "0");
 ...
@@ -828,7 +855,7 @@ ds_select_dst("1", "$var(a)");
 ds_select_dst("1", "4", "3");
 ...
 
-4.2. ds_select_domain(set, alg[, limit])
+4.2.  ds_select_domain(set, alg[, limit])
 
    The method selects a destination from addresses set and rewrites the
    host and port from R-URI. The parameters have same meaning as for
@@ -841,21 +868,21 @@ ds_select_dst("1", "4", "3");
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.3. ds_next_dst()
+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).
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.4. ds_next_domain()
+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.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-4.5. ds_mark_dst([state])
+4.5.  ds_mark_dst([state])
 
    Mark the last used address from destination set as inactive ("i"/"I"),
    active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T"). Apart of
@@ -882,7 +909,7 @@ ds_select_dst("1", "4", "3");
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 
-   Example 1.34. ds_mark_dst usage
+   Example 1.35. ds_mark_dst usage
 ...
 failure_route[tryagain] {
 ...
@@ -892,21 +919,21 @@ failure_route[tryagain] {
 }
 ...
 
-4.6. ds_list_exist(groupid)
+4.6.  ds_list_exist(groupid)
 
    Check if a specific group is defined in dispatcher list or database.
      * groupid - A group ID to check.
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.35. ds_list_exist usage
+   Example 1.36. ds_list_exist usage
 ...
 if(ds_list_exist("10")) {
     ...
 }
 ...
 
-4.7. ds_is_from_list([groupid [, mode [, uri] ] ])
+4.7.  ds_is_from_list([groupid [, mode [, uri] ] ])
 
    This function returns true, if there is a match of source address or
    uri with an address in the given group of the dispatcher-list;
@@ -942,7 +969,7 @@ if(ds_list_exist("10")) {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.36. ds_mark_dst usage
+   Example 1.37. ds_mark_dst usage
 ...
 if(ds_is_from_list()) {
     ...
@@ -955,7 +982,7 @@ if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) {
 }
 ...
 
-4.8. ds_load_update()
+4.8.  ds_load_update()
 
    Updates the load state:
      * if it is a BYE or CANCEL - remove the load from destination address
@@ -966,14 +993,14 @@ if(ds_is_from_list("10", "sip:127.0.0.1:5080", "3")) {
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-4.9. ds_load_unset()
+4.9.  ds_load_unset()
 
    Remove the call load for the destination that routed the call.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE and ONREPLY_ROUTE.
 
-   Example 1.37. ds_load_unset usage
+   Example 1.38. ds_load_unset usage
 ...
 route {
     ...
@@ -1003,7 +1030,7 @@ onreply_route {
    5.2. ds_list
    5.3. ds_reload
 
-5.1. ds_set_state
+5.1.  ds_set_state
 
    Sets the status for a destination address (can be use to mark the
    destination as active or inactive).
@@ -1012,11 +1039,11 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + "a": active
-          + "i": inactive
-          + "t": trying
-          + "d": disabled
-       The states "a", "i" or "t" can be followed by "p" to set probing
+          + “a�: active
+          + “i�: inactive
+          + “t�: trying
+          + “d�: disabled
+       The states “a�, “i� or “t� can be followed by “p� to set probing
        mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -1028,7 +1055,7 @@ onreply_route {
                 _address_
                 _empty_line_
 
-5.2. ds_list
+5.2.  ds_list
 
    It lists the groups and included destinations.
 
@@ -1040,7 +1067,7 @@ onreply_route {
                 :ds_list:_reply_fifo_file_
                 _empty_line_
 
-5.3. ds_reload
+5.3.  ds_reload
 
    It reloads the groups and included destinations. For algorithm 10 (call
    load distribution), old internal list of active calls is destroyed
@@ -1060,7 +1087,7 @@ onreply_route {
    6.2. dispatcher.list
    6.3. dispatcher.reload
 
-6.1. dispatcher.set_state
+6.1.  dispatcher.set_state
 
    Sets the state for a destination address (can be use to mark the
    destination as active or inactive).
@@ -1069,11 +1096,11 @@ onreply_route {
 
    Parameters:
      * _state_ : state of the destination address
-          + "a": active
-          + "i": inactive
-          + "t": trying
-          + "d": disabled
-       The states "a", "i" or "t" can be followed by "p" to set probing
+          + “a�: active
+          + “i�: inactive
+          + “t�: trying
+          + “d�: disabled
+       The states “a�, “i� or “t� can be followed by “p� to set probing
        mode (e.g. 'ap', 'ip' or 'tp').
      * _group_: destination group id
      * _address_: address of the destination in the _group_
@@ -1084,7 +1111,7 @@ onreply_route {
 kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
 ...
 
-6.2. dispatcher.list
+6.2.  dispatcher.list
 
    Lists the groups and included destinations.
 
@@ -1095,7 +1122,7 @@ kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
    Example:
                 kamcmd dispatcher.list
 
-6.3. dispatcher.reload
+6.3.  dispatcher.reload
 
    Reloads the groups and included destinations. The command is disabled
    for call load based dispatching (algorithm 10) since removal of
@@ -1166,15 +1193,15 @@ setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
    For database, each element of a line resides in a different column.
    Next is a dispatcher.list file example:
 
-   Example 1.38. dispatcher list file
+   Example 1.39. dispatcher list file
 ...
 # $Id$
 # dispatcher destination sets
 #
 
 # line format
-# setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(st
-r,opt)
+# setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(s
+tr,opt)
 
 # proxies
 2 sip:127.0.0.1:5080
@@ -1191,7 +1218,7 @@ r,opt)
 
    Next picture shows a sample usage of the dispatcher module.
 
-   Example 1.39. Kamailio config script - sample dispatcher usage
+   Example 1.40. Kamailio config script - sample dispatcher usage
 ...
 #!KAMAILIO
 #
@@ -1297,8 +1324,8 @@ modparam("rr", "append_fromtag", 0)
 modparam("acc", "log_flag", 1)
 modparam("acc", "failed_transaction_flag", 3)
 modparam("acc", "log_extra",
-        "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd;s
-rc_ip=$si")
+        "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd;
+src_ip=$si")
 
 # ----- tm params -----
 modparam("tm", "fr_timer", 2000)
@@ -1408,13 +1435,13 @@ route[WITHINDLG] {
                         if ( is_method("ACK") ) {
                                 if ( t_check_trans() ) {
                                         # non loose-route, but stateful ACK;
-                                        # must be ACK after a 487 or e.g. 404 fr
-om upstream server
+                                        # must be ACK after a 487 or e.g. 404 f
+rom upstream server
                                         t_relay();
                                         exit;
                                 } else {
-                                        # ACK without matching transaction ... i
-gnore and discard.
+                                        # ACK without matching transaction ...
+ignore and discard.
                                         exit;
                                 }
                         }
@@ -1482,7 +1509,7 @@ failure_route[RTF_DISPATCH] {
    8.1. dispatcher:dst-down
    8.2. dispatcher:dst-up
 
-8.1. dispatcher:dst-down
+8.1.  dispatcher:dst-down
 
    When defined, the module calls event_route[dispatcher:ds-down] when a
    destination goes down (becomes probing). A typical use case is to
@@ -1493,7 +1520,7 @@ event_route[dispatcher:dst-down] {
 }
 ...
 
-8.2. dispatcher:dst-up
+8.2.  dispatcher:dst-up
 
    When defined, the module calls event_route[dispatcher:ds-up] when a
    destination that was previously down (probing) comes up. A typical use

modules/dispatcher/config.c

@@ -31,15 +31,18 @@
 #include "config.h"
 
 struct cfg_group_dispatcher	default_dispatcher_cfg = {
-		3,	/* Probing threshhold */	
+		1,	/* Probing threshold */	
+		1,      /* Inactive threshold */
 		{0,0}	/* reply codes */
 	    };
 
 void	*dispatcher_cfg = &default_dispatcher_cfg;
 
 cfg_def_t	dispatcher_cfg_def[] = {
-	{"probing_threshhold",		CFG_VAR_INT | CFG_ATOMIC, 	0, 0, 0, 0,
+	{"probing_threshold",		CFG_VAR_INT | CFG_ATOMIC, 	0, 0, 0, 0,
 		"Number of failed requests, before a destination is set to probing."},
+	{"inactive_threshold",           CFG_VAR_INT | CFG_ATOMIC,       0, 0, 0, 0,
+                "Number of successful requests, before a destination is set to active."},
 	{"ping_reply_codes",		CFG_VAR_STR | CFG_CB_ONLY_ONCE ,			0, 0, 0, ds_ping_reply_codes_update,
 		"Additional, valid reply codes for the OPTIONS Pinger. Default is \"\""},
 	{0, 0, 0, 0, 0, 0}

modules/dispatcher/config.h

@@ -27,7 +27,8 @@
 #include "../../str.h"
 
 struct cfg_group_dispatcher {
-	int probing_threshhold;
+	int probing_threshold;
+	int inactive_threshold;
 	str ds_ping_reply_codes_str;
 };
 

modules/dispatcher/dispatch.c

@@ -38,6 +38,8 @@
  * 2007-07-18  removed index stuff
  * 			   added DB support to load/reload data(ancuta)
  * 2007-09-17  added list-file support for reload data (carstenbock)
+ * 2014-12-23  Corrected misspelled words in some variables' name (alezzandro)
+ * 2014-12-23  Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro)
  */
 
 /*! \file
@@ -2187,12 +2189,49 @@ int ds_mark_dst(struct sip_msg *msg, int state)
 }
 
 /**
- *
+ * Get state for given destination
+ */
+int ds_get_state(int group, str *address)
+{
+	int i=0;
+	int state = 0;
+	ds_set_t *idx = NULL;
+
+	if(_ds_list==NULL || _ds_list_nr<=0)
+	{
+		LM_ERR("the list is null\n");
+		return -1;
+	}
+
+	/* get the index of the set */
+	if(ds_get_index(group, &idx)!=0)
+	{
+		LM_ERR("destination set [%d] not found\n", group);
+		return -1;
+	}
+
+	while(i<idx->nr)
+	{
+		if(idx->dlist[i].uri.len==address->len
+				&& strncasecmp(idx->dlist[i].uri.s, address->s,
+					address->len)==0)
+		{
+			/* destination address found */
+			state = idx->dlist[i].flags;
+		}
+		i++;
+	}
+	return state;
+}
+
+/**
+ * Update destionation's state
  */
 int ds_update_state(sip_msg_t *msg, int group, str *address, int state)
 {
 	int i=0;
 	int old_state = 0;
+	int init_state = 0;
 	ds_set_t *idx = NULL;
 
 	if(_ds_list==NULL || _ds_list_nr<=0)
@@ -2219,7 +2258,10 @@ int ds_update_state(sip_msg_t *msg, int group, str *address, int state)
 
 			/* reset the bits used for states */
 			idx->dlist[i].flags &= ~(DS_STATES_ALL);
-
+			
+			/* we need the initial state for inactive counter */
+			init_state = state;
+			
 			if((state & DS_TRYING_DST) && (old_state & DS_INACTIVE_DST))
 			{
 				/* old state is inactive, new state is trying => keep it inactive
@@ -2235,18 +2277,33 @@ int ds_update_state(sip_msg_t *msg, int group, str *address, int state)
 			} else {
 				idx->dlist[i].flags |= state;
 			}
-
+			
 			if(state & DS_TRYING_DST)
 			{
-				idx->dlist[i].failure_count++;
-				if (idx->dlist[i].failure_count >= probing_threshhold)
+				idx->dlist[i].message_count++;
+				/* Destination is not replying.. Increasing failure counter */
+				if (idx->dlist[i].message_count >= probing_threshold)
 				{
+					/* Destionation has too much lost messages.. Bringing it to inactive state */
 					idx->dlist[i].flags &= ~DS_TRYING_DST;
 					idx->dlist[i].flags |= DS_INACTIVE_DST;
-					idx->dlist[i].failure_count = 0;
+					idx->dlist[i].message_count = 0;
 				}
 			} else {
-				idx->dlist[i].failure_count = 0;
+				if(!(init_state & DS_TRYING_DST) && (old_state & DS_INACTIVE_DST)){
+					idx->dlist[i].message_count++;
+					/* Destination was inactive but it is just replying.. Increasing successful counter */
+					if (idx->dlist[i].message_count < inactive_threshold)
+					{
+						/* Destination has not enough successful replies.. Leaving it into inactive state */
+						idx->dlist[i].flags |= DS_INACTIVE_DST;
+					}else{
+						/* Destination has enough replied messages.. Bringing it to active state */
+						idx->dlist[i].message_count = 0;
+					}
+				}else{ 
+					idx->dlist[i].message_count = 0;
+				}
 			}
 
 			if (!ds_skip_dst(old_state) && ds_skip_dst(idx->dlist[i].flags))
@@ -2375,10 +2432,10 @@ int ds_print_list(FILE *fout)
 			else if (list->dlist[j].flags&DS_TRYING_DST) {
 				fprintf(fout, "    Trying");
 				/* print the tries for this host. */
-				if (list->dlist[j].failure_count > 0) {
+				if (list->dlist[j].message_count > 0) {
 					fprintf(fout, " (Fail %d/%d)",
-							list->dlist[j].failure_count,
-							probing_threshhold);
+							list->dlist[j].message_count,
+							probing_threshold);
 				} else {
 					fprintf(fout, "           ");
 				}
@@ -2607,7 +2664,8 @@ static void ds_options_callback( struct cell *t, int type,
 		state = 0;
 		if (ds_probing_mode==DS_PROBE_ALL)
 			state |= DS_PROBING_DST;
-		if (ds_update_state(fmsg, group, &uri, state) != 0)
+		/* Check if in the meantime someone disabled the target through RPC or MI */
+		if (!(ds_get_state(group, &uri) & DS_DISABLED_DST) && ds_update_state(fmsg, group, &uri, state) != 0)
 		{
 			LM_ERR("Setting the state failed (%.*s, group %d)\n", uri.len,
 					uri.s, group);
@@ -2616,8 +2674,8 @@ static void ds_options_callback( struct cell *t, int type,
 		state = DS_TRYING_DST;
 		if (ds_probing_mode!=DS_PROBE_NONE)
 			state |= DS_PROBING_DST;
-
-		if (ds_update_state(fmsg, group, &uri, state) != 0)
+		/* Check if in the meantime someone disabled the target through RPC or MI */
+		if (!(ds_get_state(group, &uri) & DS_DISABLED_DST) && ds_update_state(fmsg, group, &uri, state) != 0)
 		{
 			LM_ERR("Setting the probing state failed (%.*s, group %d)\n",
 					uri.len, uri.s, group);

modules/dispatcher/dispatch.h

@@ -30,6 +30,8 @@
  *		re-enabling of destinations
  * 2007-05-08  Ported the changes to SVN-Trunk and renamed ds_is_domain
  *		to ds_is_from_list.
+ * 2014-12-23  Corrected misspelled words in some variables' name (alezzandro) 
+ * 2014-12-23  Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro)
  */
 
 /*! \file
@@ -100,8 +102,10 @@ extern pv_spec_t ds_attrs_pv;
 extern struct tm_binds tmb;
 extern str ds_ping_method;
 extern str ds_ping_from;
-extern int probing_threshhold; /*!< number of failed requests,
-								 before a destination is taken into probing */ 
+extern int probing_threshold; /*!< number of failed requests,
+								before a destination is taken into probing */
+extern int inactive_threshold; /*!< number of successful requests, 
+								before a destination is taken into active */
 extern int ds_probing_mode;
 extern str ds_outbound_proxy;
 extern str ds_default_socket;
@@ -172,7 +176,7 @@ typedef struct _ds_dest
 	struct ip_addr ip_address; 	/*!< IP-Address of the entry */
 	unsigned short int port; 	/*!< Port of the URI */
 	unsigned short int proto; 	/*!< Protocol of the URI */
-	int failure_count;
+	int message_count;
 	struct _ds_dest *next;
 } ds_dest_t;
 

modules/dispatcher/dispatcher.c

@@ -34,6 +34,8 @@
  * 2007-07-18  Added support for load/reload groups from DB 
  * 			   reload triggered from ds_reload MI_Command (ancuta)
  * 2014-12-12  Added "ds_list_exist" function
+ * 2014-12-23  Corrected misspelled words in some variables' name (alezzandro)
+ * 2014-12-23  Added support for custom number of successful probing requests before moving a destination from 'inactive' to 'active' state (alezzandro)
  */
 
 /*! \file
@@ -108,7 +110,7 @@ unsigned short sock_avp_type;
 
 pv_elem_t * hash_param_model = NULL;
 
-int probing_threshhold = 1; /* number of failed requests, before a destination
+int probing_threshold = 1; /* number of failed requests, before a destination
 							   is taken into probing */
 str ds_ping_method = str_init("OPTIONS");
 str ds_ping_from   = str_init("sip:dispatcher@localhost");
@@ -240,7 +242,7 @@ static param_export_t params[]={
 	{"hash_pvar",       PARAM_STR, &hash_pvar_param},
 	{"setid_pvname",    PARAM_STR, &ds_setid_pvname},
 	{"attrs_pvname",    PARAM_STR, &ds_attrs_pvname},
-	{"ds_probing_threshhold", INT_PARAM, &probing_threshhold},
+	{"ds_probing_threshold", INT_PARAM, &probing_threshold},
 	{"ds_ping_method",     PARAM_STR, &ds_ping_method},
 	{"ds_ping_from",       PARAM_STR, &ds_ping_from},
 	{"ds_ping_interval",   INT_PARAM, &ds_ping_interval},
@@ -321,8 +323,8 @@ static int mod_init(void)
 		}
 	}	
 	/* Copy Threshhold to Config */
-	cfg_get(dispatcher, dispatcher_cfg, probing_threshhold)
-		= probing_threshhold;
+	cfg_get(dispatcher, dispatcher_cfg, probing_threshold)
+		= probing_threshold;
 
 
 	if(init_data()!= 0)
@@ -549,7 +551,7 @@ static int mod_init(void)
 }
 
 /*! \brief
- * Initialize childreng
+ * Initialize children
  */
 static int child_init(int rank)
 {

modules/dispatcher/doc/dispatcher.xml

@@ -39,6 +39,14 @@
                 <email>[email protected]</email>
                 </address>
             </editor>
+            <editor>
+                <firstname>Alessandro</firstname>
+                <surname>Arrichiello</surname>
+                <affiliation><orgname>Hewlett Packard</orgname></affiliation>
+                <address>
+                <email>[email protected]</email>
+                </address>
+            </editor>
 	</authorgroup>
 	<copyright>
 	    <year>2004</year>
@@ -56,6 +64,10 @@
 	    <year>2014</year>
 	    <holder>Olle E. Johansson, Edvina AB</holder>
 	</copyright>
+	<copyright>
+            <year>2015</year>
+            <holder>Alessandro Arrichiello, Hewlett Packard</holder>
+        </copyright>
    </bookinfo>
     <toc></toc>
     

modules/dispatcher/doc/dispatcher_admin.xml

@@ -598,14 +598,36 @@ modparam("dispatcher", "force_dst", 1)
  		</emphasis>
  		</para>
  		<example>
- 		<title>Set the <quote>ds_probing_threshhold</quote> parameter</title>
+ 		<title>Set the <quote>ds_probing_threshold</quote> parameter</title>
  <programlisting format="linespecific">
  ...
- modparam("dispatcher", "ds_probing_threshhold", 10)
+ modparam("dispatcher", "ds_probing_threshold", 10)
  ...
  </programlisting>
  		</example>
 	</section>
+	<section id="dispatcher.p.ds_inactive_threshold">
+                <title><varname>ds_inactive_threshold</varname> (int)</title>
+                <para>
+                If you want to set a gateway into active mode (after being inactive), there can be
+                a specific number of successful requests until it will change from "inactive"
+                to "active". The number of attempts can be set with this parameter.
+                This parameter can be modified via ser config framework.
+                </para>
+                <para>
+                <emphasis>
+                Default value is <quote>1</quote> (set active with first success).
+                </emphasis>
+                </para>
+                <example>
+                <title>Set the <quote>ds_inactive_threshold</quote> parameter</title>
+ <programlisting format="linespecific">
+ ...
+ modparam("dispatcher", "ds_inactive_threshold", 10)
+ ...
+ </programlisting>
+                </example>
+        </section>
  	<section id="dispatcher.p.ds_ping_reply_codes">
  		<title><varname>ds_ping_reply_codes</varname> (string)</title>
  		<para>