Browse code

lcr doc: re-gerenarated README

Andrei Pelinescu-Onciul authored on 13/05/2009 11:59:53
Showing 1 changed files
... ...
@@ -12,62 +12,67 @@ Juha Heinanen
12 12
 
13 13
    Copyright � 2005-2008 Juha Heinanen
14 14
    Revision History
15
-   Revision $Revision$ $Date: 2008-10-16 19:58:34 +0300
16
-                              (Thu, 16 Oct 2008) $
17
-     __________________________________________________________
15
+   Revision $Revision$ $Date$
16
+     __________________________________________________________________
18 17
 
19 18
    Table of Contents
20 19
 
21 20
    1. Admin Guide
22 21
 
23
-        1.1. Overview
24
-        1.2. Dependencies
25
-
26
-              1.2.1. Kamailio modules
27
-              1.2.2. External libraries or applications
28
-
29
-        1.3. Exported Parameters
30
-
31
-              1.3.1. db_url (string)
32
-              1.3.2. gw_table (string)
33
-              1.3.3. gw_name_column (string)
34
-              1.3.4. grp_id_column (string)
35
-              1.3.5. ip_addr_column (string)
36
-              1.3.6. hostname_column (string)
37
-              1.3.7. port_column (string)
38
-              1.3.8. uri_scheme_column (string)
39
-              1.3.9. transport_column (string)
40
-              1.3.10. strip_column (string)
41
-              1.3.11. tag_column (string)
42
-              1.3.12. weight_column (string)
43
-              1.3.13. flags_column (string)
44
-              1.3.14. lcr_table (string)
45
-              1.3.15. prefix_column (string)
46
-              1.3.16. from_uri_column (string)
47
-              1.3.17. priority_column (string)
48
-              1.3.18. gw_uri_avp (AVP string)
49
-              1.3.19. rpid_avp (AVP string)
50
-              1.3.20. ruri_user_avp (AVP string)
51
-              1.3.21. flags_avp (AVP string)
52
-              1.3.22. lcr_hash_size (integer)
53
-              1.3.23. fetch_rows (integer)
54
-
55
-        1.4. Exported Functions
56
-
57
-              1.4.1. load_gws([pvar])
58
-              1.4.2. load_gws_from_grp(group-id)
59
-              1.4.3. next_gw()
60
-              1.4.4. from_gw([pvar])
61
-              1.4.5. from_gw_grp(group-id)
62
-              1.4.6. to_gw([group-id])
63
-
64
-        1.5. Exported MI Commands
65
-
66
-              1.5.1. lcr_reload
67
-              1.5.2. lcr_gw_dump
68
-              1.5.3. lcr_lcr_dump
69
-
70
-        1.6. Known Limitations
22
+        1. Overview
23
+        2. Dependencies
24
+
25
+              2.1. Kamailio modules
26
+              2.2. External libraries or applications
27
+
28
+        3. Exported Parameters
29
+
30
+              3.1. db_url (string)
31
+              3.2. gw_table (string)
32
+              3.3. gw_name_column (string)
33
+              3.4. grp_id_column (string)
34
+              3.5. ip_addr_column (string)
35
+              3.6. hostname_column (string)
36
+              3.7. port_column (string)
37
+              3.8. uri_scheme_column (string)
38
+              3.9. transport_column (string)
39
+              3.10. strip_column (string)
40
+              3.11. tag_column (string)
41
+              3.12. weight_column (string)
42
+              3.13. flags_column (string)
43
+              3.14. lcr_table (string)
44
+              3.15. prefix_column (string)
45
+              3.16. from_uri_column (string)
46
+              3.17. priority_column (string)
47
+              3.18. gw_uri_avp (AVP string)
48
+              3.19. rpid_avp (AVP string)
49
+              3.20. ruri_user_avp (AVP string)
50
+              3.21. flags_avp (AVP string)
51
+              3.22. lcr_hash_size (integer)
52
+              3.23. fetch_rows (integer)
53
+
54
+        4. Exported Functions
55
+
56
+              4.1. load_gws([pvar])
57
+              4.2. load_gws_from_grp(group-id)
58
+              4.3. next_gw()
59
+              4.4. from_gw([pvar])
60
+              4.5. from_gw_grp(group-id)
61
+              4.6. to_gw([group-id])
62
+
63
+        5. Exported MI Commands
64
+
65
+              5.1. lcr_reload
66
+              5.2. lcr_gw_dump
67
+              5.3. lcr_lcr_dump
68
+
69
+        6. Exported RPC Commands
70
+
71
+              6.1. lcr.reload
72
+              6.2. lcr.dump_gws
73
+              6.3. lcr.dump_lcr
74
+
75
+        7. Known Limitations
71 76
 
