pua: regenerated the readme file

modules_k/pua/README

@@ -1,4 +1,3 @@
-
 Presence User Agent Module
 
 Anca-Maria Vamanu
@@ -10,7 +9,7 @@ Edited by
 Anca-Maria Vamanu
 
    Copyright © 2006 Voice Sistem SRL
-     _________________________________________________________________
+     __________________________________________________________________
 
    Table of Contents
 
@@ -35,21 +34,22 @@ Anca-Maria Vamanu
               3.9. reginfo_increase_version (int)
               3.10. db_mode (int)
               3.11. check_remote_contact (int)
+              3.12. fetch_rows (integer)
 
         4. Functions
 
-              4.1. pua_update_contact() 
+              4.1. pua_update_contact()
 
         5. Installation
 
    2. Developer Guide
 
-        1. bind_pua(pua_api_t* api) 
-        2. send_publish 
-        3. send_subscribe 
-        4. is_dialog 
-        5. register_puacb 
-        6. add_event 
+        1. bind_pua(pua_api_t* api)
+        2. send_publish
+        3. send_subscribe
+        4. is_dialog
+        5. register_puacb
+        6. add_event
 
    List of Examples
 
@@ -64,7 +64,8 @@ Anca-Maria Vamanu
    1.9. Set reginfo_increase_version parameter
    1.10. Set db_mode parameter
    1.11. Set check_remote_contact parameter
-   1.12. pua_update_contact usage
+   1.12. Set fetch_rows parameter
+   1.13. pua_update_contact usage
    2.1. pua_api structure
    2.2. pua_is_dialog usage example
    2.3. register_puacb usage example
@@ -93,38 +94,37 @@ Chapter 1. Admin Guide
         3.9. reginfo_increase_version (int)
         3.10. db_mode (int)
         3.11. check_remote_contact (int)
+        3.12. fetch_rows (integer)
 
    4. Functions
 
-        4.1. pua_update_contact() 
+        4.1. pua_update_contact()
 
    5. Installation
 
 1. Overview
 
-   This  module  offer the functionality of a presence user agent client,
+   This module offer the functionality of a presence user agent client,
    sending Subscribe and Publish messages. It's a core part of Kamailio's
-   SIP  presence  package,  implementing  SIMPLE  and various shared line
+   SIP presence package, implementing SIMPLE and various shared line
    appearance implementations.
 
-   It  can  be  used  with  the following modules: pua_mi and pua_usrloc,
-   pua_bla  and  pua_xmpp.  The  <emphasize>pua_mi</emphasize>  offer the
-   possibility  to  publish  any  kind of information or subscribing to a
-   resource through the manager interface. The
-   <emphasize>pua_usrloc</emphasize>  module calls a function exported by
-   pua  modules to publish elementary presence information, such as basic
-   status   "open"  or  "closed",  for  clients  that  do  not  implement
-   client-to-server  presence.  Through  <emphasize>pua_bla</emphasize> ,
-   BRIDGED   LINE   APPEARANCE   features   are  added  to  openser.  The
-   <emphasize>pua_xmpp</emphasize>  module  represents  a gateway between
-   SIP  and  XMPP,  so  that jabber and SIP clients can exchange presence
-   information.
+   It can be used with the following modules: pua_mi and pua_usrloc,
+   pua_bla and pua_xmpp. The pua_mi offer the possibility to publish any
+   kind of information or subscribing to a resource through the manager
+   interface. The pua_usrloc module calls a function exported by pua
+   modules to publish elementary presence information, such as basic
+   status "open" or "closed", for clients that do not implement
+   client-to-server presence. Through pua_bla , BRIDGED LINE APPEARANCE
+   features are added to openser. The pua_xmpp module represents a gateway
+   between SIP and XMPP, so that jabber and SIP clients can exchange
+   presence information.
 
    The module supports 2 modes of operation. In the first a cache is used
-   to  store  the  presentity  list and writes to database on timer to be
-   able  to  recover  upon restart. The presence is kept in-memory during
+   to store the presentity list and writes to database on timer to be able
+   to recover upon restart. The presence is kept in-memory during
    run-time. The second is a database only mode where the presentity list
