[sr-dev] git:master: docs: added README for pua_reginfo and presence_reginfo

Module: sip-router Branch: master Commit: 0eaebb2c9a06f2eff7f103d1f2768f5aa677c18a URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=0eaebb2… Author: Daniel-Constantin Mierla <miconda(a)gmail.com> Committer: Daniel-Constantin Mierla <miconda(a)gmail.com> Date: Sat Jun 18 23:25:12 2011 +0200 docs: added README for pua_reginfo and presence_reginfo --- modules_k/presence_reginfo/README | 76 +++++++++++++ modules_k/pua_reginfo/README | 223 +++++++++++++++++++++++++++++++++++++ 2 files changed, 299 insertions(+), 0 deletions(-) diff --git a/modules_k/presence_reginfo/README b/modules_k/presence_reginfo/README new file mode 100644 index 0000000..3cde44d --- /dev/null +++ b/modules_k/presence_reginfo/README @@ -0,0 +1,76 @@ +presence_reginfo Module + +Carsten Bock + + <carsten(a)ng-voice.com> + +Edited by + +Carsten Bock + + <carsten(a)ng-voice.com> + + Copyright © 2011 Carsten Bock, carsten(a)ng-voice.com, + 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. diff --git a/modules_k/pua_reginfo/README b/modules_k/pua_reginfo/README new file mode 100644 index 0000000..bf6d98c --- /dev/null +++ b/modules_k/pua_reginfo/README @@ -0,0 +1,223 @@ +pua_reginfo Module + +Carsten Bock + + <carsten(a)ng-voice.com> + +Edited by + +Carsten Bock + + <carsten(a)ng-voice.com> + + Copyright © 2011 Carsten Bock, carsten(a)ng-voice.com, + 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:proxy@kamailio.org") +... + +3.5. server_address(str) + + The IP address of the server. + + Example 1.5. Set server_address parameter +... +modparam("pua_reginfo", "server_address", "sip:reginfo@160.34.23.12") +... + +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"); +} +...