Resource List Server
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. rlsubs_table(str)
              1.3.2. rlpres_table(str)
              1.3.3. clean_period (int)
              1.3.4. waitn_time (int)
              1.3.5. max_expires (int)
              1.3.6. hash_size (int)
              1.3.7. xcap_root (str)
              1.3.8. to_presence_code (int)
              1.3.9. rls_event (str)
              1.3.10. presence_server (str)
              1.3.11. contact_user (str)

        1.4. Exported Functions

              1.4.1. rls_handle_subscribe()
              1.4.2. rls_handle_notify()

        1.5. Exported MI Functions

              1.5.1. rls_update_subscriptions

        1.6. Installation

   2. Developer Guide
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set rlsubs_table parameter
   1.2. Set rlpres_table parameter
   1.3. Set clean_period parameter
   1.4. Set waitn_time parameter
   1.5. Set max_expires parameter
   1.6. Set hash_size parameter
   1.7. Set hash_size parameter
   1.8. Set to_presence_code parameter
   1.9. Set rls_event parameter
   1.10. Set presence_server parameter
   1.11. Set contact_user parameter
   1.12. rls_handle_subscribe usage
   1.13. rls_handle_notify usage

Chapter 1. Admin Guide

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

1.2. Dependencies

1.2.1. OpenSIPS Modules

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

1.2.2. External Libraries or Applications

     * libxml-dev.

1.3. Exported Parameters

1.3.1. rlsubs_table(str)

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

   Default value is “rls_watchers”.

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

1.3.2. rlpres_table(str)

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

   Default value is “rls_presentity”.

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

1.3.3. clean_period (int)

   The period at which to check for expired information.

   Default value is “100”.

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

1.3.4. 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.4. Set waitn_time parameter
...
modparam("rls", "waitn_time", 10)
...

1.3.5. max_expires (int)

   The maximum accepted expires for a subscription to a list.

   Default value is “7200”.

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

1.3.6. 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.6. Set hash_size parameter
...
modparam("rls", "hash_size", 11)
...

1.3.7. xcap_root (str)

   The address of the xcap server.

   Default value is “NULL”.

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

1.3.8. 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.8. Set to_presence_code parameter
...
modparam("rls", "to_presence_code", 10)
...

1.3.9. 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.9. Set rls_event parameter
...
modparam("rls", "rls_event", "dialog;sla")
...

1.3.10. presence_server (str)

   The address of the presence server. It will be used as outbound
   proxy for Subscribe requests sent by the RLS server to bouncing
   on and off the proxy and having to include special processing
   for this messages in the proxy's configuration file.

   Example 1.10. Set presence_server parameter
...
modparam("rls", "presence_server", "sip:pres@opensips.org:5060")
...

1.3.11. contact_user (str)

   This is the username that will be used in the Contact header
   for the 200 OK replies to SUBSCRIBE and in the following
   in-dialog NOTIFY requests, as well as for the SUBSCRIBE
   requests that are generated by the RLS server. The IP address,
   port and transport for the Contact will be automatically
   determined based on the interface where the SUBSCRIBE was
   received or sent from.

   If set to an empty string, no username will be added to the
   contact and the contact will be built just out of the IP, port
   and transport.

   Default value is “rls”.

   Example 1.11. Set contact_user parameter
...
modparam("rls", "contact_user", "rls")
...

1.4. Exported Functions

1.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.12. 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();
        }

...

1.4.2.  rls_handle_notify()

   This function has to be called for Notify messages sent by
   presence servers in reply to the Subscribe messages sent by
   RLS.

   This function can be used from REQUEST_ROUTE.

   It can return 3 codes:
     * 1 - the Notify was inside a dialog that was recognized by
       the RLS server and was processed successfully.
     * 2 - the Notify did not belog to a dialog initiated by the
       RLS server.
     * -1 - an error occurred during processing.

   Example 1.13. rls_handle_notify usage
...
if($rm=="NOTIFY")
    rls_handle_notify();
...

1.5. Exported MI Functions

1.5.1.  rls_update_subscriptions

   Triggers updating backend subscriptions after a resources-list
   or rls-services document has been updated.

   Name: rls_update_subscriptions

   Parameters:
     * presentity_uri : the uri of the user who made the change
       and whose subscriptions should be updated

   MI FIFO Command Format:
opensips-cli -x mi rls_update_subscriptions sip:alice@atlanta.com

1.6. Installation

   The module requires 2 table in OpenSIPS 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 opensips/scripts folder. You can also find
   the complete database documentation on the project webpage,
   https://opensips.org/docs/db/db-schema-devel.html.

Chapter 2. Developer Guide

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

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Anca Vamanu 101 41 5335 863
   2. Saúl Ibarra Corretgé (@saghul) 40 18 1150 710
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 25 21 110 137
   4. Dan Pascu (@danpascu) 15 10 127 138
   5. Razvan Crainea (@razvancrainea) 14 12 20 38
   6. Liviu Chircu (@liviuchircu) 14 11 58 79
   7. Daniel-Constantin Mierla (@miconda) 9 7 18 15
   8. Vlad Patrascu (@rvlad-patrascu) 7 5 28 35
   9. Henning Westerholt (@henningw) 7 3 164 114
   10. Vlad Paiu (@vladpaiu) 5 3 11 41

   All remaining contributors: Walter Doekes (@wdoekes), Maksym
   Sobolyev (@sobomax), Stanislaw Pitucha, Ovidiu Sas
   (@ovidiusas), Sergio Gutierrez, Konstantin Bokarius, UnixDev,
   John Riordan, Julián Moreno Patiño, Peter Lemenkov (@lemenkov),
   Edson Gellert Schubert.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   2.  Maksym Sobolyev (@sobomax)          Feb 2023 - Nov 2023
   3.  Razvan Crainea (@razvancrainea)     Feb 2012 - Jul 2020
   4.  Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2008 - Mar 2020
   5.  Dan Pascu (@danpascu)               Aug 2008 - Jul 2019
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   7.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   8.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   9.  Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013
   10. Saúl Ibarra Corretgé (@saghul)      Oct 2012 - Jan 2013

   All remaining contributors: Vlad Paiu (@vladpaiu), Anca Vamanu,
   Stanislaw Pitucha, Walter Doekes (@wdoekes), John Riordan,
   UnixDev, Sergio Gutierrez, Henning Westerholt (@henningw),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert.

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Dan Pascu (@danpascu), Razvan Crainea
   (@razvancrainea), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Vlad Patrascu (@rvlad-patrascu), Bogdan-Andrei
   Iancu (@bogdan-iancu), Saúl Ibarra Corretgé (@saghul), Walter
   Doekes (@wdoekes), Anca Vamanu, Henning Westerholt (@henningw),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert.

   Documentation Copyrights:

   Copyright © 2007 Voice Sistem SRL