-   is  stored  purely  in  a  database,  allowing  both  scalability  and
+   is stored purely in a database, allowing both scalability and
    resilience.
 
 2. Dependencies
@@ -140,7 +140,7 @@ Chapter 1. Admin Guide
 
 2.2. External Libraries or Applications
 
-   The  following  libraries  or  applications  must  be installed before
+   The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * libxml.
 
@@ -157,14 +157,15 @@ Chapter 1. Admin Guide
    3.9. reginfo_increase_version (int)
    3.10. db_mode (int)
    3.11. check_remote_contact (int)
+   3.12. fetch_rows (integer)
 
 3.1. hash_size (int)
 
-   The  size  of  the  hash  table used for storing Subscribe and Publish
-   information.  This  parameter  will  be  used  as  the power of 2 when
+   The size of the hash table used for storing Subscribe and Publish
+   information. This parameter will be used as the power of 2 when
    computing table size.
 
-   Default value is "9". 
+   Default value is "9".
 
    Example 1.1. Set hash_size parameter
 ...
@@ -175,7 +176,7 @@ modparam("pua", "hash_size", 11)
 
    Database url.
 
-   Default value is ">mysql://openser:openserrw@localhost/openser". 
+   Default value is ">mysql://openser:openserrw@localhost/openser".
 
    Example 1.2. Set db_url parameter
 ...
@@ -186,7 +187,7 @@ modparam("pua", "db_url" "dbdriver://username:password@dbhost/dbname")
 
    The name of the database table.
 
-   Default value is "pua". 
+   Default value is "pua".
 
    Example 1.3. Set db_table parameter
 ...
@@ -197,7 +198,7 @@ modparam("pua", "db_table", "pua")
 
    The inferior expires limit for both Publish and Subscribe.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.4. Set min_expires parameter
 ...
@@ -206,10 +207,10 @@ modparam("pua", "min_expires", 0)
 
 3.5. default_expires (int)
 
-   The  default  expires  value  used  in  case  this  information is not
+   The default expires value used in case this information is not
    provisioned.
 
-   Default value is "3600". 
+   Default value is "3600".
 
    Example 1.5. Set default_expires parameter
 ...
@@ -218,12 +219,12 @@ modparam("pua", "default_expires", 3600)
 
 3.6. update_period (int)
 
-   The  interval  at  which  the  information  in database and hash table
-   should  be  updated.  In  the  case  of  the hash table updating means
-   deleting expired messages. Setting a value less than or equal to zero,
-   disables updates.
+   The interval at which the information in database and hash table should
+   be updated. In the case of the hash table updating means deleting
+   expired messages. Setting a value less than or equal to zero, disables
+   updates.
 
-   Default value is "100". 
+   Default value is "100".
 
    Example 1.6. Set update_period parameter
 ...
@@ -234,7 +235,7 @@ modparam("pua", "update_period", 100)
 
    SIP URI of outbound proxy to be used when sending PUBLISH requests.
 
-   By default, no outbound proxy has been defined. 
+   By default, no outbound proxy has been defined.
 
    Example 1.7. Set outbound_proxy parameter
 ...
@@ -243,16 +244,16 @@ modparam("pua", "outbound_proxy", "sip:outbound.example.com")
 
 3.8. dlginfo_increase_version (int)
 
-   When  sending  PUBLISHs  for  Event:  dialog, the body contains an XML
-   document  according  to RFC 4235. This XML document contains a version
-   attribute  to  easily  detect  changes in the dialog state. By setting
-   this  parameter,  the  pua module parses the XML document and sets the
-   version  attribute to the proper value. If the receiver of the PUBLISH
-   does  not  care  about  the  version  parameter  (e.g.  like  Kamailio
-   presence_dialoginfo  module)  it makes no sense to waste CPU resources
+   When sending PUBLISHs for Event: dialog, the body contains an XML
+   document according to RFC 4235. This XML document contains a version
+   attribute to easily detect changes in the dialog state. By setting this
+   parameter, the pua module parses the XML document and sets the version
+   attribute to the proper value. If the receiver of the PUBLISH does not
+   care about the version parameter (e.g. like Kamailio
+   presence_dialoginfo module) it makes no sense to waste CPU resources
    for parsing the XML body and the parameter should be set to 0.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.8. Set dlginfo_increase_version parameter
 ...
