modules: readme files regenerated - presence ...

modules/presence/README

@@ -43,28 +43,29 @@ Juha Heinanen
               3.8. notifier_poll_rate (int)
               3.9. notifier_processes (int)
               3.10. force_delete (int)
-              3.11. to_tag_pref (str)
-              3.12. expires_offset (int)
-              3.13. max_expires (int)
-              3.14. min_expires (int)
-              3.15. min_expires_action (int)
-              3.16. server_address (str)
-              3.17. subs_db_mode (int)
-              3.18. publ_cache (int)
-              3.19. subs_htable_size (int)
-              3.20. pres_htable_size (int)
-              3.21. send_fast_notify (int)
-              3.22. enable_sphere_check (int)
-              3.23. timeout_rm_subs (int)
-              3.24. fetch_rows (integer)
-              3.25. db_table_lock_type (integer)
-              3.26. local_log_level (int)
-              3.27. local_log_facility (int)
-              3.28. subs_remove_match (int)
-              3.29. xavp_cfg (str)
-              3.30. retrieve_order (int)
-              3.31. retrieve_order_by (str)
-              3.32. sip_uri_match (int)
+              3.11. startup_mode (int)
+              3.12. to_tag_pref (str)
+              3.13. expires_offset (int)
+              3.14. max_expires (int)
+              3.15. min_expires (int)
+              3.16. min_expires_action (int)
+              3.17. server_address (str)
+              3.18. subs_db_mode (int)
+              3.19. publ_cache (int)
+              3.20. subs_htable_size (int)
+              3.21. pres_htable_size (int)
+              3.22. send_fast_notify (int)
+              3.23. enable_sphere_check (int)
+              3.24. timeout_rm_subs (int)
+              3.25. fetch_rows (integer)
+              3.26. db_table_lock_type (integer)
+              3.27. local_log_level (int)
+              3.28. local_log_facility (int)
+              3.29. subs_remove_match (int)
+              3.30. xavp_cfg (str)
+              3.31. retrieve_order (int)
+              3.32. retrieve_order_by (str)
+              3.33. sip_uri_match (int)
 
         4. Functions
 
@@ -128,36 +129,37 @@ Juha Heinanen
    1.8. Set notifier_poll_rate parameter
    1.9. Set notifier_processes parameter
    1.10. Set force_delete parameter
-   1.11. Set to_tag_pref parameter
-   1.12. Set expires_offset parameter
-   1.13. Set max_expires parameter
-   1.14. Set min_expires parameter
+   1.11. Set startup_mode parameter
+   1.12. Set to_tag_pref parameter
+   1.13. Set expires_offset parameter
+   1.14. Set max_expires parameter
    1.15. Set min_expires parameter
-   1.16. Set server_address parameter
-   1.17. Set subs_db_mode parameter
-   1.18. Set publ_cache parameter
-   1.19. Set subs_htable_size parameter
-   1.20. Set pres_htable_size parameter
-   1.21. Set send_fast_notify parameter
-   1.22. Set enable_sphere_check parameter
-   1.23. Set timeout_rm_subs parameter
-   1.24. Set fetch_rows parameter
-   1.25. Set db_table_lock_type parameter
-   1.26. Set local_log_level parameter
-   1.27. Set local_log_facility parameter
-   1.28. Set subs_remove_match parameter
-   1.29. Set xavp_cfg parameter
-   1.30. Set retrieve_order parameter
-   1.31. Set retrieve_order_by parameter
-   1.32. Set sip_uri_match parameter
-   1.33. handle_publish usage
-   1.34. handle_subscribe usage
-   1.35. pres_auth_status usage
-   1.36. pres_refresh_watchers usage
-   1.37. pres_update_watchers usage
-   1.38. $subs(name) usage
-   1.39. $notify_reply(name) usage
+   1.16. Set min_expires parameter
+   1.17. Set server_address parameter
+   1.18. Set subs_db_mode parameter
+   1.19. Set publ_cache parameter
+   1.20. Set subs_htable_size parameter
+   1.21. Set pres_htable_size parameter
+   1.22. Set send_fast_notify parameter
+   1.23. Set enable_sphere_check parameter
+   1.24. Set timeout_rm_subs parameter
+   1.25. Set fetch_rows parameter
+   1.26. Set db_table_lock_type parameter
+   1.27. Set local_log_level parameter
+   1.28. Set local_log_facility parameter
+   1.29. Set subs_remove_match parameter
+   1.30. Set xavp_cfg parameter
+   1.31. Set retrieve_order parameter
+   1.32. Set retrieve_order_by parameter
+   1.33. Set sip_uri_match parameter
+   1.34. handle_publish usage
+   1.35. handle_subscribe usage
+   1.36. pres_auth_status usage
+   1.37. pres_refresh_watchers usage
+   1.38. pres_update_watchers usage
+   1.39. $subs(name) usage
    1.40. $notify_reply(name) usage
