modules: readme files regenerated - pua_reginfo ... [skip ci]
[sip-router] / 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 ...