@@ -261,16 +262,16 @@ modparam("pua", "dlginfo_increase_version", 1)
 
 3.9. reginfo_increase_version (int)
 
-   When  sending  PUBLISHs  for  Event:  reg,  the  body  contains an XML
-   document  according  to  RFC  4235(?).  This  XML  document contains a
-   version  attribute to easily detect changes in the registration state.
-   By  setting this parameter, the pua module parses the XML document and
-   sets the version attribute to the proper value. If the receiver of the
-   PUBLISH  does not care about the version parameter (e.g. like Kamailio
-   presence_reginfo  module) it makes no sense to waste CPU resources for
+   When sending PUBLISHs for Event: reg, the body contains an XML document
+   according to RFC 4235(?). This XML document contains a version
+   attribute to easily detect changes in the registration state. By
+   setting this parameter, the pua module parses the XML document and sets
+   the version attribute to the proper value. If the receiver of the
+   PUBLISH does not care about the version parameter (e.g. like Kamailio
+   presence_reginfo module) it makes no sense to waste CPU resources for
    parsing the XML body and the parameter should be set to 0.
 
-   Default value is "0". 
+   Default value is "0".
 
    Example 1.9. Set reginfo_increase_version parameter
 ...
@@ -279,12 +280,12 @@ modparam("pua", "reginfo_increase_version", 1)
 
 3.10. 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.10. Set db_mode parameter
 ...
@@ -297,30 +298,40 @@ modparam("pua", "db_mode", 0)
    in the stored dialog or not. If the remote contact is checked and does
    not match the one in the stored dialog then the dialog is not matched.
    Checking the remote contact can cause problems when using modules like
-   RLS  and  should not be required in order to properly match the dialog
-   anyway.  Set this parameter to 0 to disable checking of remote contact
+   RLS and should not be required in order to properly match the dialog
+   anyway. Set this parameter to 0 to disable checking of remote contact
    for SUBSCRIBE dialog matching.
 
-   Default value is "1". 
+   Default value is "1".
 
    Example 1.11. Set check_remote_contact parameter
 ...
 modparam("pua", "check_remote_contact", 0)
 ...
 
+3.12. fetch_rows (integer)
+
+   Number of rows to be loaded in one step from database.
+
+   Default value is 500.
+
+   Example 1.12. Set fetch_rows parameter
+...
+modparam("pua", "fetch_rows", 1000)
+...
+
 4. Functions
 
-   4.1. pua_update_contact() 
+   4.1. pua_update_contact()
 
-4.1.  pua_update_contact()
+4.1. pua_update_contact()
 
-   The  remote  target  can  be updated by the Contact of a subsequent in
-   dialog   request.  In  the  PUA  watcher  case  (sending  a  SUBSCRIBE
-   messages),  this  means  that  the  remote  target  for  the following
-   Subscribe  messages  can  be  updated  at any time by the contact of a
-   Notify  message.  If  this  function  is  called  on  request route on
-   receiving  a  Notify  message, it will try to update the stored remote
-   target.
+   The remote target can be updated by the Contact of a subsequent in
+   dialog request. In the PUA watcher case (sending a SUBSCRIBE messages),
+   this means that the remote target for the following Subscribe messages
+   can be updated at any time by the contact of a Notify message. If this
+   function is called on request route on receiving a Notify message, it
+   will try to update the stored remote target.
 
    This function can be used from REQUEST_ROUTE.
 
@@ -328,7 +339,7 @@ modparam("pua", "check_remote_contact", 0)
      * 1 - if success.
      * -1 - if error.
 
-   Example 1.12. pua_update_contact usage
+   Example 1.13. pua_update_contact usage
 ...
 if(method=="NOTIFY")
     pua_update_contact();
@@ -336,29 +347,29 @@ if(method=="NOTIFY")
 
 5. Installation
 
-   The  module  requires one table in the Kamailio database: pua. The SQL
-   syntax  to create it can be found in presence_xml-create.sql script in
-   the  database directories in the kamailio/scripts folder. You can also
-   find  the  complete  database  documentation  on  the project webpage,
+   The module requires one table in the Kamailio database: pua. The SQL
+   syntax to create it can be found in presence_xml-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.
 
 Chapter 2. Developer Guide
 
    Table of Contents
 