+   1.41. $notify_reply(name) usage
    2.1. presence_api_t structure
 
 Chapter 1. Admin Guide
@@ -182,28 +184,29 @@ Chapter 1. Admin Guide
         3.8. notifier_poll_rate (int)
         3.9. notifier_processes (int)
         3.10. force_delete (int)
-        3.11. to_tag_pref (str)
-        3.12. expires_offset (int)
-        3.13. max_expires (int)
-        3.14. min_expires (int)
-        3.15. min_expires_action (int)
-        3.16. server_address (str)
-        3.17. subs_db_mode (int)
-        3.18. publ_cache (int)
-        3.19. subs_htable_size (int)
-        3.20. pres_htable_size (int)
-        3.21. send_fast_notify (int)
-        3.22. enable_sphere_check (int)
-        3.23. timeout_rm_subs (int)
-        3.24. fetch_rows (integer)
-        3.25. db_table_lock_type (integer)
-        3.26. local_log_level (int)
-        3.27. local_log_facility (int)
-        3.28. subs_remove_match (int)
-        3.29. xavp_cfg (str)
-        3.30. retrieve_order (int)
-        3.31. retrieve_order_by (str)
-        3.32. sip_uri_match (int)
+        3.11. startup_mode (int)
+        3.12. to_tag_pref (str)
+        3.13. expires_offset (int)
+        3.14. max_expires (int)
+        3.15. min_expires (int)
+        3.16. min_expires_action (int)
+        3.17. server_address (str)
+        3.18. subs_db_mode (int)
+        3.19. publ_cache (int)
+        3.20. subs_htable_size (int)
+        3.21. pres_htable_size (int)
+        3.22. send_fast_notify (int)
+        3.23. enable_sphere_check (int)
+        3.24. timeout_rm_subs (int)
+        3.25. fetch_rows (integer)
+        3.26. db_table_lock_type (integer)
+        3.27. local_log_level (int)
+        3.28. local_log_facility (int)
+        3.29. subs_remove_match (int)
+        3.30. xavp_cfg (str)
+        3.31. retrieve_order (int)
+        3.32. retrieve_order_by (str)
+        3.33. sip_uri_match (int)
 
    4. Functions
 
@@ -288,28 +291,29 @@ Chapter 1. Admin Guide
    3.8. notifier_poll_rate (int)
    3.9. notifier_processes (int)
    3.10. force_delete (int)
-   3.11. to_tag_pref (str)
-   3.12. expires_offset (int)
-   3.13. max_expires (int)
-   3.14. min_expires (int)
-   3.15. min_expires_action (int)
-   3.16. server_address (str)
-   3.17. subs_db_mode (int)
-   3.18. publ_cache (int)
-   3.19. subs_htable_size (int)
-   3.20. pres_htable_size (int)
-   3.21. send_fast_notify (int)
-   3.22. enable_sphere_check (int)
-   3.23. timeout_rm_subs (int)
-   3.24. fetch_rows (integer)
-   3.25. db_table_lock_type (integer)
-   3.26. local_log_level (int)
-   3.27. local_log_facility (int)
-   3.28. subs_remove_match (int)
-   3.29. xavp_cfg (str)
-   3.30. retrieve_order (int)
-   3.31. retrieve_order_by (str)
-   3.32. sip_uri_match (int)
+   3.11. startup_mode (int)
+   3.12. to_tag_pref (str)
+   3.13. expires_offset (int)
+   3.14. max_expires (int)
+   3.15. min_expires (int)
+   3.16. min_expires_action (int)
+   3.17. server_address (str)
+   3.18. subs_db_mode (int)
+   3.19. publ_cache (int)
+   3.20. subs_htable_size (int)
+   3.21. pres_htable_size (int)
+   3.22. send_fast_notify (int)
+   3.23. enable_sphere_check (int)
+   3.24. timeout_rm_subs (int)
+   3.25. fetch_rows (integer)
+   3.26. db_table_lock_type (integer)
+   3.27. local_log_level (int)
+   3.28. local_log_facility (int)
+   3.29. subs_remove_match (int)
+   3.30. xavp_cfg (str)
+   3.31. retrieve_order (int)
+   3.32. retrieve_order_by (str)
+   3.33. sip_uri_match (int)
 
 3.1. db_url(str)
 
