git.sip-router.org Git - sip-router/blob - src/modules/pua_reginfo/README

   1 pua_reginfo Module
   2
   3 Carsten Bock
   4
   5    <carsten@ng-voice.com>
   6
   7 Edited by
   8
   9 Carsten Bock
  10
  11    <carsten@ng-voice.com>
  12
  13    Copyright © 2011 Carsten Bock, carsten@ng-voice.com,
  14    http://www.ng-voice.com
  15      __________________________________________________________________
  16
  17    Table of Contents
  18
  19    1. Admin Guide
  20
  21         1. Overview
  22         2. Dependencies
  23
  24               2.1. Kamailio Modules
  25               2.2. External Libraries or Applications
  26
  27         3. Parameters
  28
  29               3.1. default_domain(str)
  30               3.2. publish_reginfo(int)
  31               3.3. outbound_proxy(str)
  32               3.4. server_address(str)
  33
  34         4. Functions
  35
  36               4.1. reginfo_handle_notify(uldomain)
  37               4.2. reginfo_subscribe(uri[, expires])
  38
  39    List of Examples
  40
  41    1.1. Set default_domain parameter
  42    1.2. Set publish_reginfo parameter
  43    1.3. Set outbound_proxy parameter
  44    1.4. Set server_address parameter
  45    1.5. reginfo_handle_notify usage
  46    1.6. reginfo_subscribe usage
  47
  48 Chapter 1. Admin Guide
  49
  50    Table of Contents
  51
  52    1. Overview
  53    2. Dependencies
  54
  55         2.1. Kamailio Modules
  56         2.2. External Libraries or Applications
  57
  58    3. Parameters
  59
  60         3.1. default_domain(str)
  61         3.2. publish_reginfo(int)
  62         3.3. outbound_proxy(str)
  63         3.4. server_address(str)
  64
  65    4. Functions
  66
  67         4.1. reginfo_handle_notify(uldomain)
  68         4.2. reginfo_subscribe(uri[, expires])
  69
  70 1. Overview
  71
  72    This modules publishes information about "reg"-events according to to
  73    RFC 3680. This can be used distribute the registration-info status to
  74    the subscribed watchers.
  75
  76    This module "PUBLISH"es information when a new user registers at this
  77    server (e.g. when "save()" is called) to users, which have subscribed
  78    for the reg-info for this user.
  79
  80    This module can "SUBSCRIBE" for information at another server, so it
  81    will receive "NOTIFY"-requests, when the information about a user
  82    changes.
  83
  84    And finally, it can process received "NOTIFY" requests and it will
  85    update the local registry accordingly.
  86
  87    Use cases for this might be:
  88      * Keeping different Servers in Sync regarding the location database
  89      * Get notified, when a user registers: A presence-server, which
  90        handles offline message storage for an account, would get notified,
  91        when the user comes online.
  92      * A client could subscribe to it's own registration-status, so he
  93        would get notified as soon as his account gets administratively
  94        unregistered.
  95      * ...
  96
  97 2. Dependencies
  98
  99    2.1. Kamailio Modules
 100    2.2. External Libraries or Applications
 101
 102 2.1. Kamailio Modules
 103
 104    The following modules must be loaded before this module:
 105      * pua.
 106      * usrloc.
 107
 108 2.2. External Libraries or Applications
 109
 110    None.
 111
 112 3. Parameters
 113
 114    3.1. default_domain(str)
 115    3.2. publish_reginfo(int)
 116    3.3. outbound_proxy(str)
 117    3.4. server_address(str)
 118
 119 3.1. default_domain(str)
 120
 121    The default domain for the registered users to be used when
 122    constructing the uri for the registrar callback.
 123
 124    Default value is “NULL”.
 125
 126    Example 1.1. Set default_domain parameter
 127 ...
 128 modparam("pua_reginfo", "default_domain", "kamailio.org")
 129 ...
 130
 131 3.2. publish_reginfo(int)
 132
 133    Whether or not to generate PUBLISH requests.
 134
 135    Default value is “1” (enabled).
 136
 137    Example 1.2. Set publish_reginfo parameter
 138 ...
 139 modparam("pua_reginfo", "publish_reginfo", 0)
 140 ...
 141
 142 3.3. outbound_proxy(str)
 143
 144    The outbound_proxy uri to be used when sending Subscribe and Publish
 145    requests.
 146
 147    Default value is “NULL”.
 148
 149    Example 1.3. Set outbound_proxy parameter
 150 ...
 151 modparam("pua_reginfo", "outbound_proxy", "sip:proxy@kamailio.org")
 152 ...
 153
 154 3.4. server_address(str)
 155
 156    The IP address of the server.
 157
 158    Example 1.4. Set server_address parameter
 159 ...
 160 modparam("pua_reginfo", "server_address", "sip:reginfo@160.34.23.12")
 161 ...
 162
 163 4. Functions
 164
 165    4.1. reginfo_handle_notify(uldomain)
 166    4.2. reginfo_subscribe(uri[, expires])
 167
 168 4.1.  reginfo_handle_notify(uldomain)
 169
 170    This function processes received "NOTIFY"-requests and updates the
 171    local registry accordingly.
 172
 173    This method does not create any SIP-Reponse, this has to be done the
 174    script-writer.
 175
 176    The parameter has to correspond to user location table (domain) where
 177    to store the record.
 178
 179    Return codes:
 180      * 2 - contacts successfully updated, but no more contacts online now.
 181        1 - contacts successfully updated and at at least one contact still
 182        registered.
 183        -1 - Invalid NOTIFY or other error (see log-file)
 184
 185    Example 1.5. reginfo_handle_notify usage
 186 ...
 187 if(is_method("NOTIFY"))
 188         if (reginfo_handle_notify("location"))
 189                 send_reply("202", "Accepted");
 190 ...
 191
 192 4.2.  reginfo_subscribe(uri[, expires])
 193
 194    This function will subscribe for reginfo-information at the given
 195    server URI.
 196
 197    Meaning of the parameters is as follows:
 198      * uri - SIP-URI of the server, where to subscribe, may contain
 199        pseudo-variables.
 200        expires - Expiration date for this subscription, in seconds
 201        (default 3600)
 202
 203    Example 1.6. reginfo_subscribe usage
 204 ...
 205 route {
 206         t_on_reply("1");
 207         t_relay();
 208 }
 209
 210 reply_route[1] {
 211         if (t_check_status("200"))
 212                 reginfo_subscribe("$ru");
 213 }
 214 ...