Browse code

Merge remote branch 'origin/sr_3.0'

* origin/sr_3.0:
htable(k): fix non-init act. ctx in event route execution
tm: fix/support changing r-uris and path in branch routes
tm: support for changing dst_uri in branch routes
registrar: Fix handling of cases where contacts > max_contacts
domain: Do not report errors when domain cannot be extracted from URI.
parse_sip_msg_uri: Log broken URIs only when debugging is enabled.
modules/lcr: documentation improvement
sctp: count rejects sent to the remote peer (stats)
avp_db: Removes a spurious error message.
ctl: missing ifdef (minor)
event parser: Add missing string boundary checks to event_parser func.
tm: Number of fixes in code and documentation for serial forking.
Implements function reset_path_vector.

Andrei Pelinescu-Onciul authored on 28/10/2009 15:41:39
Showing 8 changed files
... ...
@@ -250,11 +250,13 @@ static int mod_init(void)
250 250
 						payload_proto_name(l->data_proto), l->name,
251 251
 						l->port?l->port:DEFAULT_CTL_PORT);
252 252
 				break;
253
+#ifdef USE_FIFO
253 254
 			case FIFO_SOCK:
254 255
 				DBG("        [%s:fifo]         %s\n",
255 256
 						payload_proto_name(l->data_proto), l->name);
256 257
 				fd_no++; /* fifos use 2 fds */
257 258
 				break;
259
+#endif
258 260
 			default:
259 261
 				LOG(L_CRIT, "BUG: ctrl: listen protocol %d not supported\n",
260 262
 						l->proto);
... ...
@@ -813,6 +813,11 @@ if (to_any_gw()) {
813 813
    Causes lcr module to re-read the contents of gw and lcr tables into
814 814
    memory.
815 815
 
816
+   Reload fails if number of gateways is larger than value of constant
817
+   MAX_NO_OF_GWS in file lcr_mod.h, which defaults to 128. If you have
818
+   more than 128 gateways, you need to increase the value of this constant
819
+   and recompile lcr module.
820
+
816 821
    Name: lcr_reload
817 822
 
818 823
    Parameters: none
... ...
@@ -1012,6 +1012,15 @@ if (to_any_gw()) {
1012 1012
 			gw and lcr tables into memory.
1013 1013
 		</para>
1014 1014
 		<para>
1015
+			Reload fails if number of
1016
+			gateways is larger than value of constant
1017
+			MAX_NO_OF_GWS in file lcr_mod.h, which
1018
+			defaults to 128.  If you have more than 128
1019
+			gateways, you need
1020
+			to increase the value of this constant and recompile
1021
+			lcr module.
1022
+		</para>
1023
+		<para>
1015 1024
 		Name: <emphasis>lcr_reload</emphasis>
1016 1025
 		</para>
1017 1026
 		<para>Parameters: <emphasis>none</emphasis></para>
... ...
@@ -15,6 +15,106 @@ Juha Heinanen
15 15
    Revision $Revision$ $Date$
16 16
      __________________________________________________________________
17 17
 
18
+   1.1. Overview
19
+   1.2. Known Issues
20
+   1.3. Parameters
21
+
22
+        1.3.1. fr_timer (integer)
23
+        1.3.2. fr_inv_timer (integer)
24
+        1.3.3. max_inv_lifetime (integer)
25
+        1.3.4. max_noninv_lifetime (integer)
26
+        1.3.5. wt_timer (integer)
27
+        1.3.6. delete_timer (integer)
28
+        1.3.7. retr_timer1 (integer)
29
+        1.3.8. retr_timer2 (integer)
30
+        1.3.9. noisy_ctimer (integer)
31
+        1.3.10. restart_fr_on_each_reply (integer)
32
+        1.3.11. auto_inv_100 (integer)
33
+        1.3.12. auto_inv_100_reason (string)
34
+        1.3.13. unix_tx_timeout (integer)
35
+        1.3.14. aggregate_challenges (integer)
36
+        1.3.15. reparse_invite (integer)
37
+        1.3.16. ac_extra_hdrs (string)
38
+        1.3.17. blst_503 (integer)
39
+        1.3.18. blst_503_def_timeout (integer)
40
+        1.3.19. blst_503_min_timeout (integer)
41
+        1.3.20. blst_503_max_timeout (integer)
42
+        1.3.21. blst_methods_add (unsigned integer)
43
+        1.3.22. blst_methods_lookup (unsigned integer)
44
+        1.3.23. cancel_b_method (integer)
45
+        1.3.24. reparse_on_dns_failover (integer)
46
+        1.3.25. on_sl_reply (string)
47
+        1.3.26. fr_inv_timer_next (integer)
48
+        1.3.27. contacts_avp (string)
49
+        1.3.28. fr_timer_avp (string)
50
+        1.3.29. fr_inv_timer_avp (string)
51
+        1.3.30. unmatched_cancel (string)
52
+        1.3.31. ruri_matching (integer)
53
+        1.3.32. via1_matching (integer)
54
+        1.3.33. pass_provisional_replies (integer)
55
+        1.3.34. default_code (integer)
56
+        1.3.35. default_reason (string)
57
+        1.3.36. disable_6xx_block (integer)
58
+
59
+   1.4. Functions
60
+
61
+        1.4.1. t_relay_to_udp(ip, port), t_relay_to_udp(),
62
+                t_relay_to_tcp(ip, port) t_relay_to_tcp()
63
+                t_relay_to_tls(ip, port) t_relay_to_tls()
64
+                t_relay_to_sctp(ip, port) t_relay_to_sctp()
65
+
66
+        1.4.2. t_relay() t_relay(host, port)
67
+        1.4.3. t_on_failure(failure_route)
68
+        1.4.4. t_on_reply(onreply_route)
69
+        1.4.5. t_on_branch(branch_route)
70
+        1.4.6. append_branch()
71
+        1.4.7. t_newtran()
72
+        1.4.8. t_reply(code, reason_phrase)
73
+        1.4.9. t_lookup_request()
74
+        1.4.10. t_retransmit_reply()
75
+        1.4.11. t_release()
76
+        1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
77
+                t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip,
78
+                port) t_forward_nonack_tls(ip, port)
79
+                t_forward_nonack_sctp(ip, port)
80
+
81
+        1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout])
82
+        1.4.14. t_reset_fr()
83
+        1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
84
+        1.4.16. t_reset_max_lifetime()
85
+        1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval)
86
+        1.4.18. t_reset_retr()
87
+        1.4.19. t_set_auto_inv_100(0|1)
88
+        1.4.20. t_branch_timeout()
89
+        1.4.21. t_branch_replied()
90
+        1.4.22. t_any_timeout()
91
+        1.4.23. t_any_replied()
92
+        1.4.24. t_grep_status("code")
93
+        1.4.25. t_is_canceled()
94
+        1.4.26. t_is_expired()
95
+        1.4.27. t_relay_cancel()
96
+        1.4.28. t_lookup_cancel(), t_lookup_cancel(1)
97
+        1.4.29. t_drop_replies()
98
+        1.4.30. t_save_lumps()
99
+        1.4.31. t_load_contacts()
100
+        1.4.32. t_next_contacts()
101
+        1.4.33. t_check_trans()
102
+        1.4.34. t_set_disable_6xx(0|1)
103
+        1.4.35. t_set_disable_failover(0|1)
104
+
105
+   1.5. TM Module API
106
+
107
+        1.5.1. Defines
108
+        1.5.2. Functions
109
+
110
+              1.5.2.1. register_tmcb(cb_type, cb_func)
111
+              1.5.2.2. load_tm(*import_structure)
112
+              1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int
113
+                      *hash_index, unsigned int *label)
114
+
115
+              1.5.2.4. int t_continue(unsigned int hash_index, unsigned
116
+                      int label, struct action *route)
117
+
18 118
 1.1. Overview
19 119
 
20 120
    TM module enables stateful processing of SIP transactions. The main use
... ...
@@ -70,179 +170,7 @@ Note
70 70
    implemented in the TMX module: "modules_k/tmx". Check it to see if what
71 71
    you are looking for is there.
72 72
 
