rls(k): regenerated the readme file

modules_k/rls/README

@@ -1,4 +1,3 @@
-
 Resource List Server
 
 Anca-Maria Vamanu
@@ -10,7 +9,7 @@ Edited by
 Anca-Maria Vamanu
 
    Copyright © 2007 Voice Sistem SRL
-     _________________________________________________________________
+     __________________________________________________________________
 
    Table of Contents
 
@@ -42,12 +41,13 @@ Anca-Maria Vamanu
               3.16. outbound_proxy (str)
               3.17. server_address (str)
               3.18. max_notify_body_length (int)
+              3.19. fetch_rows (integer)
 
         4. Functions
 
-              4.1. rls_handle_subscribe() 
-              4.2. rls_handle_notify() 
-              4.3. rls_update_subs(uri, event) 
+              4.1. rls_handle_subscribe()
+              4.2. rls_handle_notify()
+              4.3. rls_update_subs(uri, event)
 
         5. Installation
 
@@ -73,9 +73,10 @@ Anca-Maria Vamanu
    1.16. Set outbound_proxy parameter
    1.17. Set server_address parameter
    1.18. Set max_notify_body_length parameter
-   1.19. rls_handle_subscribe usage
-   1.20. rls_handle_notify usage
-   1.21. rls_update_subs usage
+   1.19. Set fetch_rows parameter
+   1.20. rls_handle_subscribe usage
+   1.21. rls_handle_notify usage
+   1.22. rls_update_subs usage
 
 Chapter 1. Admin Guide
 
@@ -107,43 +108,44 @@ Chapter 1. Admin Guide
         3.16. outbound_proxy (str)
         3.17. server_address (str)
         3.18. max_notify_body_length (int)
+        3.19. fetch_rows (integer)
 
    4. Functions
 
-        4.1. rls_handle_subscribe() 
-        4.2. rls_handle_notify() 
-        4.3. rls_update_subs(uri, event) 
+        4.1. rls_handle_subscribe()
+        4.2. rls_handle_notify()
+        4.3. rls_update_subs(uri, event)
 
    5. Installation
 
 1. Overview
 
-   The  modules  is  a  Resource List Server implementation following the
+   The modules is a Resource List Server implementation following the
    specification in RFC 4662 and RFC 4826.
 
-   The  server  is  independent  from  local presence servers, retrieving
+   The server is independent from local presence servers, retrieving
    presence information with Subscribe-Notify messages.
 
-   The  module  uses  the  presence module as a library, as it requires a
-   resembling  mechanism  for  handling Subscribe. Therefore, in case the
-   local  presence  server is not collocated on the same machine with the
-   RL server, the presence module should be loaded in a library mode only
+   The module uses the presence module as a library, as it requires a
+   resembling mechanism for handling Subscribe. Therefore, in case the
+   local presence server is not collocated on the same machine with the RL
+   server, the presence module should be loaded in a library mode only
    (see doc for presence module).
 
-   It  handles  subscription  to  lists  in  an event independent way.The
-   default  event is presence, but if some other events are to be handled
-   by  the  server,  they  should  be  added  using  the module parameter
+   It handles subscription to lists in an event independent way.The
+   default event is presence, but if some other events are to be handled
+   by the server, they should be added using the module parameter
    "rls_events".
 
-   It  works  with XCAP server for storage. There is also the possibility
-   to  configure  it  to  work in an integrated_xcap server mode, when it
-   only queries database for the resource lists documents. This is useful
-   in  a small architecture when all the clients use an integrated server
-   and there are no references to exterior documents in their lists.
+   It works with XCAP server for storage. There is also the possibility to
+   configure it to work in an integrated_xcap server mode, when it only
+   queries database for the resource lists documents. This is useful in a
+   small architecture when all the clients use an integrated server and
+   there are no references to exterior documents in their lists.
 
