pua_reginfo Module

Carsten Bock

   <carsten@ng-voice.com>

Edited by

Carsten Bock

   <carsten@ng-voice.com>
     __________________________________________________________

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

              1.3.1. default_domain(str)
              1.3.2. publish_reginfo(int)
              1.3.3. outbound_proxy(str)
              1.3.4. server_address(str)
              1.3.5. ul_domain(str)
              1.3.6. ul_identities_key(str)

        1.4. Functions

              1.4.1. reginfo_handle_notify(uldomain)
              1.4.2. reginfo_subscribe(uri[, expires])
              1.4.3. reginfo_update(aor)

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

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

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

   List of Examples

   1.1. Set default_domain parameter
   1.2. Set publish_reginfo parameter
   1.3. Set outbound_proxy parameter
   1.4. Set server_address parameter
   1.5. Set ul_domain parameter
   1.6. Set ul_identities_key parameter
   1.7. reginfo_handle_notify usage
   1.8. reginfo_subscribe usage
   1.9. reginfo_subscribe usage

Chapter 1. Admin Guide

1.1. Overview

   This module publishes information about "reg"-events according
   to to RFC 3680. This can be used distribute the
   registration-info status to the subscribed watchers.

   This module "PUBLISH"es information when a new user registers
   at this server (e.g. when "save()" is called) to users, which
   have subscribed for the reg-info for this user.

   This module can "SUBSCRIBE" for information at another server,
   so it will receive "NOTIFY"-requests, when the information
   about a user changes.

   And finally, it can process received "NOTIFY" requests and it
   will update the local registry accordingly.

   Use cases for this might be:
     * Keeping different Servers in Sync regarding the location
       database
     * Get notified, when a user registers: A presence-server,
       which handles offline message storage for an account, would
       get notified, when the user comes online.
     * A client could subscribe to its own registration-status, so
       he would get notified as soon as his account gets
       administratively unregistered.
     * ...

1.2. Dependencies

1.2.1. OpenSIPS Modules

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

1.2.2. External Libraries or Applications

   None.

1.3. Parameters

1.3.1. default_domain(str)

   The default domain for the registered users to be used when
   constructing the uri for the registrar callback.

   Default value is “NULL”.

   Example 1.1. Set default_domain parameter
...
modparam("pua_reginfo", "default_domain", "kamailio.org")
...

1.3.2. publish_reginfo(int)

   Whether or not to generate PUBLISH requests.

   Default value is “1” (enabled).

   Example 1.2. Set publish_reginfo parameter
...
modparam("pua_reginfo", "publish_reginfo", 0)
...

1.3.3. outbound_proxy(str)

   The outbound_proxy uri to be used when sending Subscribe and
   Publish requests.

   Default value is “NULL”.

   Example 1.3. Set outbound_proxy parameter
...
modparam("pua_reginfo", "outbound_proxy", "sip:proxy@kamailio.org")
...

1.3.4. server_address(str)

   The IP address of the server.

   Example 1.4. Set server_address parameter
...
modparam("pua_reginfo", "server_address", "sip:reginfo@160.34.23.12")
...

1.3.5. ul_domain(str)

   The domain for for querying the usrloc-database.

   Default value is “NULL” (not set).

   Example 1.5. Set ul_domain parameter
...
modparam("pua_reginfo", "ul_domain", "location")
...

1.3.6. ul_identities_key(str)

   The Key, which may be used for retrieving multiple public
   identies for a user.

   Default value is “NULL” (not set).

   Example 1.6. Set ul_identities_key parameter
...
modparam("pua_reginfo", "ul_identities_key", "identities")
...
onreply_route[register_reply] {
        if (t_check_status("200") && $hdr(P-Associated-URI)) {
        ul_add_key("location", "$tU@$td", "identities", "$hdr(P-Associat
ed-URI)");
        reginfo_update("$tU@$td");
        }
}

...

1.4. Functions

1.4.1.  reginfo_handle_notify(uldomain)

   This function processes received "NOTIFY"-requests and updates
   the local registry accordingly.

   This method does not create any SIP-Response, this has to be
   done by the script-writer.

   The parameter has to correspond to user location table (domain)
   where to store the record.

   Return codes:
     * 2 - contacts successfully updated, but no more contacts
       online now.
       1 - contacts successfully updated and at at least one
       contact still registered.
       -1 - Invalid NOTIFY or other error (see log-file)

   Example 1.7. reginfo_handle_notify usage
...
if(is_method("NOTIFY"))
        if (reginfo_handle_notify("location"))
                send_reply("202", "Accepted");
...

1.4.2.  reginfo_subscribe(uri[, expires])

   This function will subscribe for reginfo-information at the
   given server URI.

   Meaning of the parameters is as follows:
     * uri - SIP-URI of the server, where to subscribe, may
       contain pseudo-variables.
       expires - Expiration date for this subscription, in seconds
       (default 3600)

   Example 1.8. reginfo_subscribe usage
...
route {
        t_on_reply("1");
        t_relay();
}

reply_route[1] {
        if (t_check_status("200"))
                reginfo_subscribe("$ru");
}
...

1.4.3.  reginfo_update(aor)

   Explicitly update the presence status, e.g., when new
   information is learned. This may trigger a new NOTIFY towards
   subscribed entities; at least it will update the internal
   information for subsequent subscribe and notifies.

   This is done implicitly, when a registration is updated.
   However, when a registration was just updated with additional
   information like identities, this is not triggered
   automatically.

   Meaning of the parameters is as follows:
     * aor - The AOR to be updated.

   Example 1.9. reginfo_subscribe usage
...
modparam("pua_reginfo", "ul_domain", "location")
modparam("pua_reginfo", "ul_identities_key", "identities")
...
onreply_route[register_reply] {
        if (t_check_status("200") && $hdr(P-Associated-URI)) {
        ul_add_key("location", "$tU@$td", "identities", "$hdr(P-Associat
ed-URI)");
        reginfo_update("$tU@$td");
        }
}

...

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Carsten Bock 18 1 1930 0
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 4 2 16 19
   3. Liviu Chircu (@liviuchircu) 3 1 2 3
   4. Peter Lemenkov (@lemenkov) 3 1 1 1
   5. Razvan Crainea (@razvancrainea) 2 1 1 0

   (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

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Peter Lemenkov (@lemenkov)          Feb 2025 - Feb 2025
   2. Razvan Crainea (@razvancrainea)     Jan 2025 - Jan 2025
   3. Bogdan-Andrei Iancu (@bogdan-iancu) Apr 2024 - Apr 2024
   4. Liviu Chircu (@liviuchircu)         Apr 2024 - Apr 2024
   5. Carsten Bock                        Mar 2024 - Mar 2024

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Carsten
   Bock.

   Documentation Copyrights:

   Copyright © 2011-2023 Carsten Bock, carsten@ng-voice.com,
   http://www.ng-voice.com