72 77
    List of Examples
73 78
 
... ...
@@ -103,83 +108,165 @@ Juha Heinanen
103 108
    1.30. from_gw_grp usage
104 109
    1.31. to_gw usage
105 110
    1.32. to_gw usage with group-id
111
+   1.33. lcr.reload RPC example
112
+   1.34. lcr.dump_gws RPC example
113
+   1.35. lcr.dump_lcr RPC example
106 114
 
107 115
 Chapter 1. Admin Guide
108 116
 
109
-1.1. Overview
110
-
111
-   Least cost routing (LCR) module implements capability to
112
-   serially forward a request to one or more gateways so that the
113
-   order in which the gateways is tried is based on admin defined
114
-   "least cost".
115
-
116
-   For the purpose of facilitating least cost routing of requests,
117
-   each gateway belongs to a gateway group and each gateway group
118
-   is associated with one or more <prefix, from pattern, priority>
119
-   tuples. A gateway matches a request if user part of Request URI
120
-   matches a prefix and caller's URI matches a from pattern in a
121
-   tuple that belongs to the group of the gateway.
122
-
123
-   When function load_gws() is called, matching gateways are
124
-   ordered for forwarding purpose (1) according to longest user
125
-   part match, (2) according to tuple's priority, and (3)
126
-   gateway's randomized weight within its group. Prefix is a
127
-   string of characters or NULL. From pattern is a regular
128
-   expression (see 'man pcresyntax' for syntax), an empty string,
129
-   or NULL. Empty or NULL from pattern or prefix matches anything.
130
-   Smaller priority value means higher priority (highest priority
131
-   value being 0). Weight is an integer value from 1 to 254.
132
-
133
-   Function next_gw() can then be used to select one gateway at a
134
-   time for forwarding. Upon each call, user part of original
135
-   Request URI is first stripped by the number of characters as
136
-   specified by the gateway's strip count and then prefixed by
137
-   gateway's tag. Upon first call, if gateway's hostname is NULL,
138
-   Request URI is rewritten based on gateway's URI scheme, IP
139
-   address, port, and transport protocol. If hostname is not NULL,
140
-   Request-URI is rewritten based on gateway's URI scheme and
141
-   hostname, and destination URI is set based on gateway's URI
142
-   scheme, IP address, port, and transport protocol. Upon
143
-   subsequent calls, the same is done, but instead of rewriting
144
-   Request URI, a new branch is added.
145
-
146
-   Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips.
147
-   Currently valid transport protocol values are NULL = none, 1 =
148
-   udp, 2 = tcp, 3 = tls, and 4 = sctp.
149
-
150
-   As a side effect of gateway selection, gateway's flags (that
151
-   may contain information about capabilities of the gateway) are
152
-   stored into an AVP.
153
-
154
-1.2. Dependencies
155
-
156
-1.2.1. Kamailio modules
117
+   Table of Contents
118
+
119
+   1. Overview
120
+   2. Dependencies
121
+
122
+        2.1. Kamailio modules
123
+        2.2. External libraries or applications
124
+
125
+   3. Exported Parameters
126
+
127
+        3.1. db_url (string)
128
+        3.2. gw_table (string)
129
+        3.3. gw_name_column (string)
130
+        3.4. grp_id_column (string)
131
+        3.5. ip_addr_column (string)
132
+        3.6. hostname_column (string)
133
+        3.7. port_column (string)
134
+        3.8. uri_scheme_column (string)
135
+        3.9. transport_column (string)
136
+        3.10. strip_column (string)
137
+        3.11. tag_column (string)
138
+        3.12. weight_column (string)
139
+        3.13. flags_column (string)
140
+        3.14. lcr_table (string)
141
+        3.15. prefix_column (string)
142
+        3.16. from_uri_column (string)
143
+        3.17. priority_column (string)
144
+        3.18. gw_uri_avp (AVP string)
145
+        3.19. rpid_avp (AVP string)
146
+        3.20. ruri_user_avp (AVP string)
147
+        3.21. flags_avp (AVP string)
148
+        3.22. lcr_hash_size (integer)
149
+        3.23. fetch_rows (integer)
150
+
151
+   4. Exported Functions
152
+
153
+        4.1. load_gws([pvar])
154
+        4.2. load_gws_from_grp(group-id)
155
+        4.3. next_gw()
156
+        4.4. from_gw([pvar])
157
+        4.5. from_gw_grp(group-id)
158
+        4.6. to_gw([group-id])
159
+
160
+   5. Exported MI Commands
161
+
162
+        5.1. lcr_reload
163
+        5.2. lcr_gw_dump
164
+        5.3. lcr_lcr_dump
165
+
166
+   6. Exported RPC Commands
167
+
168
+        6.1. lcr.reload
169
+        6.2. lcr.dump_gws
170
+        6.3. lcr.dump_lcr
171
+
172
+   7. Known Limitations
173
+
174
+1. Overview
175
+
176
+   Least cost routing (LCR) module implements capability to serially
177
+   forward a request to one or more gateways so that the order in which
178
+   the gateways is tried is based on admin defined "least cost".
179
+
180
+   For the purpose of facilitating least cost routing of requests, each
181
+   gateway belongs to a gateway group and each gateway group is associated
182
+   with one or more <prefix, from pattern, priority> tuples. A gateway
183
+   matches a request if user part of Request URI matches a prefix and
184
+   caller's URI matches a from pattern in a tuple that belongs to the
185
+   group of the gateway.
186
+
187
+   When function load_gws() is called, matching gateways are ordered for
188
+   forwarding purpose (1) according to longest user part match, (2)
189
+   according to tuple's priority, and (3) gateway's randomized weight
190
+   within its group. Prefix is a string of characters or NULL. From
191
+   pattern is a regular expression (see 'man pcresyntax' for syntax), an
192
+   empty string, or NULL. Empty or NULL from pattern or prefix matches
193
+   anything. Smaller priority value means higher priority (highest
194
+   priority value being 0). Weight is an integer value from 1 to 254.
195
+
196
+   Function next_gw() can then be used to select one gateway at a time for
197
+   forwarding. Upon each call, user part of original Request URI is first
198
+   stripped by the number of characters as specified by the gateway's
199
+   strip count and then prefixed by gateway's tag. Upon first call, if
200
+   gateway's hostname is NULL, Request URI is rewritten based on gateway's
201
+   URI scheme, IP address, port, and transport protocol. If hostname is
202
+   not NULL, Request-URI is rewritten based on gateway's URI scheme and
203
+   hostname, and destination URI is set based on gateway's URI scheme, IP
204
+   address, port, and transport protocol. Upon subsequent calls, the same
205
+   is done, but instead of rewriting Request URI, a new branch is added.
206
+
207
+   Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently
208
+   valid transport protocol values are NULL = none, 1 = udp, 2 = tcp, 3 =
209
+   tls, and 4 = sctp.
210
+
211
+   As a side effect of gateway selection, gateway's flags (that may
212
+   contain information about capabilities of the gateway) are stored into
213
+   an AVP.
214
+
215
+2. Dependencies
216
+
217
+   2.1. Kamailio modules
218
+   2.2. External libraries or applications
219
+
220
+2.1. Kamailio modules
157 221
 