73
-1.2. Serial Forking Based on Q Value
74
-
75
-   A single SIP INVITE request may be forked to multiple destinations. We
76
-   call the set of all such destinations a destination set. Individual
77
-   elements within the destination sets are called branches. The script
78
-   writer can add URIs to the destination set from the configuration file,
79
-   or they can be loaded from the user location database, each registered
80
-   contact then becomes one branch in the destination set.
81
-
82
-   The default behavior of the tm module, if it encounters a SIP message
83
-   with multiple branches in the destination set, it to forward the SIP
84
-   message to all the branches in parallel. That means it sends the
85
-   message to all the branch destinations before it waits for replies from
86
-   any of them. This is the default behavior if you call t_relay() and
87
-   similar functions without anything else.
88
-
89
-   Another approach of handling multiple branches in a destination set it
90
-   serial forking. When configured to do serial forking, the server takes
91
-   the first branch out of the destination set, forwards the message to
92
-   its destination and waits for a reply or timeout. Only after a reply
93
-   has been received or the timeout occurred, the server takes another
94
-   destination from the destination set and tries again, until it receives
95
-   a positive final reply or until all branches from the destination set
96
-   have been tried.
97
-
98
-   Yet another, more sophisticated, way of handling multiple branches is
99
-   combined serial/parallel forking, where individual branches within the
100
-   destination set are assigned priorities. The order in which individual
101
-   branches are tried is then determined by their relative priority within
102
-   the destination set. Branches can be tried sequentially in the
103
-   descending priority order and all branches that have the same priority
104
-   can be tried in parallel. Such combined serial/parallel forking can be
105
-   achieved in the tm module with the help of functions t_load_contacts()
106
-   and t_next_contacts().
107
-
108
-   Every branch in the destination set is assigned a priority number, also
109
-   known as the q value. The q value is a floating point number in a range
110
-   0 to 1.0. The higher the q value number, the more priority is the
111
-   particular branch in the destination set is given. Branches with q
112
-   value 1.0 have maximum priority, such branches should be always tried
113
-   first in serial forking. Branches with q value 0 have the lowest
114
-   priority and they should by tried after all other branches with higher
115
-   priority in the destination set.
116
-
117
-   As an example, consider the following simple configuration file. When
118
-   the server receives an INVITE, it creates four branches for it with
119
-   usernames A through D and then forwards the request using t_relay():
120
-route {
121
-  seturi("sip:a@example.com");
122
-  append_branch("sip:b@example.com");
123
-  append_branch("sip:c@example.com");
124
-  append_branch("sip:d@example.com");
125
-
126
-  t_relay();
127
-  break;
128
-}
129
-
130
-   With this configuratin the server forwards the request to all four
131
-   branches at once, performing parallel forking described above. We did
132
-   not set the q value for individual branches in this example but we can
133
-   do that by slightly modifying the arguments given to append_branch():
134
-route {
135
-  seturi("sip:a@example.com");
136
-  append_branch("sip:b@example.com", "0.5");
137
-  append_branch("sip:c@example.com", "0.5");
138
-  append_branch("sip:d@example.com", "1.0");
139
-
140
-  t_relay();
141
-  break;
142
-}
143
-
144
-   Here we assigned q value 0.5 to branches B and C and q value 1.0 to
145
-   branch D. We did not specify any q value for branch A and in that case
146
-   it is assumed that its q value is the lowest from all branches within
147
-   the destination set. If you try to run this example again, you will
148
-   figure out that nothing changed, t_relay() still forward the message to
149
-   all branches in parallel.
150
-
151
-   We now want to implement the combined serial/parallel forking. Branch D
152
-   should be tried first, because its q value is 1.0. Branches B and C
153
-   should be tried in parallel, but only after D finishes. Branch A should
154
-   be tried after B and C finished, because its q value (the default) is
155
-   the lowest of all. To do that, we need to introduce two new functions
156
-   into our example and one tm module parameter:
157
-modparam("tm", "contacts_avp", "tm_contacts");
158
-
159
-route {
160
-  seturi("sip:a@example.com");
161
-  append_branch("sip:b@example.com", "0.5");
162
-  append_branch("sip:c@example.com", "0.5");
163
-  append_branch("sip:d@example.com", "1.0");
164
-
165
-  t_load_contacts();
166
-
167
-  t_next_contacts();
168
-  t_relay();
169
-  break;
170
-}
171
-
172
-   First of all, the tm module parameter is mandatory if the two new
173
-   functions are used. Function t_load_contacts() takes all branches from
174
-   the destination set, sorts them according to their q values and stores
175
-   them in the AVP configured in the modparam. The function also clears
176
-   the destination set, which means that it removes all branches
177
-   configured before with seturi() and append_branch().
178
-
179
-   Function t_next_contacts() takes the AVP created by the previous
180
-   function and extract the branches with highest q values from it. In our
181
-   example it is branch D. That branch is then put back into the
182
-   destination set and when the script finally reaches t_relay(), the
183
-   destination set only contains branch D and the request will be
184
-   forwarded there.
185
-
186
-   We achieved the first step of serial forking, but this is not
187
-   sufficient. Now we also need to forward to other branches with lower
188
-   priority values when branch D finishes. To do that, we need to extend
189
-   the configuration file again and introduce a failure_route section:
190
-modparam("tm", "contacts_avp", "tm_contacts");
191
-
192
-route {
193
-  seturi("sip:a@example.com");
194
-  append_branch("sip:b@example.com", "0.5");
195
-  append_branch("sip:c@example.com", "0.5");
196
-  append_branch("sip:d@example.com", "1.0");
197
-
198
-  t_load_contacts();
199
-
200
-  t_next_contacts();
201
-  t_on_failure("serial");
202
-  t_relay();
203
-  break;
204
-}
205
-
206
-failure_route["serial"]
207
-{
208
-  if (!t_next_contacts()) {
209
-    exit;
210
-  }
211
-
212
-  t_on_failure("serial");
213
-  t_relay();
214
-}
215
-
216
-   The failure_route section will be executed when branch D finishes. It
217
-   executes t_next_contacts() again and this time the function retrieves
218
-   branches B and C from the AVP and adds them to the destination set.
219
-   Here we need to check the return value of the function, because a
220
-   negative value indicates that there were no more branches, in that case
221
-   the failure_route should just terminate and forward the response from
222
-   branch D upstream.
223
-
224
-   If t_next_contact() returns a positive value then we have more new
225
-   branches to try and we need to setup the failure_route again and call
226
-   t_relay(). In our example the request will now be forwarded to branches
227
-   B and C in paralell, because they were both added to the destination
228
-   set by t_next_contacts() at the same time.
229
-
230
-   When branches B and C finish, the failure_route block is executed
231
-   again, this time t_next_contacts() puts the final branch A into the
232
-   destination set and t_relay() forwards the request there.
233
-
234
-   And that's the whole example, we achieved combined serial/parallel
235
-   forking based on the q value of individual branches. In real-world
236
-   configuration files the script writer would need to check the return
237
-   value of all functions and also configure some additional parameters,
238
-   such as fr_inv_timer_next and restart_fr_on_each_reply. Also the
239
-   destination set would not be configured directly in the configuration
240
-   file, but can be retrieved from the user location database, for
241
-   example. In that case registered contacts will be stored in the
242
-   destination set as branches and their q values (provided by UAs) will
243
-   be used.
244
-
245
-1.3. Known Issues
73
+1.2. Known Issues
246 74
 
247 75
      * Possibly, performance could be improved by not parsing non-INVITEs,
248 76
        as they do not be replied with 100, and do not result in
... ...
@@ -257,19 +185,13 @@ failure_route["serial"]
257 257
      * t_replicate should be done more cleanly--Vias, Routes, etc. should
258 258
        be removed from a message prior to replicating it (well, does not
259 259
        matter any longer so much as there is a new replication module).
260
-     * Function t_next_contacts should restore the value of timer
261
-       fr_inv_timer when there are no more branches to be processed
262
-       serially. The function can restore the timer properly if it has
263
-       been configured through an AVP or with the config framework, but
264
-       may fail to restore timer values configured for individual
265
-       transactions with t_set_fr.
266 260
 
267
-1.4. Parameters
261
+1.3. Parameters
268 262
 
269 263
    Revision History
270 264
    Revision $Revision$ $Date$
271 265
 
272
-1.4.1. fr_timer (integer)
266
+1.3.1. fr_timer (integer)
273 267
 
274 268
    Timer which hits if no final reply for a request or ACK for a negative
275 269
    INVITE reply arrives (in milliseconds).
... ...
@@ -283,7 +205,7 @@ failure_route["serial"]
283 283
 modparam("tm", "fr_timer", 10000)
284 284
 ...
285 285
 
286
-1.4.2. fr_inv_timer (integer)
286
+1.3.2. fr_inv_timer (integer)
287 287
 
288 288
    Timer which hits if no final reply for an INVITE arrives after a
289 289
    provisional message was received (in milliseconds).
