kamailio/modules_k/rls/README

Resource List Server

Anca-Maria Vamanu

   Voice Sistem SRL

Edited by

Anca-Maria Vamanu

   Copyright © 2007 Voice Sistem SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. db_url(str)
              3.2. xcap_table(str)
              3.3. rlsubs_table(str)
              3.4. rlpres_table(str)
              3.5. clean_period (int)
              3.6. waitn_time (int)
              3.7. max_expires (int)
              3.8. hash_size (int)
              3.9. xcap_root (str)
              3.10. integrated_xcap_server (int)
              3.11. to_presence_code (int)
              3.12. rls_event (str)
              3.13. outbound_proxy (str)
              3.14. server_address (str)
              3.15. max_notify_body_length (int)

        4. Functions

              4.1. rls_handle_subscribe()
              4.2. rls_handle_notify()
              4.3. rls_update_subs(uri, event)

        5. Installation

   2. Developer Guide

   List of Examples

   1.1. Set db_url parameter
   1.2. Set xcap_table parameter
   1.3. Set rlsubs_table parameter
   1.4. Set rlpres_table parameter
   1.5. Set clean_period parameter
   1.6. Set waitn_time parameter
   1.7. Set max_expires parameter
   1.8. Set hash_size parameter
   1.9. Set hash_size parameter
   1.10. Set integrated_xcap_server parameter
   1.11. Set to_presence_code parameter
   1.12. Set rls_event parameter
   1.13. Set outbound_proxy parameter
   1.14. Set server_address parameter
   1.15. Set max_notify_body_length parameter
   1.16. rls_handle_subscribe usage
   1.17. rls_handle_notify usage
   1.18. rls_update_subs usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. db_url(str)
        3.2. xcap_table(str)
        3.3. rlsubs_table(str)
        3.4. rlpres_table(str)
        3.5. clean_period (int)
        3.6. waitn_time (int)
        3.7. max_expires (int)
        3.8. hash_size (int)
        3.9. xcap_root (str)
        3.10. integrated_xcap_server (int)
        3.11. to_presence_code (int)
        3.12. rls_event (str)
        3.13. outbound_proxy (str)
        3.14. server_address (str)
        3.15. max_notify_body_length (int)

   4. Functions

        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
   specification in RFC 4662 and RFC 4826.

   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
   (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
   "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.

   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

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * a database module.
     * sl.
     * tm.
     * presence- in a library mode.
     * pua.

2.2. External Libraries or Applications

     * libxml.

3. Parameters

   3.1. db_url(str)
   3.2. xcap_table(str)
   3.3. rlsubs_table(str)
   3.4. rlpres_table(str)
   3.5. clean_period (int)
   3.6. waitn_time (int)
   3.7. max_expires (int)
   3.8. hash_size (int)
   3.9. xcap_root (str)
   3.10. integrated_xcap_server (int)
   3.11. to_presence_code (int)
   3.12. rls_event (str)
   3.13. outbound_proxy (str)
   3.14. server_address (str)
   3.15. max_notify_body_length (int)

3.1. db_url(str)

   The database url.

   Default value is “mysql://openser:openserrw@localhost/openser”.

   Example 1.1. Set db_url parameter
...
modparam("rls", "db_url", "dbdriver://username:password@dbhost/dbname")
...

3.2. 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
   xcap_client module.

   Default value is “xcap”.

   Example 1.2. Set xcap_table parameter
...
modparam("rls", "xcap_table", "xcaps");
...

3.3. rlsubs_table(str)

   The name of the db table where resource lists subscription information
   is stored.

   Default value is “rls_watchers”.

   Example 1.3. Set rlsubs_table parameter
...
modparam("rls", "rlsubs_table", "rls_subscriptions")
...

3.4. rlpres_table(str)

   The name of the db table where notified event specific information is
   stored.

   Default value is “rls_presentity”.

   Example 1.4. Set rlpres_table parameter
...
modparam("rls", "rlpres_table", "rls_notify")
...

3.5. clean_period (int)

   The period at which to check for expired information.

   Default value is “100”.

   Example 1.5. Set clean_period parameter
...
modparam("rls", "clean_period", 100)
...

3.6. 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
   information.

   Default value is “50”.

   Example 1.6. Set waitn_time parameter
...
modparam("rls", "waitn_time", 10)
...

3.7. max_expires (int)

   The maximum accepted expires for a subscription to a list.

   Default value is “7200”.

   Example 1.7. Set max_expires parameter
...
modparam("rls", "max_expires", 10800)
...

3.8. 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
   size.

   Default value is “9 (512)”.

   Example 1.8. Set hash_size parameter
...
modparam("rls", "hash_size", 11)
...

3.9. xcap_root (str)

   The address of the xcap server.

   Default value is “NULL”.

   Example 1.9. Set hash_size parameter
...
modparam("rls", "xcap_root", "http://192.168.2.132/xcap-root:800")
...

3.10. integrated_xcap_server (int)

   This parameter should be set if only integrated xcap servers are used
   to store resource lists.

   Default value is “0”.

   Example 1.10. Set integrated_xcap_server parameter
...
modparam("rls", "integrated_xcap_server", 1)
...

3.11. to_presence_code (int)

   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
   code.

   Default value is “0”.

   Example 1.11. Set to_presence_code parameter
...
modparam("rls", "to_presence_code", 10)
...

3.12. 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
   parameter. It can be set more than once.

   Default value is “"presence"”.

   Example 1.12. Set rls_event parameter
...
modparam("rls", "rls_event", "dialog;sla")
...

3.13. outbound_proxy (str)

   The SIP address where to send RLS subscriptions (outbound proxy address
   as SIP URI).

   Default value is “NULL”.

   Example 1.13. Set outbound_proxy parameter
...
modparam("rls", "outbound_proxy", "sip:presence.kamailio.org")
...

3.14. 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.
   It is a mandatory parameter.

   Example 1.14. Set server_address parameter
...
modparam("rls", "server_address", "sip:[email protected]:5060")
...

3.15. max_notify_body_length (int)

   The maximum size that the body of a NOTIFY message may be. If set to 0
   (the default), no size limit is applied. Note that this refers only to
   the body, not the complete NOTIFY message.

   Example 1.15. Set max_notify_body_length parameter
...
modparam("rls", "max_notify_body_length", 32000)
...

4. Functions

   4.1. rls_handle_subscribe()
   4.2. rls_handle_notify()
   4.3. rls_update_subs(uri, event)

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
   information for the list.

   This function can be used from REQUEST_ROUTE.

   Example 1.16. rls_handle_subscribe usage
...
For presence and rls on the same machine:
        modparam("rls", "to_presence_code", 10)

        if(is_method("SUBSCRIBE"))
        {
                $var(ret_code)= rls_handle_subscribe();

                if($var(ret_code)== 10)
                                handle_subscribe();

                t_release();
        }

For rls only:
        if(is_method("SUBSCRIBE"))
        {
                rls_handle_subscribe();
                t_release();
        }

...

4.2.  rls_handle_notify()

   This function can be used from REQUEST_ROUTE.

   Example 1.17. rls_handle_notify usage
...
if(method=="NOTIFY")
    rls_handle_notify();
...

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
   resource list has changes).

   Parameters:
     * 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.18. rls_update_subs usage
...
Within event_route[xhttp:request]:
        case "PUT":
                xcaps_put("$var(uri)", "$var(doc_uri)", "$rb");
                if($xcapuri(u=>auid)=~"pres-rules") {
                        pres_update_watchers("$var(uri)", "presence");
                        pres_refresh_watchers("$var(uri)", "presence", 1);
                } else if ($xcapuri(u=>auid)=~"resource-lists"
                           || $xcapuri(u=>auid)=~"rls-services") {
                        rls_update_subs("$var(uri)", "presence");
                }
                exit;
                break;
...

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
   documentation on the project webpage,
   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.

Chapter 2. Developer Guide

   The module provides no functions to be used in other Kamailio modules.