presence: documented local_log_level parameter

modules/presence/README

@@ -16,9 +16,9 @@ Edited by
 
 Juha Heinanen
 
-   Copyright © 2006 Voice Sistem SRL
+   Copyright © 2006 Voice Sistem SRL
 
-   Copyright © 2009 Juha Heinanen
+   Copyright © 2009 Juha Heinanen
      __________________________________________________________________
 
    Table of Contents
@@ -55,6 +55,7 @@ Juha Heinanen
               3.20. timeout_rm_subs (int)
               3.21. fetch_rows (integer)
               3.22. db_table_lock_type (integer)
+              3.23. local_log_level (int)
 
         4. Functions
 
@@ -121,11 +122,12 @@ Juha Heinanen
    1.20. Set timeout_rm_subs parameter
    1.21. Set fetch_rows parameter
    1.22. Set db_table_lock_type parameter
-   1.23. handle_publish usage
-   1.24. handle_subscribe usage
-   1.25. pres_auth_status usage
-   1.26. pres_refresh_watchers usage
-   1.27. pres_update_watchers usage
+   1.23. Set local_log_level parameter
+   1.24. handle_publish usage
+   1.25. handle_subscribe usage
+   1.26. pres_auth_status usage
+   1.27. pres_refresh_watchers usage
+   1.28. pres_update_watchers usage
    2.1. presence_api_t structure
 
 Chapter 1. Admin Guide
@@ -162,6 +164,7 @@ Chapter 1. Admin Guide
         3.20. timeout_rm_subs (int)
         3.21. fetch_rows (integer)
         3.22. db_table_lock_type (integer)
+        3.23. local_log_level (int)
 
    4. Functions
 
@@ -249,6 +252,7 @@ Chapter 1. Admin Guide
    3.20. timeout_rm_subs (int)
    3.21. fetch_rows (integer)
    3.22. db_table_lock_type (integer)
+   3.23. local_log_level (int)
 
 3.1. db_url(str)
 
@@ -257,7 +261,7 @@ Chapter 1. Admin Guide
    If set, the module is a fully operational presence server. Otherwise,
    it is used as a 'library', for its exported functions.
 
-   Default value is “NULL�.
+   Default value is "NULL".
 
    Example 1.1. Set db_url parameter
 ...
@@ -269,7 +273,7 @@ modparam("presence", "db_url",
 
    The name of the db table where PUBLISH presence information is stored.
 
-   Default value is “presentity�.
+   Default value is "presentity".
 
    Example 1.2. Set presentity_table parameter
 ...
@@ -281,7 +285,7 @@ modparam("presence", "presentity_table", "presentity")
    The name of the db table where active subscription information is
    stored.
 
-   Default value is “active_watchers�.
+   Default value is "active_watchers".
 
    Example 1.3. Set active_watchers_table parameter
 ...
@@ -292,7 +296,7 @@ modparam("presence", "active_watchers_table", "active_watchers")
 
    The name of the db table where subscription states are stored.
 
-   Default value is “watchers�.
+   Default value is "watchers".
 
    Example 1.4. Set watchers_table parameter
 ...
@@ -304,7 +308,7 @@ modparam("presence", "watchers_table", "watchers")
    The period in seconds between checks if there are expired messages
    stored in database.
 
-   Default value is “100�. A zero or negative value disables this
+   Default value is "100". A zero or negative value disables this
    activity.
 
    Example 1.5. Set clean_period parameter
@@ -317,7 +321,7 @@ modparam("presence", "clean_period", 100)
    The period at which to synchronize cached subscriber info with the
    database.
 
-   Default value is “100�. A zero or negative value disables
+   Default value is "100". A zero or negative value disables
    synchronization.
 
    Example 1.6. Set db_update_period parameter
@@ -335,7 +339,7 @@ modparam("presence", "db_update_period", 100)
    than 0. When notifier_processes is less than or equal to 0 NOTIFY
    requests are sent immediately.
 
-   Default value is “5�.
+   Default value is "5".
 
    Example 1.7. Set waitn_time parameter
 ...
@@ -352,7 +356,7 @@ modparam("presence", "waitn_time", 10)
    Separate notifier processes are only run when subs_db_mode is 3 (DB
    only mode).
 
-   Default value is “10�.
+   Default value is "10".
 
    Example 1.8. Set notifier_poll_rate parameter
 ...
@@ -372,7 +376,7 @@ modparam("presence", "notifier_poll_rate", 20)
    NOTIFY requests can be sent on a dialog at the same time, there are
    race conditions which result in CSeq re-use.
 
-   Default value is “1�.
+   Default value is "1".
 
    Example 1.9. Set notifier_processes parameter
 ...
@@ -384,7 +388,7 @@ modparam("presence", "notifier_processes", 2)
    The prefix used when generating to_tag when sending replies for
    SUBSCRIBE requests.
 
-   Default value is “10�.
+   Default value is "10".
 
    Example 1.10. Set to_tag_pref parameter
 ...
@@ -397,7 +401,7 @@ modparam("presence", "to_tag_pref", 'pres')
    when sending a 200OK for a publish. It is used for forcing the client
    to send an update before the old publish expires.
 
-   Default value is “0�.
+   Default value is "0".
 
    Example 1.11. Set expires_offset parameter
 ...
@@ -409,7 +413,7 @@ modparam("presence", "expires_offset", 10)
    The the maximum admissible expires value for PUBLISH/SUBSCRIBE message
    (in seconds).
 
-   Default value is “3600�.
+   Default value is "3600".
 
    Example 1.12. Set max_expires parameter
 ...
@@ -480,7 +484,7 @@ modparam("presence", "subs_db_mode", 1)
    database or there are other external entities inserting data into the
    presentity table.
 
-   Default value is “1�.
+   Default value is "1".
 
    Example 1.15. Set publ_cache parameter
 ...
@@ -493,7 +497,7 @@ modparam("presence", "publ_cache", 0)
    This parameter will be used as the power of 2 when computing table
    size.
 
-   Default value is “9 (512)�.
+   Default value is "9 (512)".
 
    Example 1.16. Set subs_htable_size parameter
 ...
@@ -505,7 +509,7 @@ modparam("presence", "subs_htable_size", 11)
    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)�.