... ...
@@ -300,7 +222,7 @@ modparam("tm", "fr_timer", 10000)
300 300
 modparam("tm", "fr_inv_timer", 180000)
301 301
 ...
302 302
 
303
-1.4.3. max_inv_lifetime (integer)
303
+1.3.3. max_inv_lifetime (integer)
304 304
 
305 305
    Maximum time an INVITE transaction is allowed to be active (in
306 306
    milliseconds). After this interval has passed from the transaction
... ...
@@ -336,7 +258,7 @@ modparam("tm", "fr_inv_timer", 180000)
336 336
 modparam("tm", "max_inv_lifetime", 150000)
337 337
 ...
338 338
 
339
-1.4.4. max_noninv_lifetime (integer)
339
+1.3.4. max_noninv_lifetime (integer)
340 340
 
341 341
    Maximum time a non-INVITE transaction is allowed to be active (in
342 342
    milliseconds). After this interval has passed from the transaction
... ...
@@ -366,7 +288,7 @@ modparam("tm", "max_inv_lifetime", 150000)
366 366
 modparam("tm", "max_inv_lifetime", 30000)
367 367
 ...
368 368
 
369
-1.4.5. wt_timer (integer)
369
+1.3.5. wt_timer (integer)
370 370
 
371 371
    Time for which a transaction stays in memory to absorb delayed messages
372 372
    after it completed (in milliseconds); also, when this timer hits,
... ...
@@ -381,7 +303,7 @@ modparam("tm", "max_inv_lifetime", 30000)
381 381
 modparam("tm", "wt_timer", 1000)
382 382
 ...
383 383
 
384
-1.4.6. delete_timer (integer)
384
+1.3.6. delete_timer (integer)
385 385
 
386 386
    Time after which a to-be-deleted transaction currently ref-ed by a
387 387
    process will be tried to be deleted again (in milliseconds).
... ...
@@ -396,7 +318,7 @@ modparam("tm", "wt_timer", 1000)
396 396
 modparam("tm", "delete_timer", 100)
397 397
 ...
398 398
 
399
-1.4.7. retr_timer1 (integer)
399
+1.3.7. retr_timer1 (integer)
400 400
 
401 401
    Initial retransmission period (in milliseconds).
402 402
 
... ...
@@ -407,7 +329,7 @@ modparam("tm", "delete_timer", 100)
407 407
 modparam("tm", "retr_timer1", 1000)
408 408
 ...
409 409
 
410
-1.4.8. retr_timer2 (integer)
410
+1.3.8. retr_timer2 (integer)
411 411
 
412 412
    Maximum retransmission period (in milliseconds). The retransmission
413 413
    interval starts with retr_timer1 and increases until it reaches this
... ...
@@ -420,7 +342,7 @@ modparam("tm", "retr_timer1", 1000)
420 420
 modparam("tm", "retr_timer2", 2000)
421 421
 ...
422 422
 
423
-1.4.9. noisy_ctimer (integer)
423
+1.3.9. noisy_ctimer (integer)
424 424
 
425 425
    If set, INVITE transactions that time-out (FR INV timer) will be always
426 426
    replied. If it's not set, the transaction has only one branch and no
... ...
@@ -439,7 +361,7 @@ modparam("tm", "retr_timer2", 2000)
439 439
 modparam("tm", "noisy_ctimer", 1)
440 440
 ...
441 441
 
442
-1.4.10. restart_fr_on_each_reply (integer)
442
+1.3.10. restart_fr_on_each_reply (integer)
443 443
 
444 444
    If set (default), the fr_inv_timer for an INVITE transaction will be
