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. server_address (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 server_address 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. 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 messages for RLS. It is compulsory.

Example 1.11. Set server_address parameter

...
modparam("rls", "server_address", "sip:rls@opensips.org:5060")
...
		

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(method=="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:

:rls_update_subscriptions:fifo_reply
sip:alice@atlanta.com
_empty_line_
	

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, http://www.opensips.org/html/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)

 NameDevScoreCommitsLines ++Lines --
1. Anca Vamanu99415335863
2. Saúl Ibarra Corretgé (@saghul)41181150710
3. Bogdan-Andrei Iancu (@bogdan-iancu)22196999
4. Daniel-Constantin Mierla (@miconda)971815
5. Liviu Chircu (@liviuchircu)963857
6. Henning Westerholt (@henningw)83164114
7. Razvan Crainea (@razvancrainea)641215
8. Dan Pascu (@danpascu)6436
9. Vlad Paiu (@vladpaiu)531141
10. Walter Doekes (@wdoekes)4299

All remaining contributors: Stanislaw Pitucha, Ovidiu Sas (@ovidiusas), Sergio Gutierrez, Konstantin Bokarius, UnixDev, John Riordan, Julián Moreno Patiño, 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

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Jan 2008 - Jun 2018
2. Liviu Chircu (@liviuchircu)Mar 2014 - Jun 2018
3. Razvan Crainea (@razvancrainea)Feb 2012 - Nov 2016
4. Julián Moreno PatiñoFeb 2016 - Feb 2016
5. Ovidiu Sas (@ovidiusas)Jan 2013 - Jan 2013
6. Saúl Ibarra Corretgé (@saghul)Oct 2012 - Jan 2013
7. Vlad Paiu (@vladpaiu)Aug 2011 - Mar 2012
8. Anca VamanuSep 2007 - Jan 2012
9. Stanislaw PituchaJul 2010 - Jul 2010
10. Walter Doekes (@wdoekes)Apr 2010 - Apr 2010

All remaining contributors: John Riordan, UnixDev, Dan Pascu (@danpascu), 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: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Saúl Ibarra Corretgé (@saghul), Razvan Crainea (@razvancrainea), Walter Doekes (@wdoekes), Anca Vamanu, Dan Pascu (@danpascu), Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert.

doc copyrights:

Copyright © 2007 Voice Sistem SRL