docs: added README for pua_reginfo and presence_reginfo

modules_k/presence_reginfo/README

@@ -0,0 +1,76 @@
+presence_reginfo Module
+
+Carsten Bock
+
+   <[email protected]>
+
+Edited by
+
+Carsten Bock
+
+   <[email protected]>
+
+   Copyright © 2011 Carsten Bock, [email protected],
+   http://www.ng-voice.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Exported Functions
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Functions
+
+1. Overview
+
+   The module enables the handling of "Event: reg" (as defined in RFC
+   3680) inside of the presence module. This can be used distribute the
+   registration-info status to the subscribed watchers.
+
+   The module does not currently implement any authorization rules. It
+   assumes that publish requests are only issued by an authorized
+   application and subscribe requests only by authorized users.
+   Authorization can thus be easily done in Kamailio configuration file
+   before calling handle_publish() and handle_subscribe() functions.
+
+   Note: This module only activates the processing of the "reg" in the
+   presence module. To send dialog-info to watchers you also need a source
+   which PUBLISH the reg info to the presence module. For example you can
+   use the pua_reginfo module or any external component. This approach
+   allows to have the presence server and the reg-info aware publisher
+   (e.g. the main proxy) on different Kamailio instances.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * presence.
+
+2.2. External Libraries or Applications
+
+   None.
+
+3. Exported Functions
+
+   None to be used in configuration file.

modules_k/pua_reginfo/README

@@ -0,0 +1,223 @@
+pua_reginfo Module
+
+Carsten Bock
+
+   <[email protected]>
+
+Edited by
+
+Carsten Bock
+
+   <[email protected]>
+
+   Copyright © 2011 Carsten Bock, [email protected],
+   http://www.ng-voice.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Exported Parameters
+
+              3.1. default_domain(str)
+              3.2. default_domain(str)
+              3.3. publish_reginfo(int)
+              3.4. outbound_proxy(str)
+              3.5. server_address(str)
+
+        4. Exported Functions
+
+              4.1. reginfo_handle_notify
+              4.2. reginfo_subscribe(uri[, expires])
+
+   List of Examples
+
+   1.1. Set default_domain parameter
+   1.2. Set default_domain parameter
+   1.3. Set publish_reginfo parameter
+   1.4. Set outbound_proxy parameter
+   1.5. Set server_address parameter
+   1.6. reginfo_handle_notify usage
+   1.7. reginfo_subscribe usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. default_domain(str)
+        3.2. default_domain(str)
+        3.3. publish_reginfo(int)
+        3.4. outbound_proxy(str)
+        3.5. server_address(str)
+
+   4. Exported Functions
+
+        4.1. reginfo_handle_notify
+        4.2. reginfo_subscribe(uri[, expires])
+
+1. Overview
+
+   This modules 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 it's own registration-status, so he
+       would get notified as soon as his account gets administratively
+       unregistered.
+     * ...
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * pua.
+     * usrloc.
+
+2.2. External Libraries or Applications
+
+   None.
+
+3. Exported Parameters
+
+   3.1. default_domain(str)
+   3.2. default_domain(str)
+   3.3. publish_reginfo(int)
+   3.4. outbound_proxy(str)
+   3.5. server_address(str)
+
+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_bla", "default_domain", "kamailio.org")
+...
+
+3.2. default_domain(str)
+
+   The domain to be used to publish information about a user.
+
+   Example 1.2. Set default_domain parameter
+...
+modparam("pua_reginfo", "default_domain", "kamailio.org")
+...
+
+3.3. publish_reginfo(int)
+
+   Whether or not to generate PUBLISH requests.
+
+   Default value is “1” (enabled).
+
+   Example 1.3. Set publish_reginfo parameter
+...
+modparam("pua_reginfo", "publish_reginfo", 0)
+...
+
+3.4. outbound_proxy(str)
+
+   The outbound_proxy uri to be used when sending Subscribe requests.
+
+   Default value is “NULL”.
+
+   Example 1.4. Set outbound_proxy parameter
+...
+modparam("pua_reginfo", "outbound_proxy", "sip:[email protected]")
+...
+
+3.5. server_address(str)
+
+   The IP address of the server.
+
+   Example 1.5. Set server_address parameter
+...
+modparam("pua_reginfo", "server_address", "sip:[email protected]")
+...
+
+4. Exported Functions
+
+   4.1. reginfo_handle_notify
+   4.2. reginfo_subscribe(uri[, expires])
+
+4.1.  reginfo_handle_notify
+
+   This function processes received "NOTIFY"-requests and updates the
+   local registry accordingly.
+
+   This method does not create any SIP-Reponse, this has to be done the
+   script-writer.
+
+   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.6. reginfo_handle_notify usage
+...
+if(is_method("NOTIFY"))
+        if (reginfo_handle_notify())
+                send_reply("202", "Accepted");
+...
+
+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.7. reginfo_subscribe usage
+...
+route {
+        t_on_reply("1");
+        t_relay();
+}
+
+reply_route[1] {
+        if (t_check_status("200"))
+                reginfo_subscribe("$ru");
+}
+...