445 445
    restarted for each provisional reply received (rfc3261 mandated
... ...
@@ -461,7 +383,7 @@ modparam("tm", "noisy_ctimer", 1)
461 461
 modparam("tm", "restart_fr_on_each_reply", 0)
462 462
 ...
463 463
 
464
-1.4.11. auto_inv_100 (integer)
464
+1.3.11. auto_inv_100 (integer)
465 465
 
466 466
    If set (default) tm will automatically send and 100 reply to INVITEs.
467 467
 
... ...
@@ -481,7 +403,7 @@ modparam("tm", "restart_fr_on_each_reply", 0)
481 481
 modparam("tm", "auto_inv_100", 0)
482 482
 ...
483 483
 
484
-1.4.12. auto_inv_100_reason (string)
484
+1.3.12. auto_inv_100_reason (string)
485 485
 
486 486
    Set reason text of the automatically send 100 to an INVITE.
487 487
 
... ...
@@ -494,7 +416,7 @@ modparam("tm", "auto_inv_100", 0)
494 494
 modparam("tm", "auto_inv_100_reason", "Trying")
495 495
 ...
496 496
 
497
-1.4.13. unix_tx_timeout (integer)
497
+1.3.13. unix_tx_timeout (integer)
498 498
 
499 499
    Unix socket transmission timeout, in milliseconds.
500 500
 
... ...
@@ -509,7 +431,7 @@ modparam("tm", "auto_inv_100_reason", "Trying")
509 509
 modparam("tm", "unix_tx_timeout", 250)
510 510
 ...
511 511
 
512
-1.4.14. aggregate_challenges (integer)
512
+1.3.14. aggregate_challenges (integer)
513 513
 
514 514
    If set (default), the final reply is a 401 or a 407 and more then one
515 515
    branch received a 401 or 407, then all the WWW-Authenticate and
... ...
@@ -526,7 +448,7 @@ modparam("tm", "unix_tx_timeout", 250)
526 526
 modparam("tm", "aggregate_challenges", 0)
527 527
 ...
528 528
 
529
-1.4.15. reparse_invite (integer)
529
+1.3.15. reparse_invite (integer)
530 530
 
531 531
    If set (default), the CANCEL and negative ACK requests are constructed
532 532
    from the INVITE message which was sent out instead of building them
... ...
@@ -552,7 +474,7 @@ modparam("tm", "aggregate_challenges", 0)
552 552
 modparam("tm", "reparse_invite", 0)
553 553
 ...
554 554
 
555
-1.4.16. ac_extra_hdrs (string)
555
+1.3.16. ac_extra_hdrs (string)
556 556
 
557 557
    Header fields prefixed by this parameter value are included in the
558 558
    CANCEL and negative ACK messages if they were present in the outgoing
... ...
@@ -570,7 +492,7 @@ modparam("tm", "reparse_invite", 0)
570 570
 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
571 571
 ...
572 572
 
573
-1.4.17. blst_503 (integer)
573
+1.3.17. blst_503 (integer)
574 574
 
575 575
    If set and the blacklist support is enabled, every 503 reply source is
576 576
    added to the blacklist. The initial blacklist timeout (or ttl) depends
... ...
@@ -588,7 +510,7 @@ modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
588 588
 modparam("tm", "blst_503", 1)
589 589
 ...
590 590
 
591
-1.4.18. blst_503_def_timeout (integer)
591
+1.3.18. blst_503_def_timeout (integer)
592 592
 
593 593
    Blacklist interval in seconds for a 503 reply with no Retry-After
594 594
    header. See also blst_503, blst_503_min_timeout and
... ...
@@ -603,7 +525,7 @@ modparam("tm", "blst_503", 1)
603 603
 modparam("tm", "blst_503_def_timeout", 120)
604 604
 ...
605 605
 
606
-1.4.19. blst_503_min_timeout (integer)
606
+1.3.19. blst_503_min_timeout (integer)
607 607
 
608 608
    Minimum blacklist interval in seconds for a 503 reply with a
609 609
    Retry-After header. It will be used if the Retry-After value is
... ...
@@ -617,7 +539,7 @@ modparam("tm", "blst_503_def_timeout", 120)
617 617
 modparam("tm", "blst_503_min_timeout", 30)
618 618
 ...
619 619
 
620
-1.4.20. blst_503_max_timeout (integer)
620
+1.3.20. blst_503_max_timeout (integer)
621 621
 
622 622
    Maximum blacklist interval in seconds for a 503 reply with a
623 623
    Retry-After header. It will be used if the Retry-After value is
... ...
@@ -631,7 +553,7 @@ modparam("tm", "blst_503_min_timeout", 30)
631 631
 modparam("tm", "blst_503_max_timeout", 604800)
632 632
 ...
633 633
 
634
-1.4.21. blst_methods_add (unsigned integer)
634
+1.3.21. blst_methods_add (unsigned integer)
635 635
 
636 636
    Bitmap of method types that trigger blacklisting on transaction
637 637
    timeouts. (This setting has no effect on blacklisting because of send
... ...
@@ -656,7 +578,7 @@ modparam("tm", "blst_503_max_timeout", 604800)
656 656
 modparam("tm", "blst_methods_add", 33)
657 657
 ...
658 658
 
659
-1.4.22. blst_methods_lookup (unsigned integer)
659
+1.3.22. blst_methods_lookup (unsigned integer)
660 660
 
661 661
    Bitmap of method types that are looked-up in the blacklist before
662 662
    statefull forwarding. See also blst_methods_add
... ...
@@ -670,7 +592,7 @@ modparam("tm", "blst_methods_add", 33)
670 670
 modparam("tm", "blst_methods_lookup", 1)
671 671
 ...
672 672
 
673
-1.4.23. cancel_b_method (integer)
673
+1.3.23. cancel_b_method (integer)
674 674
 
675 675
    Method used when attempting to CANCEL an unreplied transaction branch
676 676
    (a branch where no reply greater the 99 was received). The possible
... ...
@@ -708,7 +630,7 @@ modparam("tm", "blst_methods_lookup", 1)
708 708
 modparam("tm", "cancel_b_method", 1)
709 709
 ...
710 710
 
711
-1.4.24. reparse_on_dns_failover (integer)
711
+1.3.24. reparse_on_dns_failover (integer)
712 712
 
713 713
    If set to 1, the SIP message after a DNS failover is constructed from
714 714
    the outgoing message buffer of the failed branch instead of from the
... ...
@@ -736,7 +658,7 @@ modparam("tm", "cancel_b_method", 1)
736 736
 modparam("tm", "reparse_on_dns_failover", 0)
737 737
 ...
738 738
 
739
-1.4.25. on_sl_reply (string)
739
+1.3.25. on_sl_reply (string)
740 740
 
741 741
    Sets reply route block, to which control is passed when a reply is
742 742
    received that has no associated transaction. The reply is passed to the
... ...
@@ -753,56 +675,27 @@ onreply_route["stateless_replies"] {
753 753
         return 0;
754 754
 }
755 755
 
756
-1.4.26. fr_inv_timer_next (integer)
757
-
758
-   This parameter can be used to configure an alternative value for the
759
-   fr_inv_timer timer. This alternative value is used in place of
760
-   fr_inv_timer when serial forking takes place. It is used for all
761
-   branches during serial forking except the last one. The last branch (or
762
-   a set of parallel branches) use the original value from fr_inv_timer
763
-   again.
764
-
765
-   The purpose of the timer is to allow an administrator to configure a
766
-   shorter version of fr_inv_timer that is used only when serial forking
767
-   takes place. Forwarding branches one after another is much more time
768
-   consuming, because every serial branch has to wait for the result of
769
-   the previous one. That can take up to the value of fr_inv_timer and
770
-   this timer is configured to two minutes by default. Hence, if you have
771
-   three serial branches then completing the transaction can take six
772
-   minutes with default timer values.
773
-
774
-   In practise, the transaction will be terminated sooner, because the
775
-   timer max_inv_lifetime hits after three minutes. Thus, some of the
776
-   serial branches might not be forwarded at all. And this is exactly what
777
-   fr_inv_timer_next is for. You can configure the timer to a shorter
778
-   value to ensure that all serial branches are tried before the timer
779
-   max_inv_lifetime hits.
780
-
781
-   Note that if there is only one branch or if the current serial branch
782
-   is the last one (i.e. no more serial forking takes place after this
783
-   branch is finished) then fr_inv_timer_next is not used, instead the
784
-   branch uses the longer fr_inv_timer.
785
-
786
-   Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next if
787
-   serial forking takes place and there is more than one serial branch.
788
-
789
-   The administrator can configure the value of this timer using the
790
-   configuration framework on the fly. But unlike fr_inv_timer, it is not
791
-   possible to configure the value of this timer on per-transaction basis.
792
-
793
-   The value of this timer is to be specified in milliseconds. The default
794
-   value is 30000ms.
756
+1.3.26. fr_inv_timer_next (integer)
757
+
758
+   Value of the Final Response timeout for INVITE transactions to be used
759
+   during serial forwarding:
760
+
761
+   Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next value
762
+   if, after t_next_contacts() is called, there are still lower qvalue
763
+   contacts available, and to fr_inv_timer value if there are not.
764
+
765
+   Default value is 30.
795 766
 
796 767
    Example 26. Set fr_inv_timer_next parameter
797 768
 ...
798
-modparam("tm", "fr_inv_timer_next", 10000)
769
+modparam("tm", "fr_inv_timer_next", 10)
799 770
 ...
800 771
 
801
-1.4.27. contacts_avp (string)
772
+1.3.27. contacts_avp (string)
802 773
 
803
-   This is the name or Id of an AVP that t_load_contacts() function uses
804
-   to store contacts of the destination set and that t_next_contacts()
805
-   function uses to restore those contacts.
774
+   Internal AVP that t_load_contacts() function uses to store contacts of
775
+   the destination set and that t_next_contacts() function uses to restore
776
+   those contacts.
806 777
 
807 778
    Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
808 779
    are disabled).
... ...
@@ -812,7 +705,7 @@ modparam("tm", "fr_inv_timer_next", 10000)
812 812
 modparam("tm", "contacts_avp", "$avp(i:25)")
813 813
 ...
814 814
 
815
-1.4.28. fr_timer_avp (string)
815
+1.3.28. fr_timer_avp (string)
816 816
 
817 817
    The value of fr_timer timer can be overriden on per-transaction basis.
818 818
    The administrator can provide a value to be used for a particular
... ...
@@ -841,7 +734,7 @@ Note
841 841
 modparam("tm", "fr_timer_avp", "i:708")
842 842
 ...
843 843
 
844
-1.4.29. fr_inv_timer_avp (string)
844
+1.3.29. fr_inv_timer_avp (string)
845 845
 
846 846
    The value of fr_inv_timer timer can be overriden on per-transaction
847 847
    basis. The administrator can provide a value to be used for a
... ...
@@ -871,7 +764,7 @@ Note
871 871
 modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
872 872
 ...
873 873
 
874
-1.4.30. unmatched_cancel (string)
874
+1.3.30. unmatched_cancel (string)
875 875
 
876 876
    This parameter selects between forwarding CANCELs that do not match any
877 877
    transaction statefully (0, default value), statelessly (1) or dropping
... ...
@@ -890,7 +783,7 @@ modparam("tm", "fr_inv_timer_avp", "my_fr_inv_timer")
890 890
 modparam("tm", "unmatched_cancel", "2")
891 891
 ...
892 892
 
893
-1.4.31. ruri_matching (integer)
893
+1.3.31. ruri_matching (integer)
894 894
 
895 895
    If set it will also try to match the request uri when doing pre-3261
896 896
    transaction matching (the via branch parameter does not contain the
... ...
@@ -909,7 +802,7 @@ modparam("tm", "unmatched_cancel", "2")
909 909
 modparam("tm", "ruri_matching", 1)
910 910
 ...
911 911
 
912
-1.4.32. via1_matching (integer)
912
+1.3.32. via1_matching (integer)
913 913
 
914 914
    If set it will also try to match the topmost via when doing pre-3261
915 915
    transaction matching (the via branch parameter does not contain the
... ...
@@ -928,7 +821,7 @@ modparam("tm", "ruri_matching", 1)
928 928
 modparam("tm", "via1_matching", 1)
929 929
 ...
930 930
 
931
-1.4.33. pass_provisional_replies (integer)
931
+1.3.33. pass_provisional_replies (integer)
932 932
 
933 933
    If set, TMCB_LOCAL_REPONSE_OUT tm registered callbacks will be called
934 934
    also for provisional replies.
... ...
@@ -943,7 +836,7 @@ modparam("tm", "via1_matching", 1)
943 943
 modparam("tm", "pass_provisional_replies", 1)
944 944
 ...
945 945
 
946
-1.4.34. default_code (integer)
946
+1.3.34. default_code (integer)
947 947
 
948 948
    Default response code sent by t_reply() if it cannot retrieve its
949 949
    parameters (e.g. inexistent avp). Valid values are between 400 and 699.
... ...
@@ -958,7 +851,7 @@ modparam("tm", "pass_provisional_replies", 1)
958 958
 modparam("tm", "default_code", 501)
959 959
 ...
960 960
 
961
-1.4.35. default_reason (string)
961
+1.3.35. default_reason (string)
962 962
 
963 963
    Default SIP reason phrase sent by t_reply() if it cannot retrieve its
964 964
    parameters (e.g. inexistent avp).
... ...
@@ -973,7 +866,7 @@ modparam("tm", "default_code", 501)
973 973
 modparam("tm", "default_reason", "Unknown reason")
974 974
 ...
975 975
 
976
-1.4.36. disable_6xx_block (integer)
976
+1.3.36. disable_6xx_block (integer)
977 977
 
978 978
    If set tm will treat all the 6xx replies like normal replies (warning:
979 979
    this would be non-rfc conformant behaviour).
... ...
@@ -997,12 +890,12 @@ modparam("tm", "default_reason", "Unknown reason")
997 997
 modparam("tm", "disable_6xx_block", 1)
998 998
 ...
999 999
 
1000
-1.5. Functions
1000
+1.4. Functions
1001 1001
 
1002 1002
    Revision History
1003 1003
    Revision $Revision$ $Date$
1004 1004
 
1005
-1.5.1.  t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
1005
+1.4.1.  t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
1006 1006
 t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
1007 1007
 t_relay_to_sctp(ip, port) t_relay_to_sctp()
1008 1008
 
... ...
@@ -1030,7 +923,7 @@ else
1030 1030
         t_relay_to_tcp(); # relay to msg. uri, but over tcp
1031 1031
 ...
1032 1032
 
1033
-1.5.2.  t_relay() t_relay(host, port)
1033
+1.4.2.  t_relay() t_relay(host, port)
1034 1034
 
1035 1035
    Relay a message statefully either to the destination indicated in the
1036 1036
    current URI (if called without any parameters) or to the specified host
... ...
@@ -1058,7 +951,7 @@ if (!t_relay())
1058 1058
 };
1059 1059
 ...
1060 1060
 
1061
-1.5.3.  t_on_failure(failure_route)
1061
+1.4.3.  t_on_failure(failure_route)
1062 1062
 
1063 1063
    Sets failure routing block, to which control is passed after a
1064 1064
    transaction completed with a negative result but before sending a final
... ...
@@ -1095,7 +988,7 @@ failure_route[1] {
1095 1095
    See test/onr.cfg for a more complex example of combination of serial
1096 1096
    with parallel forking.
1097 1097
 
1098
-1.5.4.  t_on_reply(onreply_route)
1098
+1.4.4.  t_on_reply(onreply_route)
1099 1099
 
1100 1100
    Sets the reply routing block, to which control is passed when a reply
1101 1101
    for the current transaction is received. Note that the set of commands
... ...
@@ -1125,7 +1018,7 @@ es');
1125 1125
         }
1126 1126
 }
1127 1127
 
1128
-1.5.5.  t_on_branch(branch_route)
1128
+1.4.5.  t_on_branch(branch_route)
1129 1129
 
1130 1130
    Sets the branch routing block, to which control is passed after forking
1131 1131
    (when a new branch is created). For now branch routes are intended only
... ...
@@ -1149,7 +1042,7 @@ branch_route[1] {
1149 1149
         }
1150 1150
 }