-   1. bind_pua(pua_api_t* api) 
-   2. send_publish 
-   3. send_subscribe 
-   4. is_dialog 
-   5. register_puacb 
-   6. add_event 
+   1. bind_pua(pua_api_t* api)
+   2. send_publish
+   3. send_subscribe
+   4. is_dialog
+   5. register_puacb
+   6. add_event
 
-   The  module provides the following functions that can be used by other
+   The module provides the following functions that can be used by other
    Kamailio modules.
 
-1.  bind_pua(pua_api_t* api)
+1. bind_pua(pua_api_t* api)
 
-   This  function  binds the pua modules and fills the structure with the
+   This function binds the pua modules and fills the structure with the
    two exported functions.
 
    Example 2.1. pua_api structure
@@ -372,15 +383,15 @@ typedef struct pua_api {
 } pua_api_t;
 ...
 
-2.  send_publish
+2. send_publish
 
    Field type:
 ...
 typedef int (*send_publish_t)(publ_info_t* publ);
 ...
 
-   This  function  receives  as  a  parameter  a  structure  with Publish
-   required information and sends a Publish message.
+   This function receives as a parameter a structure with Publish required
+   information and sends a Publish message.
 
    The structure received as a parameter:
 ...
@@ -412,14 +423,14 @@ typedef struct publ_info
 }publ_info_t;
 ...
 
-3.  send_subscribe
+3. send_subscribe
 
    Field type:
 ...
 typedef int (*send_subscribe_t)(subs_info_t* subs);
 ...
 
-   This  function  receives  as  a  parameter  a structure with Subscribe
+   This function receives as a parameter a structure with Subscribe
    required information and sends a Subscribe message.
 
    The structure received as a parameter:
@@ -451,15 +462,15 @@ typedef struct subs_info
 }subs_info_t;
 ...
 
-4.  is_dialog
+4. is_dialog
 
    Field type:
 ...
 typedef int  (*query_dialog_t)(ua_pres_t* presentity);
 ...
 
-   This  function  checks  is  the  parameter  corresponds  to  a  stored
-   Subscribe initiated dialog.
+   This function checks is the parameter corresponds to a stored Subscribe
+   initiated dialog.
 
    Example 2.2. pua_is_dialog usage example
 ...
@@ -470,7 +481,7 @@ typedef int  (*query_dialog_t)(ua_pres_t* presentity);
         }
 ...
 
-5.  register_puacb
+5. register_puacb
 
    Field type:
 ...
@@ -478,11 +489,11 @@ typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
 ...
 
    This function registers a callback to be called on receiving the reply
-   message  for  a  sent Publish or Subscribe request. The type parameter
-   should  be  set  the  same  as  the  source_flag for that request. The
-   function  registered  as  callback  for pua should be of type pua_cb ,
+   message for a sent Publish or Subscribe request. The type parameter
+   should be set the same as the source_flag for that request. The
+   function registered as callback for pua should be of type pua_cb ,
    which is: typedef void (pua_cb)(ua_pres_t* hentity, struct msg_start *
-   fl);  The parameters are the dialog structure for that request and the
+   fl); The parameters are the dialog structure for that request and the
    first line of the reply message.
 
    Example 2.3. register_puacb usage example
@@ -499,7 +510,7 @@ typedef int (*register_puacb_t)(int types, pua_cb f, void* param );
 typedef int (pua_cb)(ua_pres_t* hentity, struct sip_msg*);
 ...
 
-6.  add_event
+6. add_event
 
    Field type:
 ...
@@ -515,9 +526,9 @@ typedef int (*add_pua_event_t)(int ev_flag, char* name,
                 (NULL if winfo event)
 ...
 
-   This  function  allows  registering  new events to the pua module. Now
-   there   are   4   events   supported  by  the  pua  module:  presence,
-   presence;winfo,   message-summary,   dialog;sla.   These   events  are
+   This function allows registering new events to the pua module. Now
+   there are 4 events supported by the pua module: presence,
+   presence;winfo, message-summary, dialog;sla. These events are
    registered from within the pua module.
 
    Filed type for process_body: