Debian Codegraph @

src/modules/rr/README

raw
1 rr Module
2
3 Jan Janak
4
5 FhG FOKUS
6
7 Bogdan-Andrei Iancu
8
9 Voice Sistem SRL
10
11 Carsten Bock
12
13 ng-voice.com
14
15 Edited by
16
17 Jan Janak
18
19 Bogdan-Andrei Iancu
20
21 Copyright © 2003 FhG FOKUS
22
23 Copyright © 2005 Voice Sistem SRL
24
25 Copyright © 2011 Carsten Bock, [email protected]
26 __________________________________________________________________
27
28 Table of Contents
29
30 1. Admin Guide
31
32 1. Overview
33 2. Dialog support
34 3. Dependencies
35
36 3.1. Kamailio Modules
37 3.2. External Libraries or Applications
38
39 4. Parameters
40
41 4.1. enable_full_lr (integer)
42 4.2. append_fromtag (integer)
43 4.3. enable_double_rr (integer)
44 4.4. add_username (integer)
45 4.5. enable_socket_mismatch_warning (integer)
46 4.6. custom_user_avp (avp string)
47 4.7. force_send_socket (int)
48 4.8. ignore_sips (int)
49 4.9. sockname_mode (int)
50 4.10. loose_route_mode (int)
51
52 5. Functions
53
54 5.1. loose_route()
55 5.2. loose_route_preloaded()
56 5.3. loose_route_mode(vmode)
57 5.4. record_route([sparams])
58 5.5. remove_record_route()
59 5.6. record_route_preset(string [,string2])
60 5.7. record_route_advertised_address(address)
61 5.8. add_rr_param(param)
62 5.9. check_route_param(re)
63 5.10. is_direction(dir)
64 5.11. rr_next_hop_route()
65
66 6. Exported Pseudo Variables
67
68 6.1. $route_uri
69
70 2. Developer Guide
71
72 1. Available Functions
73
74 1.1. record_route(string)
75 1.2. record_route_advertised_address(string)
76 1.3. add_rr_param(msg, param)
77 1.4. check_route_param(msg, re)
78 1.5. is_direction(msg, dir)
79 1.6. get_route_param(msg, name, val)
80 1.7. register_rrcb(callback, param)
81
82 2. Examples
83
84 List of Examples
85
86 1.1. Dialog support in RR module
87 1.2. Set enable_full_lr parameter
88 1.3. Set append_fromtag parameter
89 1.4. Set enable_double_rr parameter
90 1.5. Set enable_double_rr to 2 to always have two explicit RR headers
91 1.6. Set add_username parameter
92 1.7. enable_socket_mismatch_warning usage
93 1.8. custom_user_avp usage
94 1.9. Set force_send_socket parameter
95 1.10. Set ignore_sips parameter
96 1.11. Set sockname_mode parameter
97 1.12. Set loose_route_mode parameter
98 1.13. loose_route usage
99 1.14. loose_route_preloaded usage
100 1.15. loose_route_mode usage
101 1.16. record_route usage
102 1.17. remove_record_route usage
103 1.18. record_route_preset usage
104 1.19. record_route_advertised_address usage
105 1.20. add_rr_param usage
106 1.21. check_route_param usage
107 1.22. is_direction usage
108 1.23. rr_next_hop_route usage
109 1.24. $route_uri
110 2.1. record_route usage
111 2.2. record_route_advertised_address usage
112 2.3. Loading RR module's API from another module
113
114 Chapter 1. Admin Guide
115
116 Table of Contents
117
118 1. Overview
119 2. Dialog support
120 3. Dependencies
121
122 3.1. Kamailio Modules
123 3.2. External Libraries or Applications
124
125 4. Parameters
126
127 4.1. enable_full_lr (integer)
128 4.2. append_fromtag (integer)
129 4.3. enable_double_rr (integer)
130 4.4. add_username (integer)
131 4.5. enable_socket_mismatch_warning (integer)
132 4.6. custom_user_avp (avp string)
133 4.7. force_send_socket (int)
134 4.8. ignore_sips (int)
135 4.9. sockname_mode (int)
136 4.10. loose_route_mode (int)
137
138 5. Functions
139
140 5.1. loose_route()
141 5.2. loose_route_preloaded()
142 5.3. loose_route_mode(vmode)
143 5.4. record_route([sparams])
144 5.5. remove_record_route()
145 5.6. record_route_preset(string [,string2])
146 5.7. record_route_advertised_address(address)
147 5.8. add_rr_param(param)
148 5.9. check_route_param(re)
149 5.10. is_direction(dir)
150 5.11. rr_next_hop_route()
151
152 6. Exported Pseudo Variables
153
154 6.1. $route_uri
155
156 1. Overview
157
158 The module contains record routing logic.
159
160 2. Dialog support
161
162 Kamailio is basically only a transaction stateful proxy, without any
163 dialog support build in. There are many features/services which
164 actually require a dialog awareness, like storing the information in
165 the dialog creation stage, information which will be used during the
166 whole dialog existence.
167
168 The most urging example is NAT traversal, in dealing with the within
169 the dialog INVITEs (re-INVITEs). When processing the initial INVITE,
170 the proxy detects if the caller or callee is behind some NAT and fixes
171 the signalling and media parts - since not all the detection mechanism
172 are available for within the dialog requests (like usrloc), to be able
173 to fix correspondingly the sequential requests, the proxy must remember
174 that the original request was NAT processed. There are many other cases
175 where dialog awareness fixes or helps.
176
177 The solution is to store additional dialog-related information in the
178 routing set (Record-Route/Route headers), headers which show up in all
179 sequential requests. So any information added to the Record-Route
180 header will be found (with no direction dependencies) in Route header
181 (corresponding to the proxy address).
182
183 As storage container, the parameters of the Record-Route / Route header
184 will be used - Record-Route parameters mirroring are reinforced by RFC
185 3261 (see 12.1.1 UAS behavior).
186
187 For this purpose, the module offers the following functions:
188 * add_rr_param() - see Section 5.8, “add_rr_param(param)”
189 * check_route_param() - see Section 5.9, “check_route_param(re)”
190
191 Example 1.1. Dialog support in RR module
192 ...
193 UAC Kamailio PROXY UAS
194
195 ---- INVITE ------> record_route() ----- INVITE ---->
196 add_rr_param(";foo=true")
197
198 --- reINVITE -----> loose_route() ---- reINVITE --->
199 check_route_param(";foo=true")
200
201 <-- reINVITE ------ loose_route() <--- reINVITE ----
202 check_route_param(";foo=true")
203
204 <------ BYE ------- loose_route() <----- BYE -------
205 check_route_param(";foo=true")
206 ...
207
208 3. Dependencies
209
210 3.1. Kamailio Modules
211 3.2. External Libraries or Applications
212
213 3.1. Kamailio Modules
214
215 The following modules must be loaded before this module:
216 * (optional) The "outbound" module is needed for outbound routing as
217 per RFC 5626.
218
219 3.2. External Libraries or Applications
220
221 The following libraries or applications must be installed before
222 running Kamailio with this module loaded:
223 * None.
224
225 4. Parameters
226
227 4.1. enable_full_lr (integer)
228 4.2. append_fromtag (integer)
229 4.3. enable_double_rr (integer)
230 4.4. add_username (integer)
231 4.5. enable_socket_mismatch_warning (integer)
232 4.6. custom_user_avp (avp string)
233 4.7. force_send_socket (int)
234 4.8. ignore_sips (int)
235 4.9. sockname_mode (int)
236 4.10. loose_route_mode (int)
237
238 4.1. enable_full_lr (integer)
239
240 If set to 1 then “;lr=on” instead of just “;lr” will be used. This is
241 to overcome problems with broken UAs which strip “;lr” parameter when
242 generating Route header fields from Record-Route (“;lr=on” seems to
243 help).
244
245 Default value is 0 (no).
246
247 Example 1.2. Set enable_full_lr parameter
248 ...
249 modparam("rr", "enable_full_lr", 1)
250 ...
251
252 4.2. append_fromtag (integer)
253
254 If turned on, request's from-tag is appended to record-route; that's
255 useful for understanding whether subsequent requests (such as BYE) come
256 from caller (route's from-tag==BYE's from-tag) or callee (route's
257 from-tag==BYE's to-tag)
258
259 Default value is 1 (yes).
260
261 Example 1.3. Set append_fromtag parameter
262 ...
263 modparam("rr", "append_fromtag", 0)
264 ...
265
266 4.3. enable_double_rr (integer)
267
268 There are some situations when the server needs to insert two
269 Record-Route header fields instead of one. For example when using two
270 disconnected networks or doing cross-protocol forwarding from UDP->TCP.
271 This parameter enables inserting of 2 Record-Routes. The server will
272 later remove both of them.
273
274 Double record-routing does not occur when outbound is used for a
275 request.
276
277 Default value is 1 (yes).
278
279 Example 1.4. Set enable_double_rr parameter
280 ...
281 modparam("rr", "enable_double_rr", 0)
282 ...
283
284 Some useragents (e. g. Linphone) incorrectly use UDP transport for
285 subsequent requests in dialog, despite being configured to use another
286 SIP transport protocol. This can be worked around by setting
287 Record-Route header with explicit transport attribute. But
288 enable_double_rr enabled in default mode omits transport attribute from
289 being added to header if it detects that both sender and receiver use
290 same protocol (e. g. TCP or TLS), and this results in UDP being used by
291 such broken clients. Set enable_double_rr to value 2 to always have two
292 RR headers with transport attributes explicitly set.
293
294 Example 1.5. Set enable_double_rr to 2 to always have two explicit RR
295 headers
296 ...
297 modparam("rr", "enable_double_rr", 2)
298 ...
299
300 4.4. add_username (integer)
301
302 If set to a non 0 value (which means yes), the username part will be
303 also added in the Record-Route URI.
304
305 This option cannot be set when the “outbound” module is loaded before
306 this module as outbound uses the username part of Record-Route URIs to
307 store flow-tokens.
308
309 Default value is 0 (no).
310
311 Example 1.6. Set add_username parameter
312 ...
313 modparam("rr", "add_username", 1)
314 ...
315
316 4.5. enable_socket_mismatch_warning (integer)
317
318 When a preset record-route header is forced in Kamailio config and the
319 host from the record-route header is not the same as the host server, a
320 warning will be printed out in the logs. The
321 'enable_socket_mismatch_warning' parameter enables or disables the
322 warning. When Kamailio is behind a NATed firewall, we don't want this
323 warning to be printed for every bridged call.
324
325 Default value is 1 (yes).
326
327 Example 1.7. enable_socket_mismatch_warning usage
328 ...
329 modparam("rr", "enable_socket_mismatch_warning", 0)
330 ...
331
332 4.6. custom_user_avp (avp string)
333
334 When add_username is enabled, a call to record_route will add the
335 username of the RequestURI to the Record-Route URI. This parameter
336 allows you to set up an AVP with which you can customise the username
337 to be added in the Record-Route URI.
338
339 Default value: if not set, the std add_username behaviour is used -
340 i.e. Request URI username.
341
342 Example 1.8. custom_user_avp usage
343 ...
344 modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")
345
346 #usage in cfg file
347 $avp(RR_CUSTOM_USER_AVP)="mo";
348 record_route();
349 ...
350
351 4.7. force_send_socket (int)
352
353 If set to 1, local socket is forced even for single Record-Route,
354 otherwise is done on double Record-Route (should that be enabled).
355
356 When use of “outbound” is enabled, the socket is not forced.
357
358 Default value is 0.
359
360 Example 1.9. Set force_send_socket parameter
361 ...
362 modparam("rr", "force_send_socket", 1)
363 ...
364
365 4.8. ignore_sips (int)
366
367 If set to 1, the Record-Route header are build with 'sip' schema
368 always, ignoring the presence of 'sips' schema in request URI.
369
370 Default value is 0 (use 'sips' if present in R-URI).
371
372 Example 1.10. Set ignore_sips parameter
373 ...
374 modparam("rr", "ignore_sips", 1)
375 ...
376
377 4.9. sockname_mode (int)
378
379 If set to 1, the Record-Route URI is built to contain socket name in
380 'sn' parameter and then it is used to lookup the local socket for Route
381 header processing.
382
383 Default value is 0.
384
385 Example 1.11. Set sockname_mode parameter
386 ...
387 modparam("rr", "sockname_mode", 1)
388 ...
389
390 4.10. loose_route_mode (int)
391
392 Controls the behaviour of loose_route() in the same manner as the value
393 of the parameter for for function loose_route_mode(val), in a global
394 manner.
395
396 Default value is 0.
397
398 Example 1.12. Set loose_route_mode parameter
399 ...
400 modparam("rr", "loose_route_mode", 1)
401 ...
402
403 5. Functions
404
405 5.1. loose_route()
406 5.2. loose_route_preloaded()
407 5.3. loose_route_mode(vmode)
408 5.4. record_route([sparams])
409 5.5. remove_record_route()
410 5.6. record_route_preset(string [,string2])
411 5.7. record_route_advertised_address(address)
412 5.8. add_rr_param(param)
413 5.9. check_route_param(re)
414 5.10. is_direction(dir)
415 5.11. rr_next_hop_route()
416
417 5.1. loose_route()
418
419 The function performs routing of SIP requests which contain a route
420 set. The name is a little bit confusing, as this function also routes
421 requests which are in the “strict router” format.
422
423 This function is usually used to route in-dialog requests (like ACK,
424 BYE, reINVITE). Nevertheless also out-of-dialog requests can have a
425 “pre-loaded route set” and my be routed with loose_route. It also takes
426 care of translating between strict-routers and loose-router.
427
428 The loose_route function analyzes the Route: headers in the requests.
429 If there is no Route: header, the function returns FALSE and routing
430 should be done with normal lookup functions. If a Route: header is
431 found, the function returns 1 and behaves as described in section 16.12
432 of RFC 3261. There is only one exception: If the request is
433 out-of-dialog (no to-tag) and there is only one Route: header
434 indicating the local proxy, then the Route: header is removed and the
435 function returns FALSE.
436
437 When the “outbound” module was loaded before this module and the Route:
438 header contains a username part this function will attempt to use the
439 username part as a flow-token for routing. If route calculation based
440 on flow-token succeeds, function returns TRUE even if there is only one
441 Route: header indicating the local proxy.
442
443 Make sure your loose_routing function can't be used by attackers to
444 bypass proxy authorization.
445
446 The loose_routing topic is very complex. See the RFC3261 for more
447 details (grep for “route set” is a good starting point in this
448 comprehensive RFC).
449
450 Return codes:
451 * 1 - route calculation has been successful
452 * 2 - route calculation based on flow-token has been successful
453 * -1 - route calculation has been unsuccessful
454 * -2 - outbound flow-token shows evidence of tampering
455 * -3 - next hop is taken from a preloaded route set
456
457 This function can be used from REQUEST_ROUTE.
458
459 Example 1.13. loose_route usage
460 ...
461 loose_route();
462 ...
463
464 5.2. loose_route_preloaded()
465
466 The function is similar to `loose_route()`, but it returns 1 (true)
467 when the Route header is preloaded (is in an initial request) and -1
468 (false) if processing of the Route header failed or it is for requests
469 within dialog.
470
471 It is a convenient function to use for routing initial requests on an
472 edge proxy that adds Path header to REGISTER requests.
473
474 This function can be used from REQUEST_ROUTE.
475
476 Example 1.14. loose_route_preloaded usage
477 ...
478 if(!loose_route_preloaded()) {
479 sl_send_reply("404" "Preloaded route expected");
480 exit;
481 }
482 ...
483
484 5.3. loose_route_mode(vmode)
485
486 The function is similar to `loose_route()`, but it accepts route mode
487 bitmask as vmode parameter.
488
489 If bit one is set, then do only loose routing processing, skipping the
490 testing of r-uri==myself for performing strict routing. If not, behave
491 like loose_route(). If bit two is set, then skip flow tokens
492 processing.
493
494 First bit is convenient to use with application servers that set the
495 Contact URI to SIP server address.
496
497 This function can be used from REQUEST_ROUTE.
498
499 Example 1.15. loose_route_mode usage
500 ...
501 if(has_totag() and uri==myself) {
502 if(loose_route_mode("1")) {
503 rewritehostport("my.app.server:5090");
504 t_relay();
505 exit;
506 }
507 }
508 ...
509
510 5.4. record_route([sparams])
511
512 The function adds a new Record-Route header field. The header field
513 will be inserted in the message before any other Record-Route header
514 fields.
515
516 If any string is passed as parameter, it will be appended as URI
517 parameter to the Record-Route header. The string must follow the
518 “;name=value” scheme and it may contain pseudo-variables.
519
520 When the “outbound” module was loaded before this module this function
521 will determine whether outbound is required for the request and
522 generate and add a flow-token as the username part of the
523 Record-Route-URI.
524
525 Note: if append From-tag is enabled and the function is used for
526 requests within dialog, it must be executed after loose_route() in
527 order to detect properly the direction.
528
529 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
530 FAILURE_ROUTE.
531
532 Example 1.16. record_route usage
533 ...
534 record_route();
535 ...
536
537 5.5. remove_record_route()
538
539 The function removes the internal lumps added by record_route()
540 functions.
541
542 Can be used to revert adding Record-Route header(s).
543
544 This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
545
546 Example 1.17. remove_record_route usage
547 ...
548 remove_record_route();
549 ...
550
551 5.6. record_route_preset(string [,string2])
552
553 This function will put the string params into Record-Route, avoid to
554 use it unless you know what you are doing.
555
556 Meaning of the parameters is as follows:
557 * string - String to be inserted into the first header field; it may
558 contain pseudo-variables.
559 * string2 - String to be inserted into the second header field; it
560 may contain pseudo-variables.
561
562 Note: If 'string2' is present, then the 'string' param is pointing to
563 the outbound interface and the 'string2' param is pointing to the
564 inbound interface.
565
566 Note: The value of parameters must not contain the SIP protocol scheme
567 (sip: or sips:), one is added based on routing requirements. Thus the
568 value has to be like "address:port;parameters", the port and parameters
569 are optional. If the second parameter is provided, do not forget to add
570 the parameter "r2=on" so the proxy processes both corresponding Route
571 headers at once.
572
573 When the “outbound” module was loaded before this module this function
574 will determine whether outbound is required for the request and
575 generate and add a flow-token as the username part of the
576 Record-Route-URI.
577
578 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
579 FAILURE_ROUTE.
580
581 Example 1.18. record_route_preset usage
582 ...
583 record_route_preset("1.2.3.4:5090");
584 ...
585
586 5.7. record_route_advertised_address(address)
587
588 The function adds a new Record-Route header field using the address
589 given. The header field will be inserted in the message before any
590 other Record-Route header fields.
591
592 When the “outbound” module was loaded before this module this function
593 will determine whether outbound is required for the request and
594 generate and add a flow-token as the username part of the
595 Record-Route-URI.
596
597 Meaning of the parameter is as follows:
598 * address - Advertised address to use in the header; it may contain
599 pseudo-variables.
600
601 If double record-routing is enabled two Record-Route headers will be
602 inserted with the same given address with different transports if the
603 transport changes.
604
605 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
606 FAILURE_ROUTE.
607
608 Example 1.19. record_route_advertised_address usage
609 ...
610 record_route_advertised_address("1.2.3.4:5080");
611 ...
612
613 5.8. add_rr_param(param)
614
615 Adds a parameter to the Record-Route URI (param must be in
616 “;name=value” format. The function may be called also before or after
617 the record_route(), record_route_advertised_address(), and
618 record_route_preset() calls (see Section 5.4, “record_route([sparams])”
619 or Section 5.7, “record_route_advertised_address(address)”)).
620
621 Meaning of the parameters is as follows:
622 * param - String containing the URI parameter to be added. It must
623 follow the “;name=value” scheme; it may contain pseudo-variables.
624
625 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
626 FAILURE_ROUTE.
627
628 Example 1.20. add_rr_param usage
629 ...
630 add_rr_param(";nat=yes");
631 ...
632
633 5.9. check_route_param(re)
634
635 The function checks if the URI parameters of the local Route header
636 (corresponding to the local server) matches the given regular
637 expression. It must be called after loose_route() (see Section 5.1,
638 “loose_route()”).
639
640 Meaning of the parameters is as follows:
641 * re - regular expression to check against the Route URI parameters.
642
643 This function can be used from REQUEST_ROUTE.
644
645 Example 1.21. check_route_param usage
646 ...
647 if (check_route_param("nat=yes")) {
648 setflag(6);
649 }
650 ...
651
652 5.10. is_direction(dir)
653
654 The function checks the flow direction of in-dialog requests. This
655 function uses the “ftag” parameter from the Route header, therefore the
656 append_fromtag (see ??? module parameter must be enabled. Also this
657 must be called only after loose_route() (see Section 5.1,
658 “loose_route()”).
659
660 The function returns true if the “dir” is the same with the request's
661 flow direction.
662
663 The “downstream” direction means that the request is in the same
664 direction as the initial request that created the dialog.
665
666 Meaning of the parameters is as follows:
667 * dir - string containing the direction to be checked. It may be
668 “upstream” (from callee to caller) or “downstream” (caller to
669 callee).
670
671 This function can be used from REQUEST_ROUTE.
672
673 Example 1.22. is_direction usage
674 ...
675 if (is_direction("downstream")) {
676 xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
677 } else {
678 xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
679 }
680 ...
681
682 5.11. rr_next_hop_route()
683
684 The function returns 1 (true) if there is a Route header for the next
685 hop address. It has to be used after loose_route(), when the local
686 Route headers are processed.
687
688 This function can be used from ANY_ROUTE.
689
690 Example 1.23. rr_next_hop_route usage
691 ...
692 if(loose_route) {
693 if(rr_next_hop_route()) {
694 # next hop address is from Route header
695 }
696
697 }
698 ...
699
700 6. Exported Pseudo Variables
701
702 6.1. $route_uri
703
704 6.1. $route_uri
705
706 Returns the URI of the top route-header.
707
708 Example 1.24. $route_uri
709 ...
710 xdbg("Route-URI is: $route_uri\n");
711 ...
712
713 Chapter 2. Developer Guide
714
715 Table of Contents
716
717 1. Available Functions
718
719 1.1. record_route(string)
720 1.2. record_route_advertised_address(string)
721 1.3. add_rr_param(msg, param)
722 1.4. check_route_param(msg, re)
723 1.5. is_direction(msg, dir)
724 1.6. get_route_param(msg, name, val)
725 1.7. register_rrcb(callback, param)
726
727 2. Examples
728
729 The RR module provides an internal API to be used by other Kamailio
730 modules. The API offers support for SIP dialog based functionalities -
731 for more about the dialog support offered by RR module, see Section 2,
732 “Dialog support”.
733
734 For internal(non-script) usage, the RR module offers to other module
735 the possibility to register callback functions to be executed each time
736 a local Route header is processed. The callback function will receive
737 as parameter the register parameter and the Route header parameter
738 string.
739
740 1. Available Functions
741
742 1.1. record_route(string)
743 1.2. record_route_advertised_address(string)
744 1.3. add_rr_param(msg, param)
745 1.4. check_route_param(msg, re)
746 1.5. is_direction(msg, dir)
747 1.6. get_route_param(msg, name, val)
748 1.7. register_rrcb(callback, param)
749
750 1.1. record_route(string)
751
752 The function adds a new Record-Route header field. The header field
753 will be inserted in the message before any other Record-Route header
754 fields.
755
756 If any string is passed as parameter, it will be appended as URI
757 parameter to the Record-Route header. The string must follow the
758 “;name=value” scheme and it may contain pseudo-variables.
759
760 This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
761 FAILURE_ROUTE.
762
763 Example 2.1. record_route usage
764 ...
765 record_route();
766 ...
767
768 1.2. record_route_advertised_address(string)
769
770 This function will add the string into a new Record-Route header field.
771 Don't use unless you know what you are doing. The header field will be
772 inserted in the message before any other Record-Route header fields.
773
774 Meaning of the parameters is as follows:
775 * string - String to be inserted into the header field.
776
777 Calls to add_rr_param() will add parameters to the Record-Route header.
778 Note: A second Record-Route will be inserted if the transport used on
779 the inbound and outbound interfaces changes.
780
781 Example 2.2. record_route_advertised_address usage
782 ...
783 record_route_advertised_address("1.2.3.4:5090");
784 ...
785
786 1.3. add_rr_param(msg, param)
787
788 Adds a parameter to the requests' Record-Route URI (param must be in
789 “;name=value” format).
790
791 The function returns 0 on success. Otherwise, -1 is returned.
792
793 Meaning of the parameters is as follows:
794 * struct sip_msg* msg - request that will has the parameter “param”
795 added to its Record-Route header.
796 * str* param - parameter to be added to the Record-Route header - it
797 must be in “;name=value” format.
798
799 1.4. check_route_param(msg, re)
800
801 The function checks for the request “msg” if the URI parameters of the
802 local Route header (corresponding to the local server) matches the
803 given regular expression “re”. It must be called after the loose_route
804 was done.
805
806 The function returns 0 on success. Otherwise, -1 is returned.
807
808 Meaning of the parameters is as follows:
809 * struct sip_msg* msg - request that will has the Route header
810 parameters checked.
811 * regex_t* param - compiled regular expression to be checked against
812 the Route header parameters.
813
814 1.5. is_direction(msg, dir)
815
816 The function checks the flow direction of the request “msg”. As for
817 checking it's used the “ftag” Route header parameter, the
818 append_fromtag (see ??? module parameter must be enables. Also this
819 must be called only after the loose_route is done.
820
821 The function returns 0 if the “dir” is the same with the request's flow
822 direction. Otherwise, -1 is returned.
823
824 Meaning of the parameters is as follows:
825 * struct sip_msg* msg - request that will have the direction checked.
826 * int dir - direction to be checked against. It may be
827 “RR_FLOW_UPSTREAM” or “RR_FLOW_DOWNSTREAM”.
828
829 1.6. get_route_param(msg, name, val)
830
831 The function searches in the “msg”'s Route header parameters the
832 parameter called “name” and returns its value into “val”. It must be
833 called only after the loose_route is done.
834
835 The function returns 0 if parameter was found (even if it has no
836 value). Otherwise, -1 is returned.
837
838 Meaning of the parameters is as follows:
839 * struct sip_msg* msg - request that will have the Route header
840 parameter searched.
841 * str *name - contains the Route header parameter to be searched.
842 * str *val - returns the value of the searched Route header parameter
843 if found. It might be empty string if the parameter had no value.
844
845 1.7. register_rrcb(callback, param)
846
847 The function registers a new callback (along with its parameter). The
848 callback will be called when a loose route will be performed for the
849 local address.
850
851 The function returns 0 on success. Otherwise, -1 is returned.
852
853 Meaning of the parameters is as follows:
854 * rr_cb_t callback - callback function to be registered.
855 * void *param - parameter to be passed to the callback function.
856
857 2. Examples
858
859 Example 2.3. Loading RR module's API from another module
860 ...
861 #include "../rr/api.h"
862 ...
863 struct rr_binds my_rrb;
864 ...
865 ...
866 /* load the RR API */
867 if (load_rr_api( &my_rrb )!=0) {
868 LM_ERR("can't load RR API\n");
869 goto error;
870 }
871 ...
872 ...
873 /* register a RR callback */
874 if (my_rrb.register_rrcb(my_callback,0))!=0) {
875 LM_ERR("can't register RR callback\n");
876 goto error;
877 }
878 ...