1151 1151
 
1152
-1.5.6.  append_branch()
1152
+1.4.6.  append_branch()
1153 1153
 
1154 1154
    Similarly to t_fork_to, it extends destination set by a new entry. The
1155 1155
    difference is that current URI is taken as new entry.
... ...
@@ -1163,7 +1056,7 @@ t_fork();
1163 1163
 t_relay();
1164 1164
 ...
1165 1165
 
1166
-1.5.7.  t_newtran()
1166
+1.4.7.  t_newtran()
1167 1167
 
1168 1168
    Creates a new transaction, returns a negative value on error. This is
1169 1169
    the only way a script can add a new transaction in an atomic way.
... ...
@@ -1179,7 +1072,7 @@ if (t_newtran()) {
1179 1179
 
1180 1180
    See test/uas.cfg for more examples.
1181 1181
 
1182
-1.5.8.  t_reply(code, reason_phrase)
1182
+1.4.8.  t_reply(code, reason_phrase)
1183 1183
 
1184 1184
    Sends a stateful reply after a transaction has been established. See
1185 1185
    t_newtran for usage.
... ...
@@ -1193,7 +1086,7 @@ if (t_newtran()) {
1193 1193
 t_reply("404", "Not found");
1194 1194
 ...
1195 1195
 
1196
-1.5.9.  t_lookup_request()
1196
+1.4.9.  t_lookup_request()
1197 1197
 
1198 1198
    Checks if a transaction exists. Returns a positive value if so,
1199 1199
    negative otherwise. Most likely you will not want to use it, as a
... ...
@@ -1208,7 +1101,7 @@ if (t_lookup_request()) {
1208 1208
 };
1209 1209
 ...
1210 1210
 
1211
-1.5.10.  t_retransmit_reply()
1211
+1.4.10.  t_retransmit_reply()
1212 1212
 
1213 1213
    Retransmits a reply sent previously by UAS transaction.
1214 1214
 
... ...
@@ -1217,7 +1110,7 @@ if (t_lookup_request()) {
1217 1217
 t_retransmit_reply();
1218 1218
 ...
1219 1219
 
1220
-1.5.11.  t_release()
1220
+1.4.11.  t_release()
1221 1221
 
1222 1222
    Remove transaction from memory (it will be first put on a wait timer to
1223 1223
    absorb delayed messages).
... ...
@@ -1227,7 +1120,7 @@ t_retransmit_reply();
1227 1227
 t_release();
1228 1228
 ...
1229 1229
 
1230
-1.5.12.  t_forward_nonack() t_forward_nonack(ip, port)
1230
+1.4.12.  t_forward_nonack() t_forward_nonack(ip, port)
1231 1231
 t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
1232 1232
 t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
1233 1233
 
... ...
@@ -1242,7 +1135,7 @@ t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
1242 1242
 t_forward_nonack("1.2.3.4", "5060");
1243 1243
 ...
1244 1244
 
1245
-1.5.13.  t_set_fr(fr_inv_timeout [, fr_timeout])
1245
+1.4.13.  t_set_fr(fr_inv_timeout [, fr_timeout])
1246 1246
 
1247 1247
    Sets the fr_inv_timeout and optionally fr_timeout for the current
1248 1248
    transaction or for transactions created during the same script
... ...
@@ -1276,7 +1169,7 @@ branch_route[1] {
1276 1276
         }
1277 1277
 }
1278 1278
 
1279
-1.5.14.  t_reset_fr()
1279
+1.4.14.  t_reset_fr()
1280 1280
 
1281 1281
    Resets the fr_inv_timer and fr_timer for the current transaction to the
1282 1282
    default values (set using the tm module parameters fr_inv_timer and
... ...
@@ -1295,7 +1188,7 @@ route {
1295 1295
 ...
1296 1296
 }
1297 1297
 
1298
-1.5.15.  t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1298
+1.4.15.  t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1299 1299
 
1300 1300
    Sets the maximum lifetime for the current INVITE or non-INVITE
1301 1301
    transaction, or for transactions created during the same script
... ...
@@ -1324,7 +1217,7 @@ route {
1324 1324
                                           # INVITE and to 15s if not
1325 1325
 }
1326 1326
 
1327
-1.5.16.  t_reset_max_lifetime()
1327
+1.4.16.  t_reset_max_lifetime()
1328 1328
 
1329 1329
    Resets the the maximum lifetime for the current INVITE or non-INVITE
1330 1330
    transaction to the default value (set using the tm module parameter
... ...
@@ -1343,7 +1236,7 @@ route {
1343 1343
 ...
1344 1344
 }
1345 1345
 
1346
-1.5.17.  t_set_retr(retr_t1_interval, retr_t2_interval)
1346
+1.4.17.  t_set_retr(retr_t1_interval, retr_t2_interval)
1347 1347
 
1348 1348
    Sets the retr_t1_interval and retr_t2_interval for the current
1349 1349
    transaction or for transactions created during the same script
... ...
@@ -1389,7 +1282,7 @@ branch_route[1] {
1389 1389
         }
1390 1390
 }
1391 1391
 
1392
-1.5.18.  t_reset_retr()
1392
+1.4.18.  t_reset_retr()
1393 1393
 
1394 1394
    Resets the retr_timer1 and retr_timer2 for the current transaction to
1395 1395
    the default values (set using the tm module parameters retr_timer1 and
... ...
@@ -1408,7 +1301,7 @@ route {
1408 1408
 ...
1409 1409
 }
1410 1410
 
1411
-1.5.19.  t_set_auto_inv_100(0|1)
1411
+1.4.19.  t_set_auto_inv_100(0|1)
1412 1412
 
1413 1413
    Switch automatically sending 100 replies to INVITEs on/off on a per
1414 1414
    transaction basis. It overrides the auto_inv_100 value for the current
... ...
@@ -1425,7 +1318,7 @@ route {
1425 1425
 ...
1426 1426
 }
1427 1427
 
1428
-1.5.20.  t_branch_timeout()
1428
+1.4.20.  t_branch_timeout()
1429 1429
 
1430 1430
    Returns true if the failure route is executed for a branch that did
1431 1431
    timeout. It can be used only from the failure_route.
... ...
@@ -1439,7 +1332,7 @@ failure_route[0]{
1439 1439
         }
1440 1440
 }
1441 1441
 
1442
-1.5.21.  t_branch_replied()
1442
+1.4.21.  t_branch_replied()
1443 1443
 
1444 1444
    Returns true if the failure route is executed for a branch that did
1445 1445
    receive at least one reply in the past (the "current" reply is not
... ...
@@ -1457,7 +1350,7 @@ failure_route[0]{
1457 1457
         }
1458 1458
 }
1459 1459
 
1460
-1.5.22.  t_any_timeout()
1460
+1.4.22.  t_any_timeout()
1461 1461
 
1462 1462
    Returns true if at least one of the current transactions branches did
1463 1463
    timeout.
... ...
@@ -1473,7 +1366,7 @@ failure_route[0]{
1473 1473
         }
1474 1474
 }
1475 1475
 
1476
-1.5.23.  t_any_replied()
1476
+1.4.23.  t_any_replied()
1477 1477
 
1478 1478
    Returns true if at least one of the current transactions branches did
1479 1479
    receive some reply in the past. If called from a failure or onreply
... ...
@@ -1488,7 +1381,7 @@ onreply_route[0]{
1488 1488
         }
1489 1489
 }
1490 1490
 
1491
-1.5.24.  t_grep_status("code")
1491
+1.4.24.  t_grep_status("code")
1492 1492
 
1493 1493
    Returns true if "code" is the final reply received (or locally
1494 1494
    generated) in at least one of the current transactions branches.
... ...
@@ -1502,7 +1395,7 @@ onreply_route[0]{
1502 1502
         }
1503 1503
 }
1504 1504
 
1505
-1.5.25.  t_is_canceled()
1505
+1.4.25.  t_is_canceled()
1506 1506
 
1507 1507
    Returns true if the current transaction was canceled.
1508 1508
 
... ...
@@ -1515,7 +1408,7 @@ failure_route[0]{
1515 1515
         }
1516 1516
 }
1517 1517
 
1518
-1.5.26.  t_is_expired()
1518
+1.4.26.  t_is_expired()
1519 1519
 
1520 1520
    Returns true if the current transaction has already been expired, i.e.
1521 1521
    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
... ...
@@ -1529,7 +1422,7 @@ failure_route[0]{
1529 1529
         }
1530 1530
 }
1531 1531
 
1532
-1.5.27.  t_relay_cancel()
1532
+1.4.27.  t_relay_cancel()
1533 1533
 
1534 1534
    Forwards the CANCEL if the corresponding INVITE transaction exists. The
1535 1535
    function is supposed to be used at the very beginning of the script,
... ...
@@ -1554,7 +1447,7 @@ if (method == CANCEL) {
1554 1554
         # do the same as for INVITEs
1555 1555
 }
1556 1556
 
1557
-1.5.28.  t_lookup_cancel(), t_lookup_cancel(1)
1557
+1.4.28.  t_lookup_cancel(), t_lookup_cancel(1)
1558 1558
 
1559 1559
    Returns true if the corresponding INVITE transaction exists for a
1560 1560
    CANCEL request. The function can be called at the beginning of the
... ...
@@ -1586,7 +1479,7 @@ if (method == CANCEL) {
1586 1586
         # do the same as for INVITEs
1587 1587
 }
1588 1588
 
1589
-1.5.29.  t_drop_replies()
1589
+1.4.29.  t_drop_replies()
1590 1590
 
1591 1591
    Drops all the previously received replies in failure_route block to
1592 1592
    make sure that none of them is picked up again. Works only if a new
... ...
@@ -1609,7 +1502,7 @@ failure_route[0]{
1609 1609
         }
1610 1610
 }
1611 1611
 
1612
-1.5.30.  t_save_lumps()
1612
+1.4.30.  t_save_lumps()
1613 1613
 
1614 1614
    Forces the modifications of the processed SIP message to be saved in
1615 1615
    shared memory before t_relay() is called. The new branches which are
... ...
@@ -1649,48 +1542,14 @@ failure_route[1] {
1649 1649
         t_relay();
1650 1650
 }
1651 1651
 
1652
-1.5.31.  t_load_contacts()
1653
-
1654
-   This is the first of the two functions that can be used to implement
1655
-   serial/parallel forking based on the q value of individual branches in
1656
-   a destination set.
1657
-
1658
-   The function t_load_contacts() takes all branches from the current
1659
-   destination set and encodes them into the AVP whose name or ID is
1660
-   configured with the parameter contacts_avp. Note that you have to
1661
-   configure this parameter before you can use the function, the parameter
1662
-   is set to NULL by default, which disables the function.
1663
-
1664
-   If the destination set contains only one branch (the Request-URI) or if
1665
-   all branches have the same q value then the function does nothing to
1666
-   minimize performance impact. In such case all branches should be tried
1667
-   in parallel and that is the default mode of operation of functions like
1668
-   t_relay(), so there is no need to create the AVP or sort the branches.
1669
-
1670
-   If the current destination set contains more than one branch and not
1671
-   all branches have the same q value then the function sorts them
1672
-   according to the increasing value of the q parameter. The resulting
1673
-   sorted list of branches is then encoded into the AVP.
1674
-
1675
-   The q parameter contains a value from a range of 0 to 1.0 and it
1676
-   expresses relative preferrence of the branch among all branches in the
1677
-   destination set. The higher the q value the more preferrence the user
1678
-   agent gave to the branch. Branches with higher q values will be tried
1679
-   first when serial forking takes place.
1680
-
1681
-   After that the function clears all branches and you have to call
1682
-   t_next_contacts to retrieve them sorted according to their q value.
1683
-   Note that if you use t_load_contacts then you also have to use
1684
-   t_next_contacts before calling t_relay.
1685
-
1686
-   The AVP created by the function may contain multiple values, with one
1687
-   encoded branch per value. The first value will contain the branch with
1688
-   the highest q value. Each value contains the Request-URI, the
1689
-   destination URI, the path vector, the outgoing socket description and
1690
-   branch flags. All these fields are delimited with the LF character.
1691
-
1692
-   The function returns 1 if loading of contacts succeeded or there was
1693
-   nothing to do. Returns -1 on error (see syslog).
1652
+1.4.31.  t_load_contacts()
1653
+
1654
+   Loads contacts in destination set in increasing qvalue order as values
1655
+   of contacts_avp. If all contacts in the destination set have the same
1656
+   qvalue, t_load_contacts() does not do anything thus minimizing
1657
+   performance impact of serial forking capability when it is not needed.
1658
+   Returns 1 if loading of contacts succeeded or there was nothing to do.
1659
+   Returns -1 on error (see syslog).
1694 1660
 
1695 1661
    This function can be used from REQUEST_ROUTE.
1696 1662
 
... ...
@@ -1702,49 +1561,22 @@ if (!t_load_contacts()) {
1702 1702
 };
1703 1703
 ...
1704 1704
 
1705
-1.5.32.  t_next_contacts()
1706
-
1707
-   The function t_next_contacts is the second of the two functions that
1708
-   can be used to implement serial/parallel forking based on the q value
1709
-   of individual branches in a destination set.
1710
-
1711
-   This function takes the AVP created by t_load_contacts and extracts
1712
-   branches with highest q value from it into the destination set when
1713
-   called for the first time. When you call the function second time it
1714
-   extracts branches with lower q value, and so on until all branches have
1715
-   been extracted.
1705
+1.4.32.  t_next_contacts()
1716 1706
 
1717
-   If no transaction exist when t_next_contacts() is called, this usually
1718
-   happens when you call the function from a request route block before
1719
-   you call t_relay, it replaces the Request-URI with the first
1720
-   contacts_avp value, adds the remaining contacts_avp values with the
1721
-   same q value as branches, and destroys those AVPs.
1707
+   If transaction does not exist when t_next_contacts() is called,
1708
+   replaces Request-URI with the first contacts_avp value, adds the
1709
+   remaining contacts_avp values with the same qvalue as branches, and
1710
+   destroys those AVPs. It does nothing if there are no contacts_avp
1711
+   values. Returns 1 if there were no errors and -1 if an error occurred
1712
+   (see syslog).
1722 1713
 