@@ -454,19 +458,34 @@ modparam("presence", "notifier_processes", 2)
 modparam("presence", "force_delete", 1)
 ...
 
-3.11. to_tag_pref (str)
+3.11. startup_mode (int)
+
+   Setting this parameter to 0 will provide startup related backward
+   compatibility for some modules. Setting to 0 fixes presentity requests
+   with low expires (e.g. time() + 1)
+
+   Set this parameter to “0” to enable backward compatibility.
+
+   Default value is “1”.
+
+   Example 1.11. Set startup_mode parameter
+...
+modparam("presence", "startup_mode", 0)
+...
+
+3.12. to_tag_pref (str)
 
    The prefix used when generating to_tag when sending replies for
    SUBSCRIBE requests.
 
    Default value is “10”.
 
-   Example 1.11. Set to_tag_pref parameter
+   Example 1.12. Set to_tag_pref parameter
 ...
 modparam("presence", "to_tag_pref", 'pres')
 ...
 
-3.12. expires_offset (int)
+3.13. expires_offset (int)
 
    The value in seconds that should be subtracted from the expires value
    when sending a 200OK for a publish. It is used for forcing the client
@@ -474,24 +493,24 @@ modparam("presence", "to_tag_pref", 'pres')
 
    Default value is “0”.
 
-   Example 1.12. Set expires_offset parameter
+   Example 1.13. Set expires_offset parameter
 ...
 modparam("presence", "expires_offset", 10)
 ...
 
-3.13. max_expires (int)
+3.14. max_expires (int)
 
    The maximum admissible expires value for PUBLISH/SUBSCRIBE message (in
    seconds).
 
    Default value is “3600”.
 
-   Example 1.13. Set max_expires parameter
+   Example 1.14. Set max_expires parameter
 ...
 modparam("presence", "max_expires", 3600)
 ...
 
-3.14. min_expires (int)
+3.15. min_expires (int)
 
    The minimum admissible expires value for PUBLISH/SUBSCRIBE message (in
    seconds).
@@ -500,12 +519,12 @@ modparam("presence", "max_expires", 3600)
 
    Default value is “0”.
 
-   Example 1.14. Set min_expires parameter
+   Example 1.15. Set min_expires parameter
             ...
             modparam("presence", "min_expires", 1800)
             ...
 
-3.15. min_expires_action (int)
+3.16. min_expires_action (int)
 
    The action to take when UA sends a expires value less then min_expires.
 
@@ -517,23 +536,23 @@ modparam("presence", "max_expires", 3600)
 
    Default value is “1”.
 
-   Example 1.15. Set min_expires parameter
+   Example 1.16. Set min_expires parameter
             ...
             modparam("presence", "min_expires", 1800)
             ...
 
-3.16. server_address (str)
+3.17. server_address (str)
 
    The presence server address which will become the value of Contact
    header filed for 200 OK replies to SUBSCRIBE and PUBLISH and in NOTIFY
    messages.
 
-   Example 1.16. Set server_address parameter
+   Example 1.17. Set server_address parameter
 ...
 modparam("presence", "server_address", "sip:10.10.10.10:5060")
 ...
 
-3.17. subs_db_mode (int)
+3.18. subs_db_mode (int)
 
    The presence module can utilize database for persistent subscription
    storage. If you use database, your subscriptions will survive machine
@@ -567,12 +586,12 @@ modparam("presence", "server_address", "sip:10.10.10.10:5060")
 
    Default value is 2 (Write-Back scheme).
 
-   Example 1.17. Set subs_db_mode parameter
+   Example 1.18. Set subs_db_mode parameter
 ...
 modparam("presence", "subs_db_mode", 1)
 ...
 
-3.18. publ_cache (int)
+3.19. publ_cache (int)
 
    To improve performance, the presence module holds by default a publish
    cache that says if a certain publication exists in database. This is
@@ -588,12 +607,12 @@ modparam("presence", "subs_db_mode", 1)
 
    Default value is “1”.
 
-   Example 1.18. Set publ_cache parameter
+   Example 1.19. Set publ_cache parameter
 ...
 modparam("presence", "publ_cache", 0)
 ...
 