158 222
    The following modules must be loaded before this module:
159 223
      * TM module
160 224
      * A database module like mysql, postgres or dbtext.
161 225
 
162
-1.2.2. External libraries or applications
226
+2.2. External libraries or applications
163 227
 
164
-   The following libraries or applications must be installed
165
-   before running Kamailio with this module:
228
+   The following libraries or applications must be installed before
229
+   running Kamailio with this module:
166 230
      * none.
167 231
 
168
-1.3. Exported Parameters
169
-
170
-1.3.1. db_url (string)
232
+3. Exported Parameters
233
+
234
+   3.1. db_url (string)
235
+   3.2. gw_table (string)
236
+   3.3. gw_name_column (string)
237
+   3.4. grp_id_column (string)
238
+   3.5. ip_addr_column (string)
239
+   3.6. hostname_column (string)
240
+   3.7. port_column (string)
241
+   3.8. uri_scheme_column (string)
242
+   3.9. transport_column (string)
243
+   3.10. strip_column (string)
244
+   3.11. tag_column (string)
245
+   3.12. weight_column (string)
246
+   3.13. flags_column (string)
247
+   3.14. lcr_table (string)
248
+   3.15. prefix_column (string)
249
+   3.16. from_uri_column (string)
250
+   3.17. priority_column (string)
251
+   3.18. gw_uri_avp (AVP string)
252
+   3.19. rpid_avp (AVP string)
253
+   3.20. ruri_user_avp (AVP string)
254
+   3.21. flags_avp (AVP string)
255
+   3.22. lcr_hash_size (integer)
256
+   3.23. fetch_rows (integer)
257
+
258
+3.1. db_url (string)
171 259
 
172 260
    URL of the database table to be used.
173 261
 
174
-   Default value is
175
-   "mysql://openserro:openserro@localhost/openser".
262
+   Default value is "mysql://openserro:openserro@localhost/openser".
176 263
 
177 264
    Example 1.1. Setting db_url module parameter
178 265
 ...
179 266
 modparam("lcr","db_url","dbdriver://username:password@dbhost/dbname")
