presence(k): regenerated the readme

modules_k/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
@@ -50,6 +50,7 @@ Juha Heinanen
               3.15. send_fast_notify (int)
               3.16. enable_sphere_check (int)
               3.17. timeout_rm_subs (int)
+              3.18. fetch_rows (integer)
 
         4. Functions
 
@@ -105,11 +106,12 @@ Juha Heinanen
    1.15. Set send_fast_notify parameter
    1.16. Set enable_sphere_check parameter
    1.17. Set timeout_rm_subs parameter
-   1.18. handle_publish usage
-   1.19. handle_subscribe usage
-   1.20. pres_auth_status usage
-   1.21. pres_refresh_watchers usage
-   1.22. pres_update_watchers usage
+   1.18. Set fetch_rows parameter
+   1.19. handle_publish usage
+   1.20. handle_subscribe usage
+   1.21. pres_auth_status usage
+   1.22. pres_refresh_watchers usage
+   1.23. pres_update_watchers usage
    2.1. presence_api_t structure
 
 Chapter 1. Admin Guide
@@ -141,6 +143,7 @@ Chapter 1. Admin Guide
         3.15. send_fast_notify (int)
         3.16. enable_sphere_check (int)
         3.17. timeout_rm_subs (int)
+        3.18. fetch_rows (integer)
 
    4. Functions
 
@@ -228,6 +231,7 @@ Chapter 1. Admin Guide
    3.15. send_fast_notify (int)
    3.16. enable_sphere_check (int)
    3.17. timeout_rm_subs (int)
+   3.18. fetch_rows (integer)
 
 3.1. db_url(str)
 
@@ -236,7 +240,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
 ...
@@ -248,7 +252,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
 ...
@@ -260,7 +264,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
 ...
@@ -271,7 +275,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
 ...
@@ -283,7 +287,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
@@ -296,7 +300,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
@@ -309,7 +313,7 @@ modparam("presence", "db_update_period", 100)
    The prefix used when generating to_tag when sending replies for
    SUBSCRIBE requests.
 
-   Default value is “10�.
+   Default value is "10".
 
    Example 1.7. Set to_tag_pref parameter
 ...
@@ -322,7 +326,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.8. Set expires_offset parameter
 ...
@@ -334,7 +338,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.9. Set max_expires parameter
 ...
@@ -359,7 +363,7 @@ modparam("presence", "server_address", "sip:10.10.10.10:5060")
    is continued in database. Useful for an architecture in which
    processing and memory load might be divided on more servers using the
    same database. This parameter overwrite the configuration specified
-   from the “db_mode� parameter.
+   from the "db_mode" parameter.
 
    This parameter is obsolet and will be removed in future releases.
 
@@ -388,7 +392,7 @@ modparam("presence", "db_mode", 2)
    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.13. Set subs_htable_size parameter
 ...
@@ -400,7 +404,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.14. Set pres_htable_size parameter
 ...
@@ -415,7 +419,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.15. Set send_fast_notify parameter
 ...
@@ -430,7 +434,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.16. Set enable_sphere_check parameter
 ...
@@ -445,13 +449,24 @@ 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.17. Set timeout_rm_subs parameter
 ...
 modparam("presence", "timeout_rm_subs", 0)
 ...
 
+3.18. fetch_rows (integer)
+
+   Number of rows to be loaded in one step from database.
+
+   Default value is 500.
+
+   Example 1.18. Set fetch_rows parameter
+...
+modparam("presence", "fetch_rows", 1000)
+...
+
 4. Functions
 
    4.1. handle_publish(char* sender_uri)
@@ -460,7 +475,7 @@ modparam("presence", "timeout_rm_subs", 0)
    4.4. pres_refresh_watchers(uri, event, type)
    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
@@ -480,7 +495,7 @@ modparam("presence", "timeout_rm_subs", 0)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.18. handle_publish usage
+   Example 1.19. handle_publish usage
 ...
         if(is_method("PUBLISH"))
         {
@@ -492,7 +507,7 @@ modparam("presence", "timeout_rm_subs", 0)
         }
 ...
 
-4.2.  handle_subscribe()
+4.2. handle_subscribe()
 
    The function which handles SUBSCRIBE requests. It stores or updates
    information in memory and database and calls functions to send NOTIFY
@@ -506,13 +521,13 @@ modparam("presence", "timeout_rm_subs", 0)
 
    The module sends an appropriate stateless reply in all cases.
 
-   Example 1.19. handle_subscribe usage
+   Example 1.20. 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
@@ -523,7 +538,7 @@ if(method=="SUBSCRIBE")
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.20. pres_auth_status usage
+   Example 1.21. pres_auth_status usage
 ...
 if (method=="MESSAGE") {
     pres_auth_status("$fu", $ru");
@@ -535,7 +550,7 @@ if (method=="MESSAGE") {
 }
 ...
 
-4.4.  pres_refresh_watchers(uri, event, type)
+4.4. pres_refresh_watchers(uri, event, type)
 
    The function can be used in configuration to triger notifies to
    watchers if a change in watchers authorization or in published state
@@ -554,12 +569,12 @@ if (method=="MESSAGE") {
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.21. pres_refresh_watchers usage
+   Example 1.22. 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.,
@@ -572,7 +587,7 @@ pres_refresh_watchers("sip:[email protected]", "presence", 1);
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.22. pres_update_watchers usage
+   Example 1.23. pres_update_watchers usage
 ...
 pres_update_watchers("sip:[email protected]", "presence");
 ...
@@ -582,7 +597,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.
@@ -608,7 +623,7 @@ pres_update_watchers("sip:[email protected]", "presence");
                 1
                 _empty_line_
 
-5.2.  cleanup
+5.2. cleanup
 
    Manually triggers the cleanup functions for watchers and presentity
    tables. Useful if you have set clean_period to zero or less.
@@ -655,7 +670,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
@@ -691,7 +706,7 @@ typedef struct presence_api {
 }presence_api_t;
 ...
 
-2.  add_event
+2. add_event
 
    Field type:
 ...
@@ -754,7 +769,7 @@ makes a
 }pres_ev_t;
 ...
 
-3.  get_rules_doc
+3. get_rules_doc
 
    Filed type:
 ...
@@ -767,7 +782,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
@@ -782,7 +797,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
@@ -794,7 +809,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
@@ -808,7 +823,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
@@ -820,7 +835,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'
@@ -834,7 +849,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
@@ -849,7 +864,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.
@@ -858,7 +873,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.
@@ -868,7 +883,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:
 ..
@@ -881,7 +896,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:
 ...
@@ -891,7 +906,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:
 ...
@@ -905,7 +920,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:
 ...
@@ -916,7 +931,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:
 ...
@@ -932,7 +947,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:
 ...