Presence_XML Module
     __________________________________________________________

   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. force_active (int)
              1.3.2. pidf_manipulation (int)
              1.3.3. xcap_server (str)
              1.3.4. pres_rules_auid (str)
              1.3.5. pres_rules_filename (str)
              1.3.6. generate_offline_body (str)

        1.4. Exported Functions
        1.5. 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 force_active parameter
   1.2. Set pidf_manipulation parameter
   1.3. Set xcap_server parameter
   1.4. Set pres_rules_auid parameter
   1.5. Set pres_rules_filename parameter
   1.6. Set generate_offline_body parameter

Chapter 1. Admin Guide

1.1. Overview

   The module does specific handling for notify-subscribe events
   using xml bodies. It is used with the general event handling
   module, presence. It constructs and adds 3 events to it:
   presence, presence.winfo, dialog;sla.

   This module takes the xcap permission rule documents from
   xcap_table. The presence permission rules are interpreted
   according to the specifications in RFC 4745 and RFC 5025.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * a database module.
     * presence.
     * signaling.
     * xcap.
     * xcap_client.
       Only compulsory if not using an integrated xcap server (if
       'integrated_xcap_server' parameter is not set).

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libxml-dev.

1.3. Exported Parameters

1.3.1. force_active (int)

   This parameter is used for permissions when handling Subscribe
   messages. If set to 1, subscription state is considered active
   and the presentity is not queried for permissions(should be set
   to 1 if not using an xcap server). Otherwise,the xcap server is
   queried and the subscription states is according to user
   defined permission rules. If no rules are defined for a certain
   watcher, the subscriptions remains in pending state and the
   Notify sent will have no body.

   Note: When switching from one value to another, the watchers
   table must be emptied.

   Default value is “0”.

   Example 1.1. Set force_active parameter
...
modparam("presence_xml", "force_active", 1)
...

1.3.2. pidf_manipulation (int)

   Setting this parameter to 1 enables the features described in
   RFC 4827. It gives the possibility to have a permanent state
   notified to the users even in the case in which the phone is
   not online. The presence document is taken from the xcap server
   and aggregated together with the other presence information, if
   any exist, for each Notify that is sent to the watchers. It is
   also possible to have information notified even if not issuing
   any Publish (useful for services such as email, SMS, MMS).

   Default value is “0”.

   Example 1.2. Set pidf_manipulation parameter
...
modparam("presence_xml", "pidf_manipulation", 1)
...

1.3.3. xcap_server (str)

   The address of the xcap servers used for storage. This
   parameter is compulsory if the integrated_xcap_server parameter
   is not set. It can be set more that once, to construct an
   address list of trusted XCAP servers.

   Example 1.3. Set xcap_server parameter
...
modparam("presence_xml", "xcap_server", "xcap_server.example.org")
modparam("presence_xml", "xcap_server", "xcap_server.ag.org")
...

1.3.4. pres_rules_auid (str)

   This parameter should be configured if you are using the non
   integrated xcap mode and you need to use another pres-rules
   auid than the default 'pres-rules'.

   Example 1.4. Set pres_rules_auid parameter
...
modparam("presence_xml", "pres_rules_auid", "org.openmobilealliance.pres
-rules")
...

1.3.5. pres_rules_filename (str)

   This parameter should be configured if you are using the non
   integrated xcap mode and you need to configure another filename
   than the default 'index'.

   Example 1.5. Set pres_rules_filename parameter
...
modparam("presence_xml", "pres_rules_filename", "pres-rules")
...

1.3.6. generate_offline_body (str)

   This parameter should be set to 0 if you want to prevent
   OpenSIPS from automatically generating a PIDF body when a
   publication expires or is explicitly terminated (a PUBLISH
   request is received with Expires: 0).

   Example 1.6. Set generate_offline_body parameter
...
modparam("presence_xml", "generate_offline_body", 0)
...

1.4. Exported Functions

   None to be used in configuration file.

1.5. Installation

   The module requires 1 table in OpenSIPS database: xcap. The SQL
   syntax to create it can be found in presence-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 exports no function 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 124 54 4745 1776
   2. Saúl Ibarra Corretgé (@saghul) 30 9 1499 471
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 27 23 78 128
   4. Razvan Crainea (@razvancrainea) 15 13 40 32
   5. Liviu Chircu (@liviuchircu) 14 11 45 71
   6. Daniel-Constantin Mierla (@miconda) 8 6 15 14
   7. Henning Westerholt (@henningw) 6 4 45 50
   8. Maksym Sobolyev (@sobomax) 4 2 4 4
   9. Dan Pascu (@danpascu) 4 2 3 3
   10. Ovidiu Sas (@ovidiusas) 3 2 6 0

   All remaining contributors: Kennard White, Vlad Paiu
   (@vladpaiu), Walter Doekes (@wdoekes), Konstantin Bokarius,
   Alexandra Titoc, Peter Lemenkov (@lemenkov), UnixDev, Zero King
   (@l2dy), Edson Gellert Schubert, Denis Bilenko, Vlad Patrascu
   (@rvlad-patrascu).

   (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.  Alexandra Titoc                     Sep 2024 - Sep 2024
   2.  Liviu Chircu (@liviuchircu)         Mar 2014 - May 2024
   3.  Maksym Sobolyev (@sobomax)          Feb 2023 - Feb 2023
   4.  Razvan Crainea (@razvancrainea)     Feb 2012 - Jul 2020
   5.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2007 - Mar 2020
   6.  Zero King (@l2dy)                   Mar 2020 - Mar 2020
   7.  Dan Pascu (@danpascu)               Oct 2007 - Nov 2018
   8.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   9.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - May 2017
   10. Saúl Ibarra Corretgé (@saghul)      May 2012 - Mar 2013

   All remaining contributors: Anca Vamanu, Vlad Paiu (@vladpaiu),
   Ovidiu Sas (@ovidiusas), Kennard White, Walter Doekes
   (@wdoekes), UnixDev, Denis Bilenko, 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: Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Bogdan-Andrei Iancu (@bogdan-iancu), Saúl
   Ibarra Corretgé (@saghul), Razvan Crainea (@razvancrainea),
   Anca Vamanu, Henning Westerholt (@henningw), Daniel-Constantin
   Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert,
   Dan Pascu (@danpascu).

   Documentation Copyrights:

   Copyright © 2007 Voice Sistem SRL
