Presence User Agent for XMPP (Presence gateway between SIP and XMPP)
     __________________________________________________________

   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. server_address(str)
              1.3.2. presence_server (str)

        1.4. Exported Functions

              1.4.1. pua_xmpp_notify()
              1.4.2. pua_xmpp_req_winfo(request_uri, expires)

        1.5. Filtering

   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 server_address parameter
   1.2. Set presence_server parameter
   1.3. Notify2Xmpp usage
   1.4. xmpp_send_winfo usage

Chapter 1. Admin Guide

1.1. Overview

   This module is a gateway for presence between SIP and XMPP.

   It translates one format into another and uses xmpp, pua and
   presence modules to manage the transmition of presence state
   information.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * presence.
     * pua.
     * xmpp.

1.2.2. External Libraries or Applications

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

1.3. Exported Parameters

1.3.1. server_address(str)

   The IP address of the server.

   Example 1.1. Set server_address parameter
...
modparam("pua_xmpp", "server_address", "sip:sa@opensips.org:5060")
...

1.3.2. presence_server (str)

   The the address of the presence server. If set, it will be used
   as outbound proxy when sending PUBLISH requests.

   Example 1.2. Set presence_server parameter
...
modparam("pua_xmpp", "presence_server", "sip:pa@opensips.org:5075")
...

1.4. Exported Functions

   Functions exported to be used in configuration file.

1.4.1.  pua_xmpp_notify()

   Function that handles Notify messages addressed to a user from
   an xmpp domain. It requires filtering after method and domain
   in configuration file. If the function is successful, a 2xx
   reply must be sent.

   This function can be used from REQUEST_ROUTE.

   Example 1.3. Notify2Xmpp usage
...
        if( is_method("NOTIFY") && $ru=~"sip:.+@sip-xmpp.siphub.ro")
        {
                if(Notify2Xmpp())
                        t_reply(200, "OK");
                exit;
        }
...

1.4.2.  pua_xmpp_req_winfo(request_uri, expires)

   Function called when a Subscribe addressed to a user from a
   xmpp domain is received. It calls sending a Subscribe for winfo
   for the user, and the following Notify with dialog-info is
   translated into a subscription in xmpp. It also requires
   filtering in configuration file, after method, domain and
   event(only for presence).

   Parameters:
     * request_uri (string)
     * expires (int) - value of Expires header field in received
       Subscribe.

   This function can be used from REQUEST_ROUTE.

   Example 1.4. xmpp_send_winfo usage
...
        if( is_method("SUBSCRIBE"))
        {
                handle_subscribe();
                if($ru=~"sip:.+@sip-xmpp.siphub.ro" && $hdr(Event)== "pr
esence")
                {
                        pua_xmpp_req_winfo($ruri, $hdr(Expires));
                }
                t_release();
        }

...

1.5.  Filtering

   Instead of "sip-xmpp.siphub.ro" in the example you should use
   the value set for the xmpp module parameter named
   'gateway_domain'.

Chapter 2. Developer Guide

   The module provides 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 59 17 3287 806
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 16 13 59 81
   3. Liviu Chircu (@liviuchircu) 14 11 40 63
   4. Razvan Crainea (@razvancrainea) 13 11 24 33
   5. Daniel-Constantin Mierla (@miconda) 10 8 27 21
   6. Vlad Patrascu (@rvlad-patrascu) 7 4 34 69
   7. Ovidiu Sas (@ovidiusas) 3 1 14 2
   8. Sergio Gutierrez 3 1 5 5
   9. Vlad Paiu (@vladpaiu) 3 1 4 14
   10. Konstantin Bokarius 3 1 3 5

   All remaining contributors: Juha Heinanen (@juha-h), Maksym
   Sobolyev (@sobomax), Peter Lemenkov (@lemenkov), Walter Doekes
   (@wdoekes), Edson Gellert Schubert, Stanislaw Pitucha.

   (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 - Feb 2023
   3.  Razvan Crainea (@razvancrainea)     Feb 2012 - Jul 2020
   4.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   5.  Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2007 - Apr 2019
   6.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7.  Ovidiu Sas (@ovidiusas)             Jan 2013 - Jan 2013
   8.  Vlad Paiu (@vladpaiu)               Aug 2011 - Aug 2011
   9.  Stanislaw Pitucha                   Jul 2010 - Jul 2010
   10. Walter Doekes (@wdoekes)            Apr 2010 - Apr 2010

   All remaining contributors: Anca Vamanu, Sergio Gutierrez,
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Juha Heinanen (@juha-h).

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

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu
   (@bogdan-iancu), Razvan Crainea (@razvancrainea), Anca Vamanu,
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert.

   Documentation Copyrights:

   Copyright © 2007 Voice Sistem SRL