1723
-   If transaction does exist when t_next_contacts() is called, it adds the
1714
+   If transaction does exist when t_next_contacts() is called, adds the
1724 1715
    first contacts_avp value and all following contacts_avp values with the
1725
-   same q value as new branches to request and destroys those AVPs.
1726
-
1727
-   When you call the function repeatedly from a failure_route branch, it
1728
-   looks for more AVP values each time and adds branches that have same q
1729
-   value from the AVP as additional destination set branches. It always
1730
-   stops when it reaches a branch that has a lower q value. Used AVP
1731
-   values are always destroyed.,
1732
-
1733
-   The function does nothing if there are no contact_avp values.
1716
+   same qvalue as new branches to request and destroys those AVPs. Returns
1717
+   1 if new branches were successfully added and -1 on error (see syslog)
1718
+   or if there were no more contacts_avp values.
1734 1719
 
1735
-   The function returns 1 if there were no errors and -1 if an error
1736
-   occurred (see syslog). This function can be used from REQUEST_ROUTE and
1737
-   FAILURE_ROUTE.
1738
-
1739
-   Note that if use use t_load_contacts and t_next_contacts functions then
1740
-   you should also set the value of restart_fr_on_each_reply parameter to
1741
-   0. If you do not do that then it can happen that a broken user agent
1742
-   that retransmits 180 periodically will keep resetting the fr_inv_timer
1743
-   value and serial forking never happens.
1744
-
1745
-   Also make sure that you configured fr_inv_timer_next with lower value,
1746
-   especially if you expect to have many serially forked branches. See the
1747
-   documentation of that parameter for more details.
1720
+   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
1748 1721
 
1749 1722
    Example 68. t_next_contacts usage
1750 1723
 ...
... ...
@@ -1765,7 +1597,7 @@ if (!t_next_contacts()) {
1765 1765
 };
1766 1766
 ...
1767 1767
 
1768
-1.5.33.  t_check_trans()
1768
+1.4.33.  t_check_trans()
1769 1769
 
1770 1770
    t_check_trans() can be used to quickly check if a message belongs or is
1771 1771
    related to a transaction. It behaves differently for different types of
... ...
@@ -1815,7 +1647,7 @@ if ( method == "CANCEL" && !t_check_trans())
1815 1815
         sl_reply("403", "cancel out of the blue forbidden");
1816 1816
 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
1817 1817
 
1818
-1.5.34.  t_set_disable_6xx(0|1)
1818
+1.4.34.  t_set_disable_6xx(0|1)
1819 1819
 
1820 1820
    Turn off/on 6xx replies special rfc conformant handling on a per
1821 1821
    transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
... ...
@@ -1834,7 +1666,7 @@ route {
1834 1834
 ...
1835 1835
 }
1836 1836
 
1837
-1.5.35.  t_set_disable_failover(0|1)
1837
+1.4.35.  t_set_disable_failover(0|1)
1838 1838
 
1839 1839
    Turn off/on dns failover on a per transaction basis.
1840 1840
 
... ...
@@ -1849,7 +1681,7 @@ route {
1849 1849
 ...
1850 1850
 }
1851 1851
 
1852
-1.6. TM Module API
1852
+1.5. TM Module API
1853 1853
 
1854 1854
    Revision History
1855 1855
    Revision $Revision$ $Date$
... ...
@@ -1857,14 +1689,15 @@ route {
1857 1857
    There are applications which would like to generate SIP transactions
1858 1858
    without too big involvement in SIP stack, transaction management, etc.
1859 1859
    An example of such an application is sending instant messages from a
1860
-   website. To address needs of such apps, SIP-router accepts requests for
1861
-   new transactions via the management interface. If you want to enable
1862
-   this feature, start the management interface server by configuring the
1863
-   proper modules.
1864
-
1865
-   An application can easily launch a new transaction by writing a
1866
-   transaction request to this interface. The request must follow very
1867
-   simple format, which for the basic FIFO interface is
1860
+   website. To address needs of such apps, SER accepts requests for new
1861
+   transactions via fifo pipes too. If you want to enable this feature,
1862
+   start FIFO server with configuration option.
1863
+
1864
+   fifo="/tmp/ser_fifo"
1865
+
1866
+   Then, an application can easily launch a new transaction by writing a
1867
+   transaction request to this named pipe. The request must follow very
1868
+   simple format, which is
1868 1869
  :t_uac_from:[<file_name>]\n
1869 1870
  <method>\n
1870 1871
  <sender's uri>\n
... ...
@@ -1897,7 +1730,7 @@ end of body
1897 1897
 
1898 1898
    or cat test/transaction.fifo > /tmp/ser_fifo
1899 1899
 
1900
-1.6.1. Defines
1900
+1.5.1. Defines
1901 1901
 
1902 1902
      * ACK_TAG enables stricter matching of acknowledgments including
1903 1903
        to-tags. Without it, to-tags are ignored. It is disabled by default
... ...
@@ -1916,9 +1749,9 @@ end of body
1916 1916
        ACK_TAG, all this complex transactions matching goes with RFC3261's
1917 1917
        magic cookie away anyway.
1918 1918
 
1919
-1.6.2. Functions
1919
+1.5.2. Functions
1920 1920
 
1921
-1.6.2.1.  register_tmcb(cb_type, cb_func)
1921
+1.5.2.1.  register_tmcb(cb_type, cb_func)
1922 1922
 
1923 1923
    For programmatic use only--register a function to be called back on an
1924 1924
    event. See t_hooks.h for more details.
... ...
@@ -1927,7 +1760,7 @@ end of body
1927 1927
      * cb_type - Callback type.
1928 1928
      * cb_func - Callback function.
1929 1929
 
1930
-1.6.2.2.  load_tm(*import_structure)
1930
+1.5.2.2.  load_tm(*import_structure)
1931 1931
 
1932 1932
    For programmatic use only--import exported TM functions. See the acc
1933 1933
    module for an example of use.
... ...
@@ -1935,7 +1768,7 @@ end of body
1935 1935
    Meaning of the parameters is as follows:
1936 1936
      * import_structure - Pointer to the import structure.
1937 1937
 
1938
-1.6.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
1938
+1.5.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
1939 1939
 unsigned int *label)
1940 1940
 
1941 1941
    For programmatic use only. This function together with t_continue() can
... ...
@@ -1973,7 +1806,7 @@ unsigned int *label)
1973 1973
    t_suspend() should return 0 to make sure that the script processing
1974 1974
    does not continue.
1975 1975
 
1976
-1.6.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
1976
+1.5.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
1977 1977
 action *route)
1978 1978
 
1979 1979
    For programmatic use only. This function is the pair of t_suspend(),
... ...
@@ -78,7 +78,12 @@
78 78
  *              t saved, thus, are not available. Set reparse_on_dns_failover
79 79
  *              to 0 to revert the change. (Miklos)
80 80
  * 2008-06-04  T_CANCELED is now set each time a CANCEL is received (andrei)
81
- * 2009-06-01  Pre- and post-script callbacks of branch route are executed (Miklos)
81
+ * 2009-06-01  Pre- and post-script callbacks of branch route are 
82
+ *             executed (Miklos)
83
+ * 2009-10-26  support for changing dst_uri in branch routes,
84
+ *             s/print_uac_request/prepare_new_uac/ (andrei)
85
+ * 2009-10-28  support for changing r-uris and path in branch routes; more of
86
+ *             add_uac() functionality moved into prepare_new_uac()  (andrei)
82 87
  */
83 88
 
84 89
 #include "defs.h"
... ...
@@ -144,8 +149,20 @@ unsigned int get_on_branch(void)
144 144
 }
145 145
 
146 146
 