180 267
 ...
181 268
 
182
-1.3.2. gw_table (string)
269
+3.2. gw_table (string)
183 270
 
184 271
    Name of the table holding the gateways definitions.
185 272
 
... ...
@@ -190,7 +277,7 @@ modparam("lcr","db_url","dbdriver://username:password@dbhost/dbname")
190 277
 modparam("lcr","gw_table","gw")
191 278
 ...
192 279
 
193
-1.3.3. gw_name_column (string)
280
+3.3. gw_name_column (string)
194 281
 
195 282
    Name of the column holding the gateway name.
196 283
 
... ...
@@ -201,10 +288,10 @@ modparam("lcr","gw_table","gw")
201 288
 modparam("lcr","gw_name_column","gw_name")
202 289
 ...
203 290
 
204
-1.3.4. grp_id_column (string)
291
+3.4. grp_id_column (string)
205 292
 
206
-   Name of the column holding the group ID of gateway both in gw
207
-   and lcr tables.
293
+   Name of the column holding the group ID of gateway both in gw and lcr
294
+   tables.
208 295
 
209 296
    Default value is "grp_id".
210 297
 
... ...
@@ -213,7 +300,7 @@ modparam("lcr","gw_name_column","gw_name")
213 300
 modparam("lcr","grp_id_column","grp_id")
214 301
 ...
215 302
 
216
-1.3.5. ip_addr_column (string)
303
+3.5. ip_addr_column (string)
217 304
 
218 305
    Name of the column holding the IP address of the gateway.
219 306
 
... ...
@@ -224,12 +311,12 @@ modparam("lcr","grp_id_column","grp_id")
224 311
 modparam("lcr","ip_addr_column","ip_addr")
225 312
 ...
226 313
 
227
-1.3.6. hostname_column (string)
314
+3.6. hostname_column (string)
228 315
 
229 316
    Name of the column holding gateway's hostname that is used in
230
-   Request-URI, when request is sent to the gateway. Note that
231
-   request is not forwarded based on hostname, but based on
232
-   gateway's IP address in destination uri.
317
+   Request-URI, when request is sent to the gateway. Note that request is
318
+   not forwarded based on hostname, but based on gateway's IP address in
319
+   destination uri.
233 320
 
234 321
    Default value is "hostname".
235 322
 
... ...
@@ -238,7 +325,7 @@ modparam("lcr","ip_addr_column","ip_addr")
238 325
 modparam("lcr", "hostname_column","host")
239 326
 ...
240 327
 
241
-1.3.7. port_column (string)
328
+3.7. port_column (string)
242 329
 
243 330
    Name of the column holding the port number of the gateway.
244 331
 
... ...
@@ -249,7 +336,7 @@ modparam("lcr", "hostname_column","host")
249 336
 modparam("lcr","port_column","port")
250 337
 ...
251 338
 
252
-1.3.8. uri_scheme_column (string)
339
+3.8. uri_scheme_column (string)
253 340
 
254 341
    Name of the column holding the uri scheme of the gateway.
255 342
 
... ...
@@ -260,10 +347,10 @@ modparam("lcr","port_column","port")
260 347
 modparam("lcr","uri_scheme_column","scheme")
261 348
 ...
262 349
 
263
-1.3.9. transport_column (string)
350
+3.9. transport_column (string)
264 351
 
265
-   Name of the column holding the transport type to be used for
266
-   the gateway.
352
+   Name of the column holding the transport type to be used for the
353
+   gateway.
267 354
 
268 355
    Default value is "transport".
269 356
 
... ...
@@ -272,11 +359,10 @@ modparam("lcr","uri_scheme_column","scheme")
272 359
 modparam("lcr","transport_column","transport")
273 360
 ...
274 361
 
275
-1.3.10. strip_column (string)
362
+3.10. strip_column (string)
276 363
 
277
-   Name of the column holding the number of characters to be
278
-   stripped from the front of Request URI user part before
279
-   inserting tag.
364
+   Name of the column holding the number of characters to be stripped from
365
+   the front of Request URI user part before inserting tag.
280 366
 
281 367
    Default value is "strip".
282 368
 
... ...
@@ -285,7 +371,7 @@ modparam("lcr","transport_column","transport")
285 371
 modparam("lcr","strip_column","strip_count")
286 372
 ...
287 373
 
288
-1.3.11. tag_column (string)
374
+3.11. tag_column (string)
289 375
 
290 376
    Name of the column holding gateway specific tag string.
291 377
 
... ...
@@ -296,7 +382,7 @@ modparam("lcr","strip_column","strip_count")
296 382
 modparam("lcr","tag_column","gw_tag")
297 383
 ...