-   The  same  as  presence  module, it has a caching mode with periodical
-   update   in   database  for  subscribe  information.  The  information
-   retrieved with Notify messages is stored in database only.
+   The same as presence module, it has a caching mode with periodical
+   update in database for subscribe information. The information retrieved
+   with Notify messages is stored in database only.
 
 2. Dependencies
 
@@ -183,12 +185,13 @@ Chapter 1. Admin Guide
    3.16. outbound_proxy (str)
    3.17. server_address (str)
    3.18. max_notify_body_length (int)
+   3.19. fetch_rows (integer)
 
 3.1. db_url(str)
 
    The database url.
 
-   Default value is "mysql://openser:openserrw@localhost/openser". 
+   Default value is "mysql://openser:openserrw@localhost/openser".
 
    Example 1.1. Set db_url parameter
 ...
@@ -197,10 +200,10 @@ modparam("rls", "db_url", "dbdriver://username:password@dbhost/dbname")
 
 3.2. xcap_db_url(str)
 
-   The  xcap  database  url. This parameter only needs to be specified if
-   the rls db and integerated xcap server db have different urls.
+   The xcap database url. This parameter only needs to be specified if the
+   rls db and integerated xcap server db have different urls.
 
-   Default value is a mirror of the "db_url" setting. 
+   Default value is a mirror of the "db_url" setting.
 
    Example 1.2. Set xcap_db_url parameter
 ...
@@ -209,12 +212,12 @@ modparam("rls", "xcap_db_url", "dbdriver://username:password@dbhost/dbname")
 
 3.3. db_mode(int)
 
-   The  module  supports  2  modes  of operation, high speed memory based
-   storage  (mode 0), and database only (mode 2) where all data is stored
+   The module supports 2 modes of operation, high speed memory based
+   storage (mode 0), and database only (mode 2) where all data is stored
    in a database, allowing scalability at the expense of speed. Mode 1 is
    reserved.
 
-   Default value is "0" 
+   Default value is "0"
 
    Example 1.3. Set db_mode parameter
 ...
@@ -223,12 +226,12 @@ modparam("rls", "db_mode", 2)
 
 3.4. xcap_table(str)
 
-   The  name  of  the  xcap  table  in which the integrated server or the
-   xcap_client  module  writes.  If  integrated_xcap_server parameter not
-   set,  the  name  of  the table must be the same as the one set for the
+   The name of the xcap table in which the integrated server or the
+   xcap_client module writes. If integrated_xcap_server parameter not set,
+   the name of the table must be the same as the one set for the
    xcap_client module.
 
-   Default value is "xcap". 
+   Default value is "xcap".
 
    Example 1.4. Set xcap_table parameter
 ...
@@ -240,7 +243,7 @@ modparam("rls", "xcap_table", "xcaps");
    The name of the db table where resource lists subscription information
    is stored.
 
-   Default value is "rls_watchers". 
+   Default value is "rls_watchers".
 
    Example 1.5. Set rlsubs_table parameter
 ...
@@ -249,10 +252,10 @@ modparam("rls", "rlsubs_table", "rls_subscriptions")
 
 3.6. rlpres_table(str)
 
-   The  name of the db table where notified event specific information is
+   The name of the db table where notified event specific information is
    stored.
 
-   Default value is "rls_presentity". 
+   Default value is "rls_presentity".
 
    Example 1.6. Set rlpres_table parameter
 ...
@@ -263,7 +266,7 @@ modparam("rls", "rlpres_table", "rls_notify")
 
    The period at which to check for expired information.
 
-   Default value is "100". 
+   Default value is "100".
 
    Example 1.7. Set clean_period parameter
 ...
@@ -272,11 +275,11 @@ modparam("rls", "clean_period", 100)
 
 3.8. waitn_time (int)
 
-   The  timer  period at which the server should attempt to send Notifies
-   with  the  updated  presence  state  of the subscribed list or watcher
+   The timer period at which the server should attempt to send Notifies
+   with the updated presence state of the subscribed list or watcher
    information.
 