147
-/** create a branch "buffer".
148
- * Creates the buffer used in the branch rb and runs the on_branch route.
147
+
148
+/* prepare_new_uac flags */
149
+#define UAC_DNS_FAILOVER_F 1 /**< new branch due to dns failover */
150
+
151
+
152
+/** prepares a new branch "buffer".
153
+ * Creates the buffer used in the branch rb, fills everything needed (
154
+   the sending information: t->uac[branch].request.dst, branch buffer, uri
155
+   path vector a.s.o.) and runs the on_branch route.
156
+ * t->uac[branch].request.dst will be filled if next_hop !=0 with the result
157
+ * of the DNS resolution (next_hop and fproto).
158
+ * If next_hop is 0 all the dst members except the send_flags are read-only
159
+ * (send_flags it's updated) and are supposed to be pre-filled.
160
+ *
149 161
  * @param t  - transaction
150 162
  * @param i_req - corresponding sip_msg, must be non-null, flags might be
151 163
  *                be modified (on_branch route)
... ...
@@ -153,64 +170,61 @@ unsigned int get_on_branch(void)
153 153
  * @param uri
154 154
  * @param path  - path vector (list of route like destination in text form,
155 155
  *                 e.g.: "<sip:1.2.3.4;lr>, <sip:5.6.7.8;lr>")
156
- * @param len - resul parameter, it will be filled with the created buffer 
157
- *              lenght.
158
- * @param dst - value/result parameter. It will be used to generate the
159
- *              message. All the values except the send_flags are read-only.
160
- *              send_flags it's updated.
161
- * @return pointer to shm alloc'ed buffer on success (*len and dst->send_flags
162
- *  are filled/modified), 0 on failure
156
+ * @param next_hop - uri of the next hop. If non 0 it will be used
157
+ *              for DNS resolution and the branch request.dst structure will
158
+ *              be filled. If 0 the branch must already have
159
+ *              a pre-filled valid request.dst.
160
+ * @param fproto - forced proto for forwarding. Used only if next_hop!=0.
161
+ * @param flags - 0 or UAC_DNS_FAILOVER_F for now.
162
+ *
163
+ * @return  0 on success, < 0 (ser_errror E***) on failure.
163 164
  */
164
-static char *print_uac_request( struct cell *t, struct sip_msg *i_req,
165
-	int branch, str *uri, str* path, unsigned int *len, struct dest_info* dst)
165
+static int prepare_new_uac( struct cell *t, struct sip_msg *i_req,
166
+									int branch, str *uri, str* path,
167
+									str* next_hop, int fproto,
168
+									int flags)
166 169
 {
167
-	char *buf, *shbuf;
168
-	str* msg_uri;
170
+	char *shbuf;
169 171
 	struct lump* add_rm_backup, *body_lumps_backup;
170 172
 	struct sip_uri parsed_uri_bak;
171
-	int parsed_uri_ok_bak, uri_backed_up;
173
+	int ret;
174
+	unsigned int len;
175
+	int parsed_uri_ok_bak, free_new_uri;
172 176
 	str msg_uri_bak;
177
+	str dst_uri_bak;
178
+	int dst_uri_backed_up;
173 179
 	str path_bak;
174
-	int path_backed_up;
180
+	int free_path;
175 181
 	int backup_route_type;
176 182
 	snd_flags_t fwd_snd_flags_bak;
177 183
 	snd_flags_t rpl_snd_flags_bak;
184
+	struct dest_info *dst;
178 185
 
179 186
 	shbuf=0;
187
+	ret=E_UNSPEC;
180 188
 	msg_uri_bak.s=0; /* kill warnings */
181 189
 	msg_uri_bak.len=0;
182 190
 	parsed_uri_ok_bak=0;
183
-	uri_backed_up=0;
191
+	free_new_uri=0;
192
+	dst_uri_bak.s=0;
193
+	dst_uri_bak.len=0;
194
+	dst_uri_backed_up=0;
184 195
 	path_bak.s=0;
185 196
 	path_bak.len=0;
186
-	path_backed_up=0;
197
+	free_path=0;
198
+	dst=&t->uac[branch].request.dst;
187 199
 
188 200
 	/* ... we calculate branch ... */	
189 201
 	if (!t_calc_branch(t, branch, i_req->add_to_branch_s,
190 202
 			&i_req->add_to_branch_len ))
191 203
 	{
192 204
 		LOG(L_ERR, "ERROR: print_uac_request: branch computation failed\n");
205
+		ret=E_UNSPEC;
193 206
 		goto error00;
194 207
 	}
195 208
 
196
-	/* ... update uri ... */
197
-	msg_uri=GET_RURI(i_req);
198
-	if ((msg_uri->s!=uri->s) || (msg_uri->len!=uri->len)){
199
-		msg_uri_bak=i_req->new_uri;
200
-		parsed_uri_ok_bak=i_req->parsed_uri_ok;
201
-		parsed_uri_bak=i_req->parsed_uri;
202
-		i_req->new_uri=*uri;
203
-		i_req->parsed_uri_ok=0;
204
-		uri_backed_up=1;
205
-	}
206
-	/* update path_vec */
207
-	if (unlikely((i_req->path_vec.s!=path->s) ||
208
-					(i_req->path_vec.len!=path->len))){
209
-		path_bak=i_req->path_vec;
210
-		i_req->path_vec=*path;
211
-		path_backed_up=1;
212
-	}
213
-
209
+	/* dup lumps
210
+	 * TODO: clone lumps only if needed */
214 211
 #ifdef POSTPONE_MSG_CLONING
215 212
 	/* lumps can be set outside of the lock, make sure that we read
216 213
 	 * the up-to-date values */
... ...
@@ -218,85 +232,242 @@ static char *print_uac_request( struct cell *t, struct sip_msg *i_req,
218 218
 #endif
219 219
 	add_rm_backup = i_req->add_rm;
220 220
 	body_lumps_backup = i_req->body_lumps;
221
-	i_req->add_rm = dup_lump_list(i_req->add_rm);
222
-	i_req->body_lumps = dup_lump_list(i_req->body_lumps);
223
-
224
-	if (unlikely(branch_route)) {
225
-		/* run branch_route actions if provided */
226
-		backup_route_type = get_route_type();
227
-		set_route_type(BRANCH_ROUTE);
228
-		tm_ctx_set_branch_index(branch+1);
229
-		if (exec_pre_script_cb(i_req, BRANCH_CB_TYPE)>0) {
230
-			/* backup ireq msg send flags */
231
-			fwd_snd_flags_bak=i_req->fwd_send_flags;;
232
-			rpl_snd_flags_bak=i_req->rpl_send_flags;
233
-			i_req->fwd_send_flags=dst->send_flags /* intial value  */;
234
-			if (run_top_route(branch_rt.rlist[branch_route], i_req, 0) < 0) {
235
-				LOG(L_ERR, "Error in run_top_route\n");
236
-			}
237
-			/* update dst send_flags */
238
-			dst->send_flags=i_req->fwd_send_flags;
239
-			/* restore ireq_msg flags */
240
-			i_req->fwd_send_flags=fwd_snd_flags_bak;
241
-			i_req->rpl_send_flags=rpl_snd_flags_bak;
242
-			exec_post_script_cb(i_req, BRANCH_CB_TYPE);
221
+	i_req->add_rm=0;
222
+	i_req->body_lumps=0;
223
+	if (unlikely(i_req->add_rm)){
224
+		i_req->add_rm = dup_lump_list(i_req->add_rm);
225
+		if (unlikely(i_req->add_rm==0)){
226
+			ret=E_OUT_OF_MEM;
227
+			goto error04;
243 228
 		}
244
-		tm_ctx_set_branch_index(0);
245
-		set_route_type(backup_route_type);
246 229
 	}
230
+	if (unlikely(i_req->body_lumps)){
231
+		i_req->body_lumps = dup_lump_list(i_req->body_lumps);
232
+		if (unlikely(i_req->body_lumps==0)){
233
+			ret=E_OUT_OF_MEM;
234
+			goto error04;
235
+		}
236
+	}
237
+	/* backup uri & path: we need to change them so that build_req...()
238
+	   will use uri & path and not the ones in the original msg (i_req)
239
+	   => we must back them up so that we can restore them to the original
240
+	   value after building the send buffer */
241
+	msg_uri_bak=i_req->new_uri;
242
+	parsed_uri_bak=i_req->parsed_uri;
243
+	parsed_uri_ok_bak=i_req->parsed_uri_ok;
244
+	path_bak=i_req->path_vec;
245
+	
246
+	if (unlikely(branch_route || has_tran_tmcbs(t, TMCB_REQUEST_FWDED))){
247
+		/* dup uris, path a.s.o. if we have a branch route or callback */
248
+		/* ... set ruri ... */
249
+		/* if uri points to new_uri, it needs to be "fixed" so that we can
250
+		   change msg->new_uri */
251
+		if (uri==&i_req->new_uri)
252
+			uri=&msg_uri_bak;
253
+		i_req->parsed_uri_ok=0;
254
+		i_req->new_uri.s=pkg_malloc(uri->len);
255
+		if (unlikely(i_req->new_uri.s==0)){
256
+			ret=E_OUT_OF_MEM;
257
+			goto error03;
258
+		}
259
+		free_new_uri=1;
260
+		memcpy(i_req->new_uri.s, uri->s, uri->len);
261
+		i_req->new_uri.len=uri->len;
262
+	
263
+		/* update path_vec */
264
+		/* if path points to msg path_vec, it needs to be "fixed" so that we