298 384
 
299
-1.3.12. weight_column (string)
385
+3.12. weight_column (string)
300 386
 
301 387
    Name of the column holding gateway's weight within its group.
302 388
 
... ...
@@ -307,7 +393,7 @@ modparam("lcr","tag_column","gw_tag")
307 393
 modparam("lcr","weight_column","gw_weight")
308 394
 ...
309 395
 
310
-1.3.13. flags_column (string)
396
+3.13. flags_column (string)
311 397
 
312 398
    Name of the column holding gateway specific flag values.
313 399
 
... ...
@@ -318,7 +404,7 @@ modparam("lcr","weight_column","gw_weight")
318 404
 modparam("lcr","flags_column","gw_flags")
319 405
 ...
320 406
 
321
-1.3.14. lcr_table (string)
407
+3.14. lcr_table (string)
322 408
 
323 409
    Name of the table holding the LCR rules.
324 410
 
... ...
@@ -329,7 +415,7 @@ modparam("lcr","flags_column","gw_flags")
329 415
 modparam("lcr","lcr_table","lcr")
330 416
 ...
331 417
 
332
-1.3.15. prefix_column (string)
418
+3.15. prefix_column (string)
333 419
 
334 420
    Name of the column holding prefix of Request URI user part.
335 421
 
... ...
@@ -340,7 +426,7 @@ modparam("lcr","lcr_table","lcr")
340 426
 modparam("lcr","prefix_column","prefix")
341 427
 ...
342 428
 
343
-1.3.16. from_uri_column (string)
429
+3.16. from_uri_column (string)
344 430
 
345 431
    Name of the column holding the FROM (source) URI.
346 432
 
... ...
@@ -351,7 +437,7 @@ modparam("lcr","prefix_column","prefix")
351 437
 modparam("lcr","from_uri_column","from_uri")
352 438
 ...
353 439
 
354
-1.3.17. priority_column (string)
440
+3.17. priority_column (string)
355 441
 
356 442
    Name of the column holding the priority of the rule.
357 443
 
... ...
@@ -362,63 +448,63 @@ modparam("lcr","from_uri_column","from_uri")
362 448
 modparam("lcr","priority_column","priority")
363 449
 ...
364 450
 
365
-1.3.18. gw_uri_avp (AVP string)
451
+3.18. gw_uri_avp (AVP string)
366 452
 
367
-   Internal AVP that load_gws function uses to store information
368
-   of matching gateways.
453
+   Internal AVP that load_gws function uses to store information of
454
+   matching gateways.
369 455
 
370
-   There is NO default value, thus this variable must be defined
371
-   in kamailio.cfg.
456
+   There is NO default value, thus this variable must be defined in
457
+   kamailio.cfg.
372 458
 
373 459
    Example 1.18. Setting gw_uri_avp module parameter
374 460
 ...
375 461
 modparam("lcr", "gw_uri_avp", "$avp(i:709)")
376 462
 ...
377 463
 
378
-1.3.19. rpid_avp (AVP string)
464
+3.19. rpid_avp (AVP string)
379 465
 
380 466
    An AVP that contains caller's RPID (if any).
381 467
 
382
-   There is NO default value, thus this variable must be defined
383
-   in kamailio.cfg.
468
+   There is NO default value, thus this variable must be defined in
469
+   kamailio.cfg.
384 470
 
385 471
    Example 1.19. Setting rpid_avp module parameter
386 472
 ...
387 473
 modparam("^auth$|lcr", "rpid_avp", "$avp(i:302)")
388 474
 ...
389 475
 
390
-1.3.20. ruri_user_avp (AVP string)
476
+3.20. ruri_user_avp (AVP string)
391 477
 
392
-   Internal AVP that next_gw function uses to store Request-URI
393
-   user for subsequent next_gw calls.
478
+   Internal AVP that next_gw function uses to store Request-URI user for
479
+   subsequent next_gw calls.
394 480
 
395
-   There is NO default value, thus this variable must be defined
396
-   in kamailio.cfg.
481
+   There is NO default value, thus this variable must be defined in
482
+   kamailio.cfg.
397 483
 
398 484
    Example 1.20. Setting ruri_user_avp module parameter
399 485
 ...
400 486
 modparam("lcr", "ruri_user_avp", "$avp(i:500)")
401 487
 ...
402 488
 
403
-1.3.21. flags_avp (AVP string)
489
+3.21. flags_avp (AVP string)
404 490
 
405
-   An AVP where successful next_gw and from_gw functions store
406
-   gateway's flags.
491
+   An AVP where successful next_gw and from_gw functions store gateway's
492
+   flags.
407 493
 