+   Default value is "9 (512)".
 
    Example 1.17. Set pres_htable_size parameter
 ...
@@ -520,7 +524,7 @@ modparam("presence", "pres_htable_size", 11)
    empty NOTIFY to an message-summary event. This parameter is enabled by
    default, thus addering to the standard.
 
-   Default value is “1 �.
+   Default value is "1 ".
 
    Example 1.18. Set send_fast_notify parameter
 ...
@@ -535,7 +539,7 @@ modparam("presence", "send_fast_notify", 0)
    this check requires extra processing that should be avoided if this
    feature is not supported by the clients.
 
-   Default value is “0 �.
+   Default value is "0 ".
 
    Example 1.19. Set enable_sphere_check parameter
 ...
@@ -550,7 +554,7 @@ modparam("presence", "enable_sphere_check", 1)
    on. Disabling this will keep subscriptions active on unreliable
    networks.
 
-   Default value is “1�.
+   Default value is "1".
 
    Example 1.20. Set timeout_rm_subs parameter
 ...
@@ -586,6 +590,17 @@ modparam("presence", "fetch_rows", 1000)
 modparam("presence", "db_table_lock_type", 0)
 ...
 
+3.23. local_log_level (int)
+
+   Control log level for some debug messages inside the module.
+
+   Default value is 2 (L_INFO).
+
+   Example 1.23. Set local_log_level parameter
+...
+modparam("presence", "local_log_level", 3)
+...
+
 4. Functions
 
    4.1. handle_publish(char* sender_uri)
@@ -594,7 +609,7 @@ modparam("presence", "db_table_lock_type", 0)
    4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
    4.5. pres_update_watchers(uri, event)
 
-4.1.  handle_publish(char* sender_uri)
+4.1. handle_publish(char* sender_uri)
 
    Handles PUBLISH requests by storing and updating published information
    in memory cache and database, then calls functions to send NOTIFY
@@ -614,7 +629,7 @@ modparam("presence", "db_table_lock_type", 0)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.23. handle_publish usage
+   Example 1.24. handle_publish usage
 ...
         if(is_method("PUBLISH"))
         {
@@ -626,7 +641,7 @@ modparam("presence", "db_table_lock_type", 0)
         }
 ...
 