-3.19. subs_htable_size (int)
+3.20. subs_htable_size (int)
 
    The size of the in-memory hash table to store subscription dialogs.
    This parameter will be used as the power of 2 when computing table
@@ -601,24 +620,24 @@ modparam("presence", "publ_cache", 0)
 
    Default value is “9 (512)”.
 
-   Example 1.19. Set subs_htable_size parameter
+   Example 1.20. Set subs_htable_size parameter
 ...
 modparam("presence", "subs_htable_size", 11)
 ...
 
-3.20. pres_htable_size (int)
+3.21. pres_htable_size (int)
 
    The size of the in-memory hash table to store publish records. This
    parameter will be used as the power of 2 when computing table size.
 
    Default value is “9 (512)”.
 
-   Example 1.20. Set pres_htable_size parameter
+   Example 1.21. Set pres_htable_size parameter
 ...
 modparam("presence", "pres_htable_size", 11)
 ...
 
-3.21. send_fast_notify (int)
+3.22. send_fast_notify (int)
 
    This parameter enables or disables the sending of an initial empty
    NOTIFY after a SUBSCRIBE/reSUBSCRIBE. This caused problems for MWI
@@ -628,12 +647,12 @@ modparam("presence", "pres_htable_size", 11)
 
    Default value is “1 ”.
 
-   Example 1.21. Set send_fast_notify parameter
+   Example 1.22. Set send_fast_notify parameter
 ...
 modparam("presence", "send_fast_notify", 0)
 ...
 
-3.22. enable_sphere_check (int)
+3.23. enable_sphere_check (int)
 
    This parameter is a flag that should be set if permission rules include
    sphere checking. The sphere information is expected to be present in
@@ -643,12 +662,12 @@ modparam("presence", "send_fast_notify", 0)
 
    Default value is “0 ”.
 
-   Example 1.22. Set enable_sphere_check parameter
+   Example 1.23. Set enable_sphere_check parameter
 ...
 modparam("presence", "enable_sphere_check", 1)
 ...
 
-3.23. timeout_rm_subs (int)
+3.24. timeout_rm_subs (int)
 
    This parameter is a flag that should be set if subscriptions should be
    removed from the active_watchers when a NOTIFY times out. RFC3265
@@ -658,23 +677,23 @@ modparam("presence", "enable_sphere_check", 1)
 
    Default value is “1”.
 
-   Example 1.23. Set timeout_rm_subs parameter
+   Example 1.24. Set timeout_rm_subs parameter
 ...
 modparam("presence", "timeout_rm_subs", 0)
 ...
 
-3.24. fetch_rows (integer)
+3.25. fetch_rows (integer)
 
    Number of rows to be loaded in one step from database.
 
    Default value is 500.
 
-   Example 1.24. Set fetch_rows parameter
+   Example 1.25. Set fetch_rows parameter
 ...
 modparam("presence", "fetch_rows", 1000)
 ...
 
-3.25. db_table_lock_type (integer)
+3.26. db_table_lock_type (integer)
 
    Enable (=1) or disable (=0) the Locks for table during an transaction.
    Locking only the "current" table causes problems with a MySQL-Databases
@@ -687,35 +706,35 @@ modparam("presence", "fetch_rows", 1000)
 
    Default value is 1 (Write Lock for the Tables).
 
-   Example 1.25. Set db_table_lock_type parameter
+   Example 1.26. Set db_table_lock_type parameter
 ...
 modparam("presence", "db_table_lock_type", 0)
 ...
 
-3.26. local_log_level (int)
+3.27. local_log_level (int)
 
    Control log level for some debug messages inside the module.
 
    Default value is 2 (L_INFO).
 
-   Example 1.26. Set local_log_level parameter
+   Example 1.27. Set local_log_level parameter
 ...
 modparam("presence", "local_log_level", 3)
 ...
 
-3.27. local_log_facility (int)
+3.28. local_log_facility (int)
 
    Control syslog facility for some debug messages inside the module.
 
    Default value is taken from the core log_facility configuration
    parameter.
 
-   Example 1.27. Set local_log_facility parameter
+   Example 1.28. Set local_log_facility parameter
 ...
 modparam("presence", "local_log_facility", "LOG_LOCAL3")
 ...
 
-3.28. subs_remove_match (int)
+3.29. subs_remove_match (int)
 
    Control how to match the subscriptions to remove from memory. If set to
    0, then the match is done on To-Tag (local generated), if set to 1,