408
-   There is NO default value, thus this variable must be defined
409
-   in kamailio.cfg.
494
+   There is NO default value, thus this variable must be defined in
495
+   kamailio.cfg.
410 496
 
411 497
    Example 1.21. Setting flags_avp module parameter
412 498
 ...
413 499
 modparam("lcr", "flags_avp", "$avp(i:712)")
414 500
 ...
415 501
 
416
-1.3.22. lcr_hash_size (integer)
502
+3.22. lcr_hash_size (integer)
417 503
 
418
-   Defines the size of hash table used to store <prefix,
419
-   from_pattern, priority> tuples. Hashing is done based on
420
-   prefix. Larger value means less collisions with other prefixes.
421
-   Hash size value should be a power of 2.
504
+   Defines the size of hash table used to store <prefix, from_pattern,
505
+   priority> tuples. Hashing is done based on prefix. Larger value means
506
+   less collisions with other prefixes. Hash size value should be a power
507
+   of 2.
422 508
 
423 509
    Default value is 128.
424 510
 
... ...
@@ -427,13 +513,13 @@ modparam("lcr", "flags_avp", "$avp(i:712)")
427 513
 modparam("lcr", "lcr_hash_size", 1024)
428 514
 ...
429 515
 
430
-1.3.23. fetch_rows (integer)
516
+3.23. fetch_rows (integer)
431 517
 
432
-   The number of the rows to be fetched at once from database when
433
-   loading data from lcr table. This value can be used to tune the
434
-   load time at startup. For 1MB of private memory (default) it
435
-   should be below 3750. In order for this parameter to have
436
-   effect, database driver must support fetch_result() capability.
518
+   The number of the rows to be fetched at once from database when loading
519
+   data from lcr table. This value can be used to tune the load time at
520
+   startup. For 1MB of private memory (default) it should be below 3750.
521
+   In order for this parameter to have effect, database driver must
522
+   support fetch_result() capability.
437 523
 
438 524
    Default value is "2000".
439 525
 
... ...
@@ -442,80 +528,82 @@ modparam("lcr", "lcr_hash_size", 1024)
442 528
 modparam("lcr", "fetch_rows", 3000)
443 529
 ...
444 530
 
445
-1.4. Exported Functions
531
+4. Exported Functions
532
+
533
+   4.1. load_gws([pvar])
534
+   4.2. load_gws_from_grp(group-id)
535
+   4.3. next_gw()
536
+   4.4. from_gw([pvar])
537
+   4.5. from_gw_grp(group-id)
538
+   4.6. to_gw([group-id])
446 539
 
447
-1.4.1.  load_gws([pvar])
540
+4.1.  load_gws([pvar])
448 541
 
449
-   Loads URI schemes, IP addresses, hostnames, ports, and
450
-   transports of matching gateways to gw_uri_avp (see Overview
451
-   section). If optional pseudo variable argument is included,
452
-   caller's URI is taken from it. If pseudo variable argument is
453
-   not included, caller's URI is taken from rpid_avp or, if
454
-   rpid_avp value is empty, from From URI. Returns 1 or -1
542
+   Loads URI schemes, IP addresses, hostnames, ports, and transports of
543
+   matching gateways to gw_uri_avp (see Overview section). If optional
544
+   pseudo variable argument is included, caller's URI is taken from it. If
545
+   pseudo variable argument is not included, caller's URI is taken from
546
+   rpid_avp or, if rpid_avp value is empty, from From URI. Returns 1 or -1
455 547
    depending on success.
456 548
 
457
-   Execution time of load_gws() function is O(N) * O(M), where N
458
-   is number of different prefix lengths and M is number of
459
-   collisions for matching prefix(es) in lcr hash table.
549
+   Execution time of load_gws() function is O(N) * O(M), where N is number
550
+   of different prefix lengths and M is number of collisions for matching
551
+   prefix(es) in lcr hash table.
460 552
 
461 553
    This function can be used from REQUEST_ROUTE.
462 554
 
463 555
    Example 1.24. load_gws usage
464 556
 ...