-4.2.  handle_subscribe([watcher_uri])
+4.2. handle_subscribe([watcher_uri])
 
    The function which handles SUBSCRIBE requests. It stores or updates
    information in memory and database and calls functions to send NOTIFY
@@ -645,13 +660,13 @@ modparam("presence", "db_table_lock_type", 0)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.24. handle_subscribe usage
+   Example 1.25. handle_subscribe usage
 ...
 if(method=="SUBSCRIBE")
     handle_subscribe();
 ...
 
-4.3.  pres_auth_status(watcher_uri, presentity_uri)
+4.3. pres_auth_status(watcher_uri, presentity_uri)
 
    The function checks if watcher is authorized to subscribe event
    'presence' of presentity. Both watcher_uri and presentity_uri are
@@ -662,7 +677,7 @@ if(method=="SUBSCRIBE")
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.25. pres_auth_status usage
+   Example 1.26. pres_auth_status usage
 ...
 if (method=="MESSAGE") {
     pres_auth_status("$fu", $ru");
@@ -674,7 +689,7 @@ if (method=="MESSAGE") {
 }
 ...
 
-4.4.  pres_refresh_watchers(uri, event, type[, file_uri, filename])
+4.4. pres_refresh_watchers(uri, event, type[, file_uri, filename])
 
    The function can be used in configuration to triger notifies to
    watchers if a change in watchers authorization or in published state
@@ -698,12 +713,12 @@ if (method=="MESSAGE") {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.26. pres_refresh_watchers usage
+   Example 1.27. pres_refresh_watchers usage
 ...
 pres_refresh_watchers("sip:[email protected]", "presence", 1);
 ...
 
-4.5.  pres_update_watchers(uri, event)
+4.5. pres_update_watchers(uri, event)
 
    The function can be used in configuration to triger updates to watchers
    status if a change in watchers authorization state occurred (i.e.,
@@ -716,7 +731,7 @@ pres_refresh_watchers("sip:[email protected]", "presence", 1);
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.27. pres_update_watchers usage
+   Example 1.28. pres_update_watchers usage
 ...
 pres_update_watchers("sip:[email protected]", "presence");
 ...
@@ -726,7 +741,7 @@ pres_update_watchers("sip:[email protected]", "presence");
    5.1. refreshWatchers
    5.2. cleanup
 
-5.1.  refreshWatchers
+5.1. refreshWatchers
 
    Triggers sending Notify messages to watchers if a change in watchers
    authorization or in published state occurred.
@@ -756,7 +771,7 @@ pres_update_watchers("sip:[email protected]", "presence");
                 1
                 _empty_line_
 
-5.2.  cleanup
+5.2. cleanup
 
    Manually triggers the cleanup functions for the active_watchers,
    presentity, and watchers tables. Useful if you have set clean_period
@@ -774,7 +789,7 @@ pres_update_watchers("sip:[email protected]", "presence");
 
    6.1. presence.cleanup
 
-6.1.  presence.cleanup
+6.1. presence.cleanup
 
    Manually triggers the cleanup functions for the active_watchers,
    presentity, and watchers tables. Useful if you have set clean_period
@@ -818,7 +833,7 @@ Chapter 2. Developer Guide
    The module provides the following functions that can be used in other
    Kamailio modules.
 
-1.  bind_presence(presence_api_t* api)
+1. bind_presence(presence_api_t* api)
 
    This function binds the presence modules and fills the structure with
    one exported function -> add_event, which when called adds a new event
@@ -854,7 +869,7 @@ typedef struct presence_api {
 }presence_api_t;
 ...
 
-2.  add_event
+2. add_event
 
    Field type:
 ...
@@ -917,7 +932,7 @@ makes a
 }pres_ev_t;
 ...
 
-3.  get_rules_doc
+3. get_rules_doc
 
    Filed type:
 ...
@@ -930,7 +945,7 @@ typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
    auth_rules_doc of the subs_t structure given as a parameter to the
    functions described bellow.
 
-4.  get_auth_status
+4. get_auth_status
 
    This filed is a function to be called for a subscription request to
    return the state for that subscription according to authorization
@@ -945,7 +960,7 @@ typedef int (get_rules_doc_t)(str* user, str* domain, str** rules_doc);
 typedef int (is_allowed_t)(struct subscription* subs);
 ...
 
-5.  apply_auth_nbody
+5. apply_auth_nbody
 
    This parameter should be a function to be called for an event that
    requires authorization, when constructing final body. The authorization
@@ -957,7 +972,7 @@ typedef int (is_allowed_t)(struct subscription* subs);
 typedef int (apply_auth_t)(str* , struct subscription*, str** );
 ...
 
-6.  agg_nbody
+6. agg_nbody
 
    If present, this field marks that the events requires aggregation of
    states. This function receives a body array and should return the final
@@ -971,7 +986,7 @@ typedef str* (agg_nbody_t)(str* pres_user, str* pres_domain,
 str** body_array, int n, int off_index);
 ..
 
-7.  free_body
+7. free_body
 
    This field must be field in if subsequent processing is performed on
    the info from database before being inserted in Notify message body(if
@@ -983,7 +998,7 @@ str** body_array, int n, int off_index);
 typedef void(free_body_t)(char* body);
 ..
 
-8.  aux_body_processing
+8. aux_body_processing
 
    This field must be set if the module needs to manipulate the NOTIFY
    body for each watcher. E.g. if the XML body includes a 'version'
@@ -997,7 +1012,7 @@ typedef void(free_body_t)(char* body);
 typedef str* (aux_body_processing_t)(struct subscription *subs, str* body);
 ..
 
-9.  aux_free_body
+9. aux_free_body
 
    This field must be set if the module registers the aux_body_processing
    function and allocates memory for the new modified body. Then, this
@@ -1012,7 +1027,7 @@ typedef str* (aux_body_processing_t)(struct subscription *subs, str* body);
 typedef void(free_body_t)(char* body);
 ..
 
-10.  evs_publ_handl
+10. evs_publ_handl
 
    This function is called when handling Publish requests. Most contain
    body correctness check.
@@ -1021,7 +1036,7 @@ typedef void(free_body_t)(char* body);
 typedef int (publ_handling_t)(struct sip_msg*);
 ..
 
-11.  evs_subs_handl
+11. evs_subs_handl
 
    It is not compulsory. Should contain event specific handling for
    Subscription requests.
@@ -1031,7 +1046,7 @@ typedef int (publ_handling_t)(struct sip_msg*);
 typedef int (subs_handling_t)(struct sip_msg*);
 ..
 
-12.  contains_event
+12. contains_event
 
    Field type:
 ..
@@ -1044,7 +1059,7 @@ event_t* parsed_event);
    found. If the second argument is an allocated event_t* structure it
    fills it with the result of the parsing.
 
-13.  get_event_list
+13. get_event_list
 
    Field type:
 ...
@@ -1054,7 +1069,7 @@ typedef int (*get_event_list_t) (str** ev_list);
    This function returns a string representation of the events registered
    in presence module.( used for Allowed-Events header).
 
-14.  update_watchers_status
+14. update_watchers_status
 
    Field type:
 ...
@@ -1068,7 +1083,7 @@ str* rules_doc);
    (used by presence_xml module when notified through an MI command of a
    change in an xcap document).
 
-15.  get_sphere
+15. get_sphere
 
    Field type:
 ...
@@ -1079,7 +1094,7 @@ typedef char* (*pres_get_sphere_t)(str* pres_uri);
    information if this has type RPID. If not found returns NULL. (the
    return value is allocated in private memory and should be freed)
 
-16.  get_presentity
+16. get_presentity
 
    Field type:
 ...
@@ -1095,7 +1110,7 @@ r *contact);
    Once you are finished with the presentity document you must call
    free_presentity to free the allocated memory.
 
-17.  free_presentity
+17. free_presentity
 
    Field type:
 ...

modules/presence/doc/presence_admin.xml

@@ -602,7 +602,25 @@ modparam("presence", "db_table_lock_type", 0)
 </programlisting>
 	    </example>
 	</section>
-
+	<section id="presence.p.local_log_level">
+	    <title><varname>local_log_level</varname> (int)</title>
+	    <para>
+		Control log level for some debug messages inside the module.
+	    </para>
+	    <para>
+		<emphasis>
+		    Default value is 2 (L_INFO).
+		</emphasis>
+	    </para>
+	    <example>
+		<title>Set <varname>local_log_level</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("presence", "local_log_level", 3)
+...
+</programlisting>
+	    </example>
+	</section>
 
 </section>