@@ -724,12 +743,12 @@ modparam("presence", "local_log_facility", "LOG_LOCAL3")
 
    Default value is 0.
 
-   Example 1.28. Set subs_remove_match parameter
+   Example 1.29. Set subs_remove_match parameter
 ...
 modparam("presence", "subs_remove_match", 1)
 ...
 
-3.29. xavp_cfg (str)
+3.30. xavp_cfg (str)
 
    The name of the xavp to be used to specify attributes for internal
    processing of presence module.
@@ -745,7 +764,7 @@ modparam("presence", "subs_remove_match", 1)
 
    Default value is empty (not set).
 
-   Example 1.29. Set xavp_cfg parameter
+   Example 1.30. Set xavp_cfg parameter
 ...
 modparam("presence", "xavp_cfg", "pres")
 ...
@@ -754,7 +773,7 @@ if(is_method("PUBLISH")) {
 }
 ...
 
-3.30. retrieve_order (int)
+3.31. retrieve_order (int)
 
    If set to 0, presentity records are retrieve by received_time order. If
    set to 1, presentity records are retrieve by the value of
@@ -762,24 +781,24 @@ if(is_method("PUBLISH")) {
 
    Default value is 0.
 
-   Example 1.30. Set retrieve_order parameter
+   Example 1.31. Set retrieve_order parameter
 ...
 modparam("presence", "retrieve_order", 1)
 ...
 
-3.31. retrieve_order_by (str)
+3.32. retrieve_order_by (str)
 
    Used to set the order-by of the db query for fetching the presence
    records when retrieve_order is set to 1.
 
    Default value is “priority”.
 
-   Example 1.31. Set retrieve_order_by parameter
+   Example 1.32. Set retrieve_order_by parameter
 ...
 modparam("presence", "retrieve_order_by", "priority, received_time")
 ...
 
-3.32. sip_uri_match (int)
+3.33. sip_uri_match (int)
 
    The mode used when comparing uris.
 
@@ -789,7 +808,7 @@ modparam("presence", "retrieve_order_by", "priority, received_time")
 
    Default value is “0”.
 
-   Example 1.32. Set sip_uri_match parameter
+   Example 1.33. Set sip_uri_match parameter
             ...
             modparam("presence", "sip_uri_match", 1)
             ...
@@ -822,7 +841,7 @@ modparam("presence", "retrieve_order_by", "priority, received_time")
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.33. handle_publish usage
+   Example 1.34. handle_publish usage
 ...
         if(is_method("PUBLISH"))
         {
@@ -853,7 +872,7 @@ modparam("presence", "retrieve_order_by", "priority, received_time")
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.34. handle_subscribe usage
+   Example 1.35. handle_subscribe usage
 ...
 if(method=="SUBSCRIBE")
     handle_subscribe();
@@ -870,7 +889,7 @@ if(method=="SUBSCRIBE")
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.35. pres_auth_status usage
+   Example 1.36. pres_auth_status usage
 ...
 if (method=="MESSAGE") {
     pres_auth_status("$fu", $ru");
@@ -906,7 +925,7 @@ if (method=="MESSAGE") {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.36. pres_refresh_watchers usage
+   Example 1.37. pres_refresh_watchers usage
 ...
 pres_refresh_watchers("sip:[email protected]", "presence", 1);
 ...
@@ -924,7 +943,7 @@ pres_refresh_watchers("sip:[email protected]", "presence", 1);
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.37. pres_update_watchers usage
+   Example 1.38. pres_update_watchers usage
 ...
 pres_update_watchers("sip:[email protected]", "presence");
 ...
@@ -1030,7 +1049,7 @@ pres_update_watchers("sip:[email protected]", "presence");
      * flags
      * user_agent
 
-   Example 1.38. $subs(name) usage
+   Example 1.39. $subs(name) usage
 ...
 if(handle_subscription())
 {
@@ -1046,7 +1065,7 @@ if(handle_subscription())
 
    The “attr” can be any pseudo var that accesses attributes of msg
 
-   Example 1.39. $notify_reply(name) usage
+   Example 1.40. $notify_reply(name) usage
 ...
 event_route[presence:notify-reply]
 {
@@ -1062,7 +1081,7 @@ event_route[presence:notify-reply]
 
    Fired after notify reply is received or timeout.
 
-   Example 1.40. $notify_reply(name) usage
+   Example 1.41. $notify_reply(name) usage
 ...
 event_route[presence:notify-reply]
 {