465 557
 if (!load_gws("$var(caller_uri)")) {
466
-        sl_send_reply("500", "Server Internal Error - Cannot load gatewa
467
-ys");
558
+        sl_send_reply("500", "Server Internal Error - Cannot load gateways");
468 559
         exit;
469 560
 };
470 561
 ...
471 562
 
472
-1.4.2.  load_gws_from_grp(group-id)
563
+4.2.  load_gws_from_grp(group-id)
473 564
 
474
-   Loads URI schemes, IP addresses, hostnames, ports, and
475
-   transports of gateways that belong to a given group to
476
-   gw_uri_avp. group-id argument is a string that may contain
477
-   pseudo-variables. Its value must be a a string of digits that
478
-   are converted to an integer group id. Returns 1 or -1 depending
479
-   on success.
565
+   Loads URI schemes, IP addresses, hostnames, ports, and transports of
566
+   gateways that belong to a given group to gw_uri_avp. group-id argument
567
+   is a string that may contain pseudo-variables. Its value must be a a
568
+   string of digits that are converted to an integer group id. Returns 1
569
+   or -1 depending on success.
480 570
 
481
-   Execution time of load_gws_from_grp() function is O(N), where N
482
-   is number of gateways.
571
+   Execution time of load_gws_from_grp() function is O(N), where N is
572
+   number of gateways.
483 573
 
484 574
    This function can be used from REQUEST_ROUTE.
485 575
 
486 576
    Example 1.25. load_gws_from_grp usage
487 577
 ...
488 578
 if (!load_gws_from_grp("1")) {
489
-        sl_send_reply("500", "Server Internal Error - Cannot load gatewa
490
-ys from group 1");
579
+        sl_send_reply("500", "Server Internal Error - Cannot load gateways from
580
+group 1");
491 581
         exit;
492 582
 };
493 583
 ...
494 584
 
495 585
 if (!load_gws_from_grp("$avp(s:gateway_group)")) {
496
-        sl_send_reply("500", "Server Internal Error - Cannot load gatewa
497
-ys");
586
+        sl_send_reply("500", "Server Internal Error - Cannot load gateways");
498 587
         exit;
499 588
 };
500 589
 ...
501 590
 
502
-1.4.3.  next_gw()
591
+4.3.  next_gw()
503 592
 
504
-   Upon first call, replaces URI scheme, host, port, and transport
505
-   of Request-URI by the values stored in first gw_uri_avp and
506
-   destroys that AVP (see Overview section). Saves user part of
507
-   Request-URI into ruri_user_avp for use in subsequent next_gw()
508
-   calls.
593
+   Upon first call, replaces URI scheme, host, port, and transport of
594
+   Request-URI by the values stored in first gw_uri_avp and destroys that
595
+   AVP (see Overview section). Saves user part of Request-URI into
596
+   ruri_user_avp for use in subsequent next_gw() calls.
509 597
 
510
-   Upon subsequent calls, appends a new branch URI to the request,
511
-   where URI scheme, host, port, and transport of are taken from
512
-   values stored in the first gw_uri_avp and destroys that AVP.
513
-   URI user is taken from ruri_user_avp.
598
+   Upon subsequent calls, appends a new branch URI to the request, where
599
+   URI scheme, host, port, and transport of are taken from values stored
600
+   in the first gw_uri_avp and destroys that AVP. URI user is taken from
601
+   ruri_user_avp.
514 602
 
515 603
    As a side effect, stores gateway's flags to flags_avp.
516 604
 
517
-   Returns 1 on success and -1 if there were no gateways left or
518
-   if an error occurred (see syslog).
605
+   Returns 1 on success and -1 if there were no gateways left or if an
606
+   error occurred (see syslog).
519 607
 
520 608
    Must be preceded by successful load_gws() call.
521 609
 
... ...
@@ -537,15 +625,15 @@ if (!next_gw()) {
537 625
 };
538 626
 ...
539 627
 
540
-1.4.4.  from_gw([pvar])
628
+4.4.  from_gw([pvar])
541 629
 
542
-   Checks if request came from IP address of a gateway. IP address
543
-   to be checked is either taken from source IP address of the
544
-   request or (if present) from pseudo variable argument. As a
545
-   side effect, stores gateway's flags to flags_avp.
630
+   Checks if request came from IP address of a gateway. IP address to be
631
+   checked is either taken from source IP address of the request or (if
632
+   present) from pseudo variable argument. As a side effect, stores
633
+   gateway's flags to flags_avp.
546 634
 
547
-   Execution time of from_gw() function is O(log N), where N is
548
-   number of gateways.
635
+   Execution time of from_gw() function is O(log N), where N is number of
636
+   gateways.
549 637
 
550 638
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
551 639
    ONREPLY_ROUTE.
... ...
@@ -564,15 +652,14 @@ if (from_gw("$si")) {
564 652
 };
565 653
 ...
566 654
 
567
-1.4.5.  from_gw_grp(group-id)
655
+4.5.  from_gw_grp(group-id)
568 656
 
569
-   Checks if request came from IP address of a gateway that
570
-   belongs to the given group (integer string). Sets or resets a
571
-   message flag depending on whether the gateway supports directed
572
-   media.
657
+   Checks if request came from IP address of a gateway that belongs to the
658
+   given group (integer string). Sets or resets a message flag depending
659
+   on whether the gateway supports directed media.
573 660
 
574
-   Execution time of from_gw_grp() function is O(log N), where N
575
-   is number of gateways.
661
+   Execution time of from_gw_grp() function is O(log N), where N is number
662
+   of gateways.
576 663
 
577 664
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
578 665
    ONREPLY_ROUTE.
... ...
@@ -584,14 +671,14 @@ if (from_gw_grp("1")) {
584 671
 };
585 672
 ...
586 673
 
587
-1.4.6.  to_gw([group-id])
674
+4.6.  to_gw([group-id])
588 675
 
589
-   Checks if in-dialog request goes to a gateway. If an optional
590
-   group-id (integer string) is given, only gateways belonging to
591
-   this group are checked.
676
+   Checks if in-dialog request goes to a gateway. If an optional group-id
677
+   (integer string) is given, only gateways belonging to this group are
678
+   checked.
592 679
 
593
-   Execution time of to_gw() function is O(log N), where N is
594
-   number of gateways.
680
+   Execution time of to_gw() function is O(log N), where N is number of
681
+   gateways.
595 682
 
596 683
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
597 684
 
... ...
@@ -611,12 +698,15 @@ if (to_gw("1")) {
611 698
 };
612 699
 ...
613 700
 
614
-1.5. Exported MI Commands
701
+5. Exported MI Commands
615 702
 
616
-1.5.1. lcr_reload
703
+   5.1. lcr_reload
704
+   5.2. lcr_gw_dump
705
+   5.3. lcr_lcr_dump
617 706
 
618
-   Causes lcr module to re-read the contents of gateway table into
619
-   memory.
707
+5.1. lcr_reload
708
+
709
+   Causes lcr module to re-read the contents of gateway table into memory.
620 710
 
621 711
    Name: lcr_reload
622 712
 
... ...
@@ -626,10 +716,9 @@ if (to_gw("1")) {
626 716
                 :lcr_reload:_reply_fifo_file_
627 717
                 _empty_line_
628 718
 
629
-1.5.2. lcr_gw_dump
719
+5.2. lcr_gw_dump
630 720
 
631
-   Causes lcr module to dump the contents of its in-memory gw
632
-   table.
721
+   Causes lcr module to dump the contents of its in-memory gw table.
633 722
 
634 723
    Name: lcr_gw_dump
635 724
 
... ...
@@ -639,10 +728,9 @@ if (to_gw("1")) {
639 728
                 :lcr_gw_dump:_reply_fifo_file_
640 729
                 _empty_line_
641 730
 
642
-1.5.3. lcr_lcr_dump
731
+5.3. lcr_lcr_dump
643 732
 
644
-   Causes lcr module to dump the contents of its in-memory lcr
645
-   table.
733
+   Causes lcr module to dump the contents of its in-memory lcr table.
646 734
 
647 735
    Name: lcr_lcr_dump
648 736
 
... ...
@@ -652,10 +740,44 @@ if (to_gw("1")) {
652 740
                 :lcr_gw_dump:_reply_fifo_file_
653 741
                 _empty_line_
654 742
 
655
-1.6. Known Limitations
743
+6. Exported RPC Commands
744
+
745
+   6.1. lcr.reload
746
+   6.2. lcr.dump_gws
747
+   6.3. lcr.dump_lcr
748
+
749
+6.1. lcr.reload
750
+
751
+   Causes lcr module to re-read the contents of gateway table into memory.
752
+
753
+   Name: lcr.reload
754
+
755
+   Parameters: none
756
+
757
+   Example 1.33. lcr.reload RPC example
758
+                $ sercmd lcr.reload
759
+
760
+6.2. lcr.dump_gws
761
+
762
+   Causes lcr module to dump the contents of its in-memory gw table.
763
+
764
+   Parameters: none
765
+
766
+   Example 1.34. lcr.dump_gws RPC example
767
+                $ sercmd lcr.dump_gws
768
+
769
+6.3. lcr.dump_lcr
770
+
771
+   Causes lcr module to dump the contents of its in-memory lcr table.
772
+
773
+   Parameters: none
774
+
775
+   Example 1.35. lcr.dump_lcr RPC example
776
+                $ sercmd lcr.dump_lcr
777
+
778
+7. Known Limitations
656 779
 
657 780
    In-memory gateway and in-memory lcr table are switched by two
658
-   consecutive machine instructions. If lcr reload process is
659
-   interrupted after the first one, in-memory gateway table does
660
-   not match in-memory lcr table until execution of lcr reload
661
-   process is resumed.
781
+   consecutive machine instructions. If lcr reload process is interrupted
782
+   after the first one, in-memory gateway table does not match in-memory
783
+   lcr table until execution of lcr reload process is resumed.