-   Default value is "50". 
+   Default value is "50".
 
    Example 1.8. Set waitn_time parameter
 ...
@@ -287,7 +290,7 @@ modparam("rls", "waitn_time", 10)
 
    The maximum accepted expires for a subscription to a list.
 
-   Default value is "7200". 
+   Default value is "7200".
 
    Example 1.9. Set max_expires parameter
 ...
@@ -296,16 +299,16 @@ modparam("rls", "max_expires", 10800)
 
 3.10. expires_offset (int)
 
-   This  paramater  only  has an effect when the db_mode is DB_ONLY (mode
-   2).  When  expired  subscribers  are  checked  for  deletion  from the
-   database,  those that have a value in the expires column which is less
-   than  current_time  - expires_offset are matched. Hence when an offset
-   of  zero is used, all those that expire prior the current time will be
-   deleted.  If  an  offset  of 't' is used, only those that expired more
-   than t seconds ago are deleted from the database. Negative offsets are
-   treated as though an offset of zero was specifed.
+   This paramater only has an effect when the db_mode is DB_ONLY (mode 2).
+   When expired subscribers are checked for deletion from the database,
+   those that have a value in the expires column which is less than
+   current_time - expires_offset are matched. Hence when an offset of zero
+   is used, all those that expire prior the current time will be deleted.
+   If an offset of 't' is used, only those that expired more than t
+   seconds ago are deleted from the database. Negative offsets are treated
+   as though an offset of zero was specifed.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.10. Set expires_offset parameter
 ...
@@ -314,11 +317,11 @@ modparam("rls", "expires_offset", 0)
 
 3.11. hash_size (int)
 
-   The  dimension of the hash table used to store subscription to a list.
-   This  parameter  will  be  used as the power of 2 when computing table
+   The dimension of the hash table used to store subscription to a list.
+   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.11. Set hash_size parameter
 ...
@@ -329,7 +332,7 @@ modparam("rls", "hash_size", 11)
 
    The address of the xcap server.
 
-   Default value is "NULL". 
+   Default value is "NULL".
 
    Example 1.12. Set hash_size parameter
 ...
@@ -338,10 +341,10 @@ modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")
 
 3.13. integrated_xcap_server (int)
 
-   This  parameter should be set if only integrated xcap servers are used
+   This parameter should be set if only integrated xcap servers are used
    to store resource lists.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.13. Set integrated_xcap_server parameter
 ...
@@ -350,13 +353,13 @@ modparam("rls", "integrated_xcap_server", 1)
 
 3.14. to_presence_code (int)
 
-   The  code  to  be  returned  by  rls_handle_subscribe  function if the
+   The code to be returned by rls_handle_subscribe function if the
    processed Subscribe is not a resource list Subscribe. This code can be
-   used  in  an  architecture with presence and rls servers collocated on
-   the same machine, to call handle_subscribe on the message causing this
+   used in an architecture with presence and rls servers collocated on the
+   same machine, to call handle_subscribe on the message causing this
    code.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.14. Set to_presence_code parameter
 ...
@@ -365,11 +368,11 @@ modparam("rls", "to_presence_code", 10)
 
 3.15. rls_event (str)
 
-   The  default  event that RLS handles is presence. If some other events
-   should  also  be  handled  by  RLS  they  should  be  added using this
+   The default event that RLS handles is presence. If some other events
+   should also be handled by RLS they should be added using this
    parameter. It can be set more than once.
 
-   Default value is ""presence"". 
+   Default value is ""presence"".
 
    Example 1.15. Set rls_event parameter
 ...
@@ -378,10 +381,10 @@ modparam("rls", "rls_event", "dialog;sla")
 
 3.16. outbound_proxy (str)
 
-   The  SIP  address  where  to  send  RLS  subscriptions (outbound proxy
-   address as SIP URI).
+   The SIP address where to send RLS subscriptions (outbound proxy address
+   as SIP URI).
 
-   Default value is "NULL". 
+   Default value is "NULL".
 
    Example 1.16. Set outbound_proxy parameter
 ...
@@ -390,8 +393,8 @@ modparam("rls", "outbound_proxy", "sip:presence.kamailio.org")
 
 3.17. server_address (str)
 
-   The  address  of  the  server  that  will be used as a contact in sent
-   Subscribe  requests and 200 OK replies for Subscribe requests for RLS.
+   The address of the server that will be used as a contact in sent
+   Subscribe requests and 200 OK replies for Subscribe requests for RLS.
    It is a mandatory parameter.
 
    Example 1.17. Set server_address parameter
@@ -410,22 +413,33 @@ modparam("rls", "server_address", "sip:[email protected]:5060")
 modparam("rls", "max_notify_body_length", 32000)
 ...
 
+3.19. fetch_rows (integer)
+
+   Number of rows to be loaded in one step from database.
+
+   Default value is 500.
+
+   Example 1.19. Set fetch_rows parameter
+...
+modparam("rls", "fetch_rows", 1000)
+...
+
 4. Functions
 
-   4.1. rls_handle_subscribe() 
-   4.2. rls_handle_notify() 
-   4.3. rls_update_subs(uri, event) 
+   4.1. rls_handle_subscribe()
+   4.2. rls_handle_notify()
+   4.3. rls_update_subs(uri, event)
 
-4.1.  rls_handle_subscribe()
+4.1. rls_handle_subscribe()
 
    This function detects if a Subscribe message should be handled by RLS.
-   If  not  it replies with the configured to_presence_code. If it is, it
-   extracts  the  dialog  info  and  sends aggregate Notify requests with
+   If not it replies with the configured to_presence_code. If it is, it
+   extracts the dialog info and sends aggregate Notify requests with
    information for the list.
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.19. rls_handle_subscribe usage
+   Example 1.20. rls_handle_subscribe usage
 ...
 For presence and rls on the same machine:
         modparam("rls", "to_presence_code", 10)
@@ -449,30 +463,30 @@ For rls only:
 
 ...
 
-4.2.  rls_handle_notify()
+4.2. rls_handle_notify()
 
    This function can be used from REQUEST_ROUTE.
 
-   Example 1.20. rls_handle_notify usage
+   Example 1.21. rls_handle_notify usage
 ...
 if(method=="NOTIFY")
     rls_handle_notify();
 ...
 
-4.3.  rls_update_subs(uri, event)
+4.3. rls_update_subs(uri, event)
 
-   This  function  can  be  used  in  configuration to trigger updates to
-   resource  list  subscriptions  (for  example,  after the contents of a
+   This function can be used in configuration to trigger updates to
+   resource list subscriptions (for example, after the contents of a
    resource list has changes).
 
    Parameters:
-     * uri  -  the uri of the user who made the change and whose resource
+     * uri - the uri of the user who made the change and whose resource
        list subscriptions should be updated
      * event - the event package (e.g. presence).
 
    This function can be used from ANY_ROUTE.
 
-   Example 1.21. rls_update_subs usage
+   Example 1.22. rls_update_subs usage
 ...
 Within event_route[xhttp:request]:
         case "PUT":
@@ -490,10 +504,10 @@ Within event_route[xhttp:request]:
 
 5. Installation
 
-   The  module requires 2 tables in Kamailio database: rls_presentity and
-   rls_watchers.The   SQL   syntax   to  create  them  can  be  found  in
-   rls-create.sql   script   in   the   database   directories   in   the
-   kamailio/scripts  folder.  You  can  also  find  the complete database
+   The module requires 2 tables in Kamailio database: rls_presentity and
+   rls_watchers.The SQL syntax to create them can be found in
+   rls-create.sql script in the database directories in the
+   kamailio/scripts folder. You can also find the complete database
    documentation on the project webpage,
    http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.