Browse code

Serial forking functions.

This patch adds two new functions to tm module, t_load_contacts and
t_next_contacts which can be used to implement serial forking.

There are also two new parameters, fr_inv_timer_next and contacts_avp.
Parameter fr_inv_timer_next is similar to fr_inv_timer, the value
of this parameter is used for subsequent branches during serial forking.

The value of contacts_avp is the identifier of the AVP which contains
the list of contacts to be used for serial forking.

The serial forking functions originate from Kamailio where they were
implemented by Juha Heinanen.

Jan Janak authored on 06/05/2009 09:17:17
Showing 13 changed files
... ...
@@ -1,139 +1,61 @@
1
-
2 1
 1. TM Module
3 2
 
4 3
 Jiri Kuthan
5 4
 
6 5
    FhG FOKUS
7 6
 
7
+Juha Heinanen
8
+
9
+   <jh@tutpro.com>
10
+
8 11
    Copyright � 2003 FhG FOKUS
12
+
13
+   Copyright � 2008 Juha Heinanen
9 14
    Revision History
10 15
    Revision $Revision$ $Date$
11
-     _________________________________________________________________
12
-
13
-   1.1. Overview
14
-   1.2. Known Issues
15
-   1.3. Parameters
16
-
17
-        1.3.1. fr_timer (integer)
18
-        1.3.2. fr_inv_timer (integer)
19
-        1.3.3. max_inv_lifetime (integer)
20
-        1.3.4. max_noninv_lifetime (integer)
21
-        1.3.5. wt_timer (integer)
22
-        1.3.6. delete_timer (integer)
23
-        1.3.7. retr_timer1 (integer)
24
-        1.3.8. retr_timer2 (integer)
25
-        1.3.9. noisy_ctimer (integer)
26
-        1.3.10. restart_fr_on_each_reply (integer)
27
-        1.3.11. auto_inv_100 (integer)
28
-        1.3.12. unix_tx_timeout (integer)
29
-        1.3.13. aggregate_challenges (integer)
30
-        1.3.14. reparse_invite (integer)
31
-        1.3.15. ac_extra_hdrs (string)
32
-        1.3.16. blst_503 (integer)
33
-        1.3.17. blst_503_def_timeout (integer)
34
-        1.3.18. blst_503_min_timeout (integer)
35
-        1.3.19. blst_503_max_timeout (integer)
36
-        1.3.20. blst_methods_add (unsigned integer)
37
-        1.3.21. blst_methods_lookup (unsigned integer)
38
-        1.3.22. cancel_b_method (integer)
39
-        1.3.23. reparse_on_dns_failover (integer)
40
-        1.3.24. on_sl_reply (string)
41
-
42
-   1.4. Functions
43
-
44
-        1.4.1. t_relay_to_udp(ip, port), t_relay_to_udp(),
45
-                t_relay_to_tcp(ip, port) t_relay_to_tcp()
46
-                t_relay_to_tls(ip, port) t_relay_to_tls()
47
-                t_relay_to_sctp(ip, port) t_relay_to_sctp() 
48
-
49
-        1.4.2. t_relay() t_relay(host, port) 
50
-        1.4.3. t_on_failure(failure_route) 
51
-        1.4.4. t_on_reply(onreply_route) 
52
-        1.4.5. t_on_branch(branch_route) 
53
-        1.4.6. append_branch() 
54
-        1.4.7. t_newtran() 
55
-        1.4.8. t_reply(code, reason_phrase) 
56
-        1.4.9. t_lookup_request() 
57
-        1.4.10. t_retransmit_reply() 
58
-        1.4.11. t_release() 
59
-        1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
60
-                t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip,
61
-                port) t_forward_nonack_tls(ip, port)
62
-                t_forward_nonack_sctp(ip, port) 
63
-
64
-        1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout]) 
65
-        1.4.14. t_reset_fr() 
66
-        1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime) 
67
-        1.4.16. t_reset_max_lifetime() 
68
-        1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval) 
69
-        1.4.18. t_reset_retr() 
70
-        1.4.19. t_set_auto_inv_100(0|1) 
71
-        1.4.20. t_branch_timeout() 
72
-        1.4.21. t_branch_replied() 
73
-        1.4.22. t_any_timeout() 
74
-        1.4.23. t_any_replied() 
75
-        1.4.24. t_grep_status("code") 
76
-        1.4.25. t_is_canceled() 
77
-        1.4.26. t_is_expired() 
78
-        1.4.27. t_relay_cancel() 
79
-        1.4.28. t_lookup_cancel(), t_lookup_cancel(1) 
80
-        1.4.29. t_drop_replies() 
81
-        1.4.30. t_save_lumps() 
82
-
83
-   1.5. TM Module API
84
-
85
-        1.5.1. Defines
86
-        1.5.2. Functions
87
-
88
-              1.5.2.1. register_tmcb(cb_type, cb_func) 
89
-              1.5.2.2. load_tm(*import_structure) 
90
-              1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int
91
-                      *hash_index, unsigned int *label) 
92
-
93
-              1.5.2.4. int t_continue(unsigned int hash_index, unsigned
94
-                      int label, struct action *route) 
16
+     __________________________________________________________________
95 17
 
96 18
 1.1. Overview
97 19
 
98
-   TM module enables stateful processing of SIP transactions. The main
99
-   use of stateful logic, which is costly in terms of memory and CPU, is
100
-   some services inherently need state. For example, transaction-based
20
+   TM module enables stateful processing of SIP transactions. The main use
21
+   of stateful logic, which is costly in terms of memory and CPU, is some
22
+   services inherently need state. For example, transaction-based
101 23
    accounting (module acc) needs to process transaction state as opposed
102 24
    to individual messages, and any kinds of forking must be implemented
103 25
    statefully. Other use of stateful processing is it trading CPU caused
104 26
    by retransmission processing for memory. That makes however only sense
105 27
    if CPU consumption per request is huge. For example, if you want to
106
-   avoid costly DNS resolution for every retransmission of a request to
107
-   an unresolvable destination, use stateful mode. Then, only the initial
28
+   avoid costly DNS resolution for every retransmission of a request to an
29
+   unresolvable destination, use stateful mode. Then, only the initial
108 30
    message burdens server by DNS queries, subsequent retransmissions will
109 31
    be dropped and will not result in more processes blocked by DNS
110 32
    resolution. The price is more memory consumption and higher processing
111 33
    latency.
112 34
 
113 35
    From user's perspective, there are these major functions : t_relay,
114
-   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction
115
-   state, absorb retransmissions from upstream, generate downstream
36
+   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
37
+   absorb retransmissions from upstream, generate downstream
116 38
    retransmissions and correlate replies to requests. t_relay forwards to
117 39
    current URI (be it original request's URI or a URI changed by some of
118 40
    URI-modifying functions, such as sethost). t_relay_to_udp and
119 41
    t_relay_to_tcp forward to a specific address over UDP or TCP
120 42
    respectively.
121 43
 
122
-   In general, if TM is used, it copies clones of received SIP messages
123
-   in shared memory. That costs the memory and also CPU time (memcpys,
124
-   lookups, shmem locks, etc.) Note that non-TM functions operate over
125
-   the received message in private memory, that means that any core
126
-   operations will have no effect on statefully processed messages after
127
-   creating the transactional state. For example, calling record_route
128
-   after t_relay is pretty useless, as the RR is added to privately held
129
-   message whereas its TM clone is being forwarded.
44
+   In general, if TM is used, it copies clones of received SIP messages in
45
+   shared memory. That costs the memory and also CPU time (memcpys,
46
+   lookups, shmem locks, etc.) Note that non-TM functions operate over the
47
+   received message in private memory, that means that any core operations
48
+   will have no effect on statefully processed messages after creating the
49
+   transactional state. For example, calling record_route after t_relay is
50
+   pretty useless, as the RR is added to privately held message whereas
51
+   its TM clone is being forwarded.
130 52
 
131 53
    TM is quite big and uneasy to program--lot of mutexes, shared memory
132
-   access, malloc and free, timers--you really need to be careful when
133
-   you do anything. To simplify TM programming, there is the instrument
134
-   of callbacks. The callback mechanisms allow programmers to register
135
-   their functions to specific event. See t_hooks.h for a list of
136
-   possible events.
54
+   access, malloc and free, timers--you really need to be careful when you
55
+   do anything. To simplify TM programming, there is the instrument of
56
+   callbacks. The callback mechanisms allow programmers to register their
57
+   functions to specific event. See t_hooks.h for a list of possible
58
+   events.
137 59
 
138 60
    Other things programmers may want to know is UAC--it is a very
139 61
    simplistic code which allows you to generate your own transactions.
... ...
@@ -144,16 +66,16 @@ Jiri Kuthan
144 144
 
145 145
 1.2. Known Issues
146 146
 
147
-     * Possibly, performance could be improved by not parsing
148
-       non-INVITEs, as they do not be replied with 100, and do not result
149
-       in ACK/CANCELs, and other things which take parsing. However, we
150
-       need to rethink whether we don't need parsed headers later for
151
-       something else. Remember, when we now conserver a request in
152
-       sh_mem, we can't apply any pkg_mem operations to it any more.
153
-       (that might be redesigned too).
154
-     * Another performance improvement may be achieved by not parsing
155
-       CSeq in replies until reply branch matches branch of an
156
-       INVITE/CANCEL in transaction table.
147
+     * Possibly, performance could be improved by not parsing non-INVITEs,
148
+       as they do not be replied with 100, and do not result in
149
+       ACK/CANCELs, and other things which take parsing. However, we need
150
+       to rethink whether we don't need parsed headers later for something
151
+       else. Remember, when we now conserver a request in sh_mem, we can't
152
+       apply any pkg_mem operations to it any more. (that might be
153
+       redesigned too).
154
+     * Another performance improvement may be achieved by not parsing CSeq
155
+       in replies until reply branch matches branch of an INVITE/CANCEL in
156
+       transaction table.
157 157
      * t_replicate should be done more cleanly--Vias, Routes, etc. should
158 158
        be removed from a message prior to replicating it (well, does not
159 159
        matter any longer so much as there is a new replication module).
... ...
@@ -215,8 +137,8 @@ modparam("tm", "fr_inv_timer", 180000)
215 215
    fr_inv_timer will still be restarted for each increasing reply (e.g.
216 216
    180, 181, 182, ...). Another example when a transaction can live
217 217
    substantially more then its fr_inv_timer and where max_inv_lifetime
218
-   will help is when dns failover is used (each failed dns destination
219
-   can introduce a new branch).
218
+   will help is when dns failover is used (each failed dns destination can
219
+   introduce a new branch).
220 220
 
221 221
    The default value is 180000 ms (180 seconds - the rfc3261 timer C
222 222
    value).
... ...
@@ -249,8 +171,7 @@ modparam("tm", "max_inv_lifetime", 150000)
249 249
    failover is used (each failed dns destination can introduce a new
250 250
    branch).
251 251
 
252
-   The default value is 32000 ms (32 seconds - the rfc3261 timer F
253
-   value).
252
+   The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
254 253
 
255 254
    See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
256 255
    max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
... ...
@@ -263,11 +184,11 @@ modparam("tm", "max_inv_lifetime", 30000)
263 263
 
264 264
 1.3.5. wt_timer (integer)
265 265
 
266
-   Time for which a transaction stays in memory to absorb delayed
267
-   messages after it completed (in milliseconds); also, when this timer
268
-   hits, retransmission of local cancels is stopped (a puristic but
269
-   complex behavior would be not to enter wait state until local branches
270
-   are finished by a final reply or FR timer--we simplified).
266
+   Time for which a transaction stays in memory to absorb delayed messages
267
+   after it completed (in milliseconds); also, when this timer hits,
268
+   retransmission of local cancels is stopped (a puristic but complex
269
+   behavior would be not to enter wait state until local branches are
270
+   finished by a final reply or FR timer--we simplified).
271 271
 
272 272
    Default value is 5000 ms (5 seconds).
273 273
 
... ...
@@ -281,8 +202,8 @@ modparam("tm", "wt_timer", 1000)
281 281
    Time after which a to-be-deleted transaction currently ref-ed by a
282 282
    process will be tried to be deleted again (in milliseconds).
283 283
 
284
-   Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction
285
-   is deleted the moment it's not referenced anymore).
284
+   Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
285
+   deleted the moment it's not referenced anymore).
286 286
 
287 287
    Default value is 200 milliseconds.
288 288
 
... ...
@@ -317,16 +238,15 @@ modparam("tm", "retr_timer2", 2000)
317 317
 
318 318
 1.3.9. noisy_ctimer (integer)
319 319
 
320
-   If set, INVITE transactions that time-out (FR INV timer) will be
321
-   always replied. If it's not set, the transaction has only one branch
322
-   and no response was ever received on this branch, it will be silently
323
-   dropped (no 408 reply will be generated) This behavior is overridden
324
-   if a request is forked, the transaction has a failure route or
325
-   callback, or some functionality explicitly turned it on for a
326
-   transaction (like acc does to avoid unaccounted transactions due to
327
-   expired timer). Turn this off only if you know the client UACs will
328
-   timeout and their timeout interval for INVITEs is lower or equal than
329
-   tm's fr_inv_timer.
320
+   If set, INVITE transactions that time-out (FR INV timer) will be always
321
+   replied. If it's not set, the transaction has only one branch and no
322
+   response was ever received on this branch, it will be silently dropped
323
+   (no 408 reply will be generated) This behavior is overridden if a
324
+   request is forked, the transaction has a failure route or callback, or
325
+   some functionality explicitly turned it on for a transaction (like acc
326
+   does to avoid unaccounted transactions due to expired timer). Turn this
327
+   off only if you know the client UACs will timeout and their timeout
328
+   interval for INVITEs is lower or equal than tm's fr_inv_timer.
330 329
 
331 330
    Default value is 1 (on).
332 331
 
... ...
@@ -339,9 +259,9 @@ modparam("tm", "noisy_ctimer", 1)
339 339
 
340 340
    If set (default), the fr_inv_timer for an INVITE transaction will be
341 341
    restarted for each provisional reply received (rfc3261 mandated
342
-   behaviour). If not set, the fr_inv_timer will be restarted only for
343
-   the first provisional replies and for increasing replies greater or
344
-   equal 180 (e.g. 180, 181, 182, 185, ...).
342
+   behaviour). If not set, the fr_inv_timer will be restarted only for the
343
+   first provisional replies and for increasing replies greater or equal
344
+   180 (e.g. 180, 181, 182, 185, ...).
345 345
 
346 346
    Setting it to 0 is especially useful when dealing with bad UAs that
347 347
    continuously retransmit 180s, not allowing the transaction to timeout
... ...
@@ -364,64 +284,77 @@ modparam("tm", "restart_fr_on_each_reply", 0)
364 364
    Setting it to 0 one can be used to enable doing first some tests or
365 365
    pre-processing on the INVITE and only if some conditions are met
366 366
    manually send a 100 (using t_reply()). Note however that in this case
367
-   all the 100s have to be sent "by hand". t_set_auto_inv_100() might
368
-   help to selectively turn off this feature only for some specific
367
+   all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
368
+   to selectively turn off this feature only for some specific
369 369
    transactions.
370 370
 
371 371
    Default value is 1 (on).
372 372
 
373
-   See also: t_set_auto_inv_100().
373
+   See also: t_set_auto_inv_100() auto_inv_100_reason.
374 374
 
375 375
    Example 11. Set auto_inv_100 parameter
376 376
 ...
377 377
 modparam("tm", "auto_inv_100", 0)
378 378
 ...
379 379
 
380
-1.3.12. unix_tx_timeout (integer)
380
+1.3.12. auto_inv_100_reason (string)
381
+
382
+   Set reason text of the automatically send 100 to an INVITE.
383
+
384
+   Default value is "trying -- your call is important to us".
385
+
386
+   See also: auto_inv_100.
387
+
388
+   Example 12. Set auto_inv_100_reason parameter
389
+...
390
+modparam("tm", "auto_inv_100_reason", "Trying")
391
+...
392
+
393
+1.3.13. unix_tx_timeout (integer)
381 394
 
382 395
    Unix socket transmission timeout, in milliseconds.
383 396
 
384
-   If unix sockets are used (e.g.: to communicate with sems) and sending
385
-   a message on a unix socket takes longer then unix_tx_timeout, the send
397
+   If unix sockets are used (e.g.: to communicate with sems) and sending a
398
+   message on a unix socket takes longer then unix_tx_timeout, the send
386 399
    will fail.
387 400
 
388 401
    The default value is 500 milliseconds.
389 402
 
390
-   Example 12. Set unix_tx_timeout parameter
403
+   Example 13. Set unix_tx_timeout parameter
391 404
 ...
392 405
 modparam("tm", "unix_tx_timeout", 250)
393 406
 ...
394 407
 
395
-1.3.13. aggregate_challenges (integer)
408
+1.3.14. aggregate_challenges (integer)
396 409
 
397 410
    If set (default), the final reply is a 401 or a 407 and more then one
398 411
    branch received a 401 or 407, then all the WWW-Authenticate and
399 412
    Proxy-Authenticate headers from all the 401 and 407 replies will be
400 413
    aggregated in a new final reply. If only one branch received the
401 414
    winning 401 or 407 then this reply will be forwarded (no new one will
402
-   be built). If 0 only the first 401, or if no 401 was received the
403
-   first 407, will be forwarded (no header aggregation).
415
+   be built). If 0 only the first 401, or if no 401 was received the first
416
+   407, will be forwarded (no header aggregation).
404 417
 
405 418
    Default value is 1 (required by rfc3261).
406 419
 
407
-   Example 13. Set aggregate_challenges parameter
420
+   Example 14. Set aggregate_challenges parameter
408 421
 ...
409 422
 modparam("tm", "aggregate_challenges", 0)
410 423
 ...
411 424
 
412
-1.3.14. reparse_invite (integer)
425
+1.3.15. reparse_invite (integer)
413 426
 
414 427
    If set (default), the CANCEL and negative ACK requests are constructed
415 428
    from the INVITE message which was sent out instead of building them
416
-   from the received request. The disadvantage is that the outgoing
417
-   INVITE has to be partially re-parsed, the advantage is that the
418
-   CANCEL/ACK is always RFC 3261-compliant, it always contains the same
419
-   route-set as the INVITE message. Do not disable the INVITE re-parsing
420
-   for example in the following cases:
429
+   from the received request. The disadvantage is that the outgoing INVITE
430
+   has to be partially re-parsed, the advantage is that the CANCEL/ACK is
431
+   always RFC 3261-compliant, it always contains the same route-set as the
432
+   INVITE message. Do not disable the INVITE re-parsing for example in the
433
+   following cases:
421 434
 
422 435
    - The INVITE contains a preloaded route-set, and SER forwards the
423
-   message to the next hop according to the Route header. The Route
424
-   header is not removed in the CANCEL without reparse_invite=1.
436
+   message to the next hop according to the Route header. The Route header
437
+   is not removed in the CANCEL without reparse_invite=1.
425 438
 
426 439
    - SER record-routes, thus an in-dialog INVITE contains a Route header
427 440
    which is removed during loose routing. If the in-dialog INVITE is
... ...
@@ -430,48 +363,48 @@ modparam("tm", "aggregate_challenges", 0)
430 430
 
431 431
    Default value is 1.
432 432
 
433
-   Example 14. Set reparse_invite parameter
433
+   Example 15. Set reparse_invite parameter
434 434
 ...
435 435
 modparam("tm", "reparse_invite", 0)
436 436
 ...
437 437
 
438
-1.3.15. ac_extra_hdrs (string)
438
+1.3.16. ac_extra_hdrs (string)
439 439
 
440 440
    Header fields prefixed by this parameter value are included in the
441 441
    CANCEL and negative ACK messages if they were present in the outgoing
442 442
    INVITE.
443 443
 
444
-   Note, that the parameter value effects only those headers which are
445
-   not covered by RFC-3261 (which are neither mandatory nor prohibited in
444
+   Note, that the parameter value effects only those headers which are not
445
+   covered by RFC-3261 (which are neither mandatory nor prohibited in
446 446
    CANCEL and ACK), and the parameter can be used only together with
447 447
    reparse_invite=1.
448 448
 
449 449
    Default value is "".
450 450
 
451
-   Example 15. Set ac_extra_hdrs parameter
451
+   Example 16. Set ac_extra_hdrs parameter
452 452
 ...
453 453
 modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
454 454
 ...
455 455
 
456
-1.3.16. blst_503 (integer)
456
+1.3.17. blst_503 (integer)
457 457
 
458 458
    If set and the blacklist support is enabled, every 503 reply source is
459 459
    added to the blacklist. The initial blacklist timeout (or ttl) depends
460 460
    on the presence of a Retry-After header in the reply and the values of
461
-   the following tm parameters: blst_503_def_timeout,
462
-   blst_503_min_timeout and blst_503_max_timeout.
461
+   the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
462
+   and blst_503_max_timeout.
463 463
 
464 464
    WARNING:blindly allowing 503 blacklisting could be very easily
465 465
    exploited for DOS attacks in most network setups.
466 466
 
467 467
    The default value is 0 (disabled due to the reasons above).
468 468
 
469
-   Example 16. Set blst_503 parameter
469
+   Example 17. Set blst_503 parameter
470 470
 ...
471 471
 modparam("tm", "blst_503", 1)
472 472
 ...
473 473
 
474
-1.3.17. blst_503_def_timeout (integer)
474
+1.3.18. blst_503_def_timeout (integer)
475 475
 
476 476
    Blacklist interval in seconds for a 503 reply with no Retry-After
477 477
    header. See also blst_503, blst_503_min_timeout and
... ...
@@ -481,12 +414,12 @@ modparam("tm", "blst_503", 1)
481 481
    present, the 503 reply source will not be blacklisted (rfc conformant
482 482
    behaviour).
483 483
 
484
-   Example 17. Set blst_503_def_timeout parameter
484
+   Example 18. Set blst_503_def_timeout parameter
485 485
 ...
486 486
 modparam("tm", "blst_503_def_timeout", 120)
487 487
 ...
488 488
 
489
-1.3.18. blst_503_min_timeout (integer)
489
+1.3.19. blst_503_min_timeout (integer)
490 490
 
491 491
    Minimum blacklist interval in seconds for a 503 reply with a
492 492
    Retry-After header. It will be used if the Retry-After value is
... ...
@@ -495,12 +428,12 @@ modparam("tm", "blst_503_def_timeout", 120)
495 495
 
496 496
    The default value is 0
497 497
 
498
-   Example 18. Set blst_503_min_timeout parameter
498
+   Example 19. Set blst_503_min_timeout parameter
499 499
 ...
500 500
 modparam("tm", "blst_503_min_timeout", 30)
501 501
 ...
502 502
 
503
-1.3.19. blst_503_max_timeout (integer)
503
+1.3.20. blst_503_max_timeout (integer)
504 504
 
505 505
    Maximum blacklist interval in seconds for a 503 reply with a
506 506
    Retry-After header. It will be used if the Retry-After value is
... ...
@@ -509,12 +442,12 @@ modparam("tm", "blst_503_min_timeout", 30)
509 509
 
510 510
    The default value is 3600
511 511
 
512
-   Example 19. Set blst_503_max_timeout parameter
512
+   Example 20. Set blst_503_max_timeout parameter
513 513
 ...
514 514
 modparam("tm", "blst_503_max_timeout", 604800)
515 515
 ...
516 516
 
517
-1.3.20. blst_methods_add (unsigned integer)
517
+1.3.21. blst_methods_add (unsigned integer)
518 518
 
519 519
    Bitmap of method types that trigger blacklisting on transaction
520 520
    timeouts. (This setting has no effect on blacklisting because of send
... ...
@@ -533,13 +466,13 @@ modparam("tm", "blst_503_max_timeout", 604800)
533 533
 
534 534
    The default value is 1, only INVITEs trigger blacklisting
535 535
 
536
-   Example 20. Set blst_methods_add parameter
536
+   Example 21. Set blst_methods_add parameter
537 537
 ...
538 538
 # INVITEs and REGISTERs trigger blacklisting
539 539
 modparam("tm", "blst_methods_add", 33)
540 540
 ...
541 541
 
542
-1.3.21. blst_methods_lookup (unsigned integer)
542
+1.3.22. blst_methods_lookup (unsigned integer)
543 543
 
544 544
    Bitmap of method types that are looked-up in the blacklist before
545 545
    statefull forwarding. See also blst_methods_add
... ...
@@ -547,21 +480,21 @@ modparam("tm", "blst_methods_add", 33)
547 547
    The default value is 4294967287, every method type except BYE. (We try
548 548
    to deliver BYEs no matter what)
549 549
 
550
-   Example 21. Set blst_methods_lookup parameter
550
+   Example 22. Set blst_methods_lookup parameter
551 551
 ...
552 552
 # lookup only INVITEs
553 553
 modparam("tm", "blst_methods_lookup", 1)
554 554
 ...
555 555
 
556
-1.3.22. cancel_b_method (integer)
556
+1.3.23. cancel_b_method (integer)
557 557
 
558 558
    Method used when attempting to CANCEL an unreplied transaction branch
559 559
    (a branch where no reply greater the 99 was received). The possible
560 560
    values are 0, 1, and 2.
561 561
 
562 562
    0 will immediately stop the request (INVITE) retransmission on the
563
-   branch and it will behave as if the branch was immediately replied
564
-   with a 487 (a fake internal 487 reply). The advantage is the unreplied
563
+   branch and it will behave as if the branch was immediately replied with
564
+   a 487 (a fake internal 487 reply). The advantage is the unreplied
565 565
    branches will be terminated immediately. However it introduces a race
566 566
    risk with a possible slightly delayed 2xx reply. In this case we could
567 567
    have an UA receiving a 2xx after a 487. Moreover this risk is greatly
... ...
@@ -573,25 +506,25 @@ modparam("tm", "blst_methods_lookup", 1)
573 573
    1 will keep retransmitting the request on unreplied branches. If a
574 574
    provisional answer is later received a CANCEL will be immediately sent
575 575
    back (attempting to quickly trigger a 487). This approach is race free
576
-   and avoids the 2xx after 487 problem, but it's more resource
577
-   intensive: faced with a branch towards and UA that doesn't answer, a
578
-   CANCEL attempt will keep the transaction alive for the whole timeout
579
-   interval (fr_timer).
576
+   and avoids the 2xx after 487 problem, but it's more resource intensive:
577
+   faced with a branch towards and UA that doesn't answer, a CANCEL
578
+   attempt will keep the transaction alive for the whole timeout interval
579
+   (fr_timer).
580 580
 
581 581
    2 will send and retransmit CANCEL even on unreplied branches, stopping
582
-   the request retransmissions. This has the same advantages as 1 and
583
-   also avoids the extra roundtrip in the case of the provisional reply,
584
-   but it's not RFC 3261 conforming (the RFC allows sending CANCELs only
585
-   on pending branches).
582
+   the request retransmissions. This has the same advantages as 1 and also
583
+   avoids the extra roundtrip in the case of the provisional reply, but
584
+   it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
585
+   pending branches).
586 586
 
587 587
    The default value is 1.
588 588
 
589
-   Example 22. Set cancel_b_method parameter
589
+   Example 23. Set cancel_b_method parameter
590 590
 ...
591 591
 modparam("tm", "cancel_b_method", 1)
592 592
 ...
593 593
 
594
-1.3.23. reparse_on_dns_failover (integer)
594
+1.3.24. reparse_on_dns_failover (integer)
595 595
 
596 596
    If set to 1, the SIP message after a DNS failover is constructed from
597 597
    the outgoing message buffer of the failed branch instead of from the
... ...
@@ -605,28 +538,28 @@ modparam("tm", "cancel_b_method", 1)
605 605
    Note: If the parameter is set, branch route block and
606 606
    TMCB_REQUEST_FWDED callback are not called in case of the failover.
607 607
 
608
-   Disadvantage: only the via header is replaced in the message buffer,
609
-   so the outgoing socket address is not corrected in any other part of
610
-   the message. It is dangerous on multihomed hosts: when the new SIP
611
-   request after the DNS failover is sent via different interface than
612
-   the first request, the message can contain incorrect ip address in the
608
+   Disadvantage: only the via header is replaced in the message buffer, so
609
+   the outgoing socket address is not corrected in any other part of the
610
+   message. It is dangerous on multihomed hosts: when the new SIP request
611
+   after the DNS failover is sent via different interface than the first
612
+   request, the message can contain incorrect ip address in the
613 613
    Record-Route header for instance.
614 614
 
615 615
    Default value is 1.
616 616
 
617
-   Example 23. Set reparse_on_dns_failover parameter
617
+   Example 24. Set reparse_on_dns_failover parameter
618 618
 ...
619 619
 modparam("tm", "reparse_on_dns_failover", 0)
620 620
 ...
621 621
 
622
-1.3.24. on_sl_reply (string)
622
+1.3.25. on_sl_reply (string)
623 623
 
624 624
    Sets reply route block, to which control is passed when a reply is
625
-   received that has no associated transaction. The reply is passed to
626
-   the core for stateless forwarding after the route block execution
627
-   unless it returns 0.
625
+   received that has no associated transaction. The reply is passed to the
626
+   core for stateless forwarding after the route block execution unless it
627
+   returns 0.
628 628
 
629
-   Example 24. Set on_sl_reply parameter
629
+   Example 25. Set on_sl_reply parameter
630 630
 ...
631 631
 modparam("tm", "on_sl_reply", "stateless_replies")
632 632
 ...
... ...
@@ -636,6 +569,36 @@ onreply_route["stateless_replies"] {
636 636
         return 0;
637 637
 }
638 638
 
639
+1.3.26. fr_inv_timer_next (integer)
640
+
641
+   Value of the Final Response timeout for INVITE transactions to be used
642
+   during serial forwarding:
643
+
644
+   Function t_next_contacts() sets fr_inv_timer to fr_inv_timer_next value
645
+   if, after t_next_contacts() is called, there are still lower qvalue
646
+   contacts available, and to fr_inv_timer value if there are not.
647
+
648
+   Default value is 30.
649
+
650
+   Example 26. Set fr_inv_timer_next parameter
651
+...
652
+modparam("tm", "fr_inv_timer_next", 10)
653
+...
654
+
655
+1.3.27. contacts_avp (string)
656
+
657
+   Internal AVP that t_load_contacts() function uses to store contacts of
658
+   the destination set and that t_next_contacts() function uses to restore
659
+   those contacts.
660
+
661
+   Default value is "NULL" (t_load_contacts()/t_next_contacts() functions
662
+   are disabled).
663
+
664
+   Example 27. Set contacts_avp parameter
665
+...
666
+modparam("tm", "contacts_avp", "$avp(i:25)")
667
+...
668
+
639 669
 1.4. Functions
640 670
 
641 671
    Revision History
... ...
@@ -658,10 +621,10 @@ t_relay_to_sctp(ip, port) t_relay_to_sctp()
658 658
      * port - Port number.
659 659
 
660 660
    If no parameters are specified the message is sent to a destination
661
-   derived from the message uri (using sip sepcific DNS lookups), but
662
-   with the protocol corresponding to the function name.
661
+   derived from the message uri (using sip sepcific DNS lookups), but with
662
+   the protocol corresponding to the function name.
663 663
 
664
-   Example 25. t_relay_to_udp usage
664
+   Example 28. t_relay_to_udp usage
665 665
 ...
666 666
 if (src_ip==10.0.0.0/8)
667 667
         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
... ...
@@ -672,24 +635,23 @@ else
672 672
 1.4.2.  t_relay() t_relay(host, port)
673 673
 
674 674
    Relay a message statefully either to the destination indicated in the
675
-   current URI (if called without any parameters) or to the specified
676
-   host and port. In the later case (host and port specified) the
677
-   protocol used is the same protocol on which the message was received.
675
+   current URI (if called without any parameters) or to the specified host
676
+   and port. In the later case (host and port specified) the protocol used
677
+   is the same protocol on which the message was received.
678 678
 
679 679
    t_relay() is the statefull version for forward(uri:host, uri:port)
680 680
    while t_relay(host, port) is similar to forward(host, port).
681 681
 
682 682
    In the forward to uri case (t_relay()), if the original URI was
683 683
    rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
684
-   taken). The destination (including the protocol) is determined from
685
-   the uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
684
+   taken). The destination (including the protocol) is determined from the
685
+   uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
686 686
    depending also on the dns options).
687 687
 
688 688
    Returns a negative value on failure--you may still want to send a
689
-   negative reply upstream statelessly not to leave upstream UAC in
690
-   lurch.
689
+   negative reply upstream statelessly not to leave upstream UAC in lurch.
691 690
 
692
-   Example 26. t_relay usage
691
+   Example 29. t_relay usage
693 692
 ...
694 693
 if (!t_relay())
695 694
 {
... ...
@@ -701,24 +663,24 @@ if (!t_relay())
701 701
 1.4.3.  t_on_failure(failure_route)
702 702
 
703 703
    Sets failure routing block, to which control is passed after a
704
-   transaction completed with a negative result but before sending a
705
-   final reply. In the referred block, you can either start a new branch
706
-   (good for services such as forward_on_no_reply) or send a final reply
707
-   on your own (good for example for message silo, which received a
708
-   negative reply from upstream and wants to tell upstream "202 I will
709
-   take care of it"). Note that the set of commands which are usable
710
-   within failure_routes is strictly limited to rewriting URI, initiating
711
-   new branches, logging, and sending stateful replies (t_reply). Any
712
-   other commands may result in unpredictable behavior and possible
713
-   server failure. Note that whenever failure_route is entered, uri is
714
-   reset to value which it had on relaying. If it temporarily changed
715
-   during a reply_route processing, subsequent reply_route will ignore
716
-   the changed value and use again the original one.
704
+   transaction completed with a negative result but before sending a final
705
+   reply. In the referred block, you can either start a new branch (good
706
+   for services such as forward_on_no_reply) or send a final reply on your
707
+   own (good for example for message silo, which received a negative reply
708
+   from upstream and wants to tell upstream "202 I will take care of it").
709
+   Note that the set of commands which are usable within failure_routes is
710
+   strictly limited to rewriting URI, initiating new branches, logging,
711
+   and sending stateful replies (t_reply). Any other commands may result
712
+   in unpredictable behavior and possible server failure. Note that
713
+   whenever failure_route is entered, uri is reset to value which it had
714
+   on relaying. If it temporarily changed during a reply_route processing,
715
+   subsequent reply_route will ignore the changed value and use again the
716
+   original one.
717 717
 
718 718
    Meaning of the parameters is as follows:
719 719
      * failure_route - Failure route block to be called.
720 720
 
721
-   Example 27. t_on_failure usage
721
+   Example 30. t_on_failure usage
722 722
 ...
723 723
 route {
724 724
     t_on_failure("1");
... ...
@@ -744,7 +706,7 @@ failure_route[1] {
744 744
    Meaning of the parameters is as follows:
745 745
      * onreply_route - Onreply route block to be called.
746 746
 
747
-   Example 28. t_on_reply usage
747
+   Example 31. t_on_reply usage
748 748
 ...
749 749
 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
750 750
 ...
... ...
@@ -757,8 +719,8 @@ route {
757 757
 onreply_route[1] {
758 758
         if (status=~ "(183)|2[0-9][0-9]"){
759 759
                 force_rtp_proxy();
760
-                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=
761
-yes');
760
+                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
761
+es');
762 762
         }
763 763
         if (nat_uac_test("1")){
764 764
                 fix_nated_contact();
... ...
@@ -767,17 +729,16 @@ yes');
767 767
 
768 768
 1.4.5.  t_on_branch(branch_route)
769 769
 
770
-   Sets the branch routing block, to which control is passed after
771
-   forking (when a new branch is created). For now branch routes are
772
-   intended only for last minute changes of the SIP messages (like adding
773
-   new headers). Note that the set of commands which are usable within
774
-   branch_routes is very limited. It is not possible to drop a message or
775
-   generate a reply.
770
+   Sets the branch routing block, to which control is passed after forking
771
+   (when a new branch is created). For now branch routes are intended only
772
+   for last minute changes of the SIP messages (like adding new headers).
773
+   Note that the set of commands which are usable within branch_routes is
774
+   very limited. It is not possible to drop a message or generate a reply.
776 775
 
777 776
    Meaning of the parameters is as follows:
778 777
      * branch_route - branch route block to be called.
779 778
 
780
-   Example 29. t_on_branch usage
779
+   Example 32. t_on_branch usage
781 780
 ...
782 781
 route {
783 782
         t_on_branch("1");
... ...
@@ -795,7 +756,7 @@ branch_route[1] {
795 795
    Similarly to t_fork_to, it extends destination set by a new entry. The
796 796
    difference is that current URI is taken as new entry.
797 797
 
798
-   Example 30. append_branch usage
798
+   Example 33. append_branch usage
799 799
 ...
800 800
 set_user("john");
801 801
 t_fork();
... ...
@@ -810,7 +771,7 @@ t_relay();
810 810
    the only way a script can add a new transaction in an atomic way.
811 811
    Typically, it is used to deploy a UAS.
812 812
 
813
-   Example 31. t_newtran usage
813
+   Example 34. t_newtran usage
814 814
 ...
815 815
 if (t_newtran()) {
816 816
     log("UAS logic");
... ...
@@ -829,7 +790,7 @@ if (t_newtran()) {
829 829
      * code - Reply code number.
830 830
      * reason_phrase - Reason string.
831 831
 
832
-   Example 32. t_reply usage
832
+   Example 35. t_reply usage
833 833
 ...
834 834
 t_reply("404", "Not found");
835 835
 ...
... ...
@@ -842,7 +803,7 @@ t_reply("404", "Not found");
842 842
    none was found. However this is safely (atomically) done using
843 843
    t_newtran.
844 844
 
845
-   Example 33. t_lookup_request usage
845
+   Example 36. t_lookup_request usage
846 846
 ...
847 847
 if (t_lookup_request()) {
848 848
     ...
... ...
@@ -853,17 +814,17 @@ if (t_lookup_request()) {
853 853
 
854 854
    Retransmits a reply sent previously by UAS transaction.
855 855
 
856
-   Example 34. t_retransmit_reply usage
856
+   Example 37. t_retransmit_reply usage
857 857
 ...
858 858
 t_retransmit_reply();
859 859
 ...
860 860
 
861 861
 1.4.11.  t_release()
862 862
 
863
-   Remove transaction from memory (it will be first put on a wait timer
864
-   to absorb delayed messages).
863
+   Remove transaction from memory (it will be first put on a wait timer to
864
+   absorb delayed messages).
865 865
 
866
-   Example 35. t_release usage
866
+   Example 38. t_release usage
867 867
 ...
868 868
 t_release();
869 869
 ...
... ...
@@ -878,7 +839,7 @@ t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
878 878
      * ip - IP address where the message should be sent.
879 879
      * port - Port number.
880 880
 
881
-   Example 36. t_forward_nonack usage
881
+   Example 39. t_forward_nonack usage
882 882
 ...
883 883
 t_forward_nonack("1.2.3.4", "5060");
884 884
 ...
... ...
@@ -901,7 +862,7 @@ t_forward_nonack("1.2.3.4", "5060");
901 901
 
902 902
    See also: fr_timer, fr_inv_timer, t_reset_fr().
903 903
 
904
-   Example 37. t_set_fr usage
904
+   Example 40. t_set_fr usage
905 905
 ...
906 906
 route {
907 907
         t_set_fr(10000); # set only fr invite timeout to 10s
... ...
@@ -919,16 +880,16 @@ branch_route[1] {
919 919
 
920 920
 1.4.14.  t_reset_fr()
921 921
 
922
-   Resets the fr_inv_timer and fr_timer for the current transaction to
923
-   the default values (set using the tm module parameters fr_inv_timer
924
-   and fr_timer).
922
+   Resets the fr_inv_timer and fr_timer for the current transaction to the
923
+   default values (set using the tm module parameters fr_inv_timer and
924
+   fr_timer).
925 925
 
926 926
    It will effectively cancel any previous calls to t_set_fr for the same
927 927
    transaction.
928 928
 
929 929
    See also: fr_timer, fr_inv_timer, t_set_fr.
930 930
 
931
-   Example 38. t_reset_fr usage
931
+   Example 41. t_reset_fr usage
932 932
 ...
933 933
 route {
934 934
 ...
... ...
@@ -940,9 +901,9 @@ route {
940 940
 
941 941
    Sets the maximum lifetime for the current INVITE or non-INVITE
942 942
    transaction, or for transactions created during the same script
943
-   invocation, after calling this function (that's why it takes values
944
-   for both INVITE and non-INVITE). If one of the parameters is 0, its
945
-   value won't be changed.
943
+   invocation, after calling this function (that's why it takes values for
944
+   both INVITE and non-INVITE). If one of the parameters is 0, its value
945
+   won't be changed.
946 946
 
947 947
    It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
948 948
 
... ...
@@ -954,7 +915,7 @@ route {
954 954
 
955 955
    See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
956 956
 
957
-   Example 39. t_set_max_lifetime usage
957
+   Example 42. t_set_max_lifetime usage
958 958
 ...
959 959
 route {
960 960
     if (src_ip=1.2.3.4)
... ...
@@ -971,12 +932,12 @@ route {
971 971
    transaction to the default value (set using the tm module parameter
972 972
    max_inv_lifetime or max_noninv_lifetime).
973 973
 
974
-   It will effectively cancel any previous calls to t_set_max_lifetime
975
-   for the same transaction.
974
+   It will effectively cancel any previous calls to t_set_max_lifetime for
975
+   the same transaction.
976 976
 
977 977
    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
978 978
 
979
-   Example 40. t_reset_max_lifetime usage
979
+   Example 43. t_reset_max_lifetime usage
980 980
 ...
981 981
 route {
982 982
 ...
... ...
@@ -988,9 +949,9 @@ route {
988 988
 
989 989
    Sets the retr_t1_interval and retr_t2_interval for the current
990 990
    transaction or for transactions created during the same script
991
-   invocation, after calling this function. If one of the parameters is
992
-   0, it's value won't be changed. If the transaction is already created
993
-   (e.g called after t_relay() or in an onreply_route) all the existing
991
+   invocation, after calling this function. If one of the parameters is 0,
992
+   it's value won't be changed. If the transaction is already created (e.g
993
+   called after t_relay() or in an onreply_route) all the existing
994 994
    branches will have their retransmissions intervals updated on-the-fly:
995 995
    if the retransmission interval for the branch has not yet reached T2
996 996
    the interval will be reset to retr_t1_interval, else to
... ...
@@ -998,11 +959,11 @@ route {
998 998
    interval expires (after the next retransmission, the next-next
999 999
    retransmission will take place at retr_t1_interval or
1000 1000
    retr_t2_interval). All new branches of the same transaction will start
1001
-   with the new values. This function will work even if it's called in
1002
-   the script before a transaction creating function (e.g.:
1003
-   t_set_retr(500, 4000); t_relay()). All new transaction created after
1004
-   this function call, during the same script invocation will use the new
1005
-   values. Note that this function will work only if tm is compile with
1001
+   with the new values. This function will work even if it's called in the
1002
+   script before a transaction creating function (e.g.: t_set_retr(500,
1003
+   4000); t_relay()). All new transaction created after this function
1004
+   call, during the same script invocation will use the new values. Note
1005
+   that this function will work only if tm is compile with
1006 1006
    -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
1007 1007
    bytes).
1008 1008
 
... ...
@@ -1014,7 +975,7 @@ route {
1014 1014
 
1015 1015
    See also: retr_timer1, retr_timer2, t_reset_retr().
1016 1016
 
1017
-   Example 41. t_set_retr usage
1017
+   Example 44. t_set_retr usage
1018 1018
 ...
1019 1019
 route {
1020 1020
         t_set_retr(250, 0); # set only T1 to 250 ms
... ...
@@ -1041,7 +1002,7 @@ branch_route[1] {
1041 1041
 
1042 1042
    See also: retr_timer1, retr_timer2, t_set_retr.
1043 1043
 
1044
-   Example 42. t_reset_retr usage
1044
+   Example 45. t_reset_retr usage
1045 1045
 ...
1046 1046
 route {
1047 1047
 ...
... ...
@@ -1057,7 +1018,7 @@ route {
1057 1057
 
1058 1058
    See also: auto_inv_100.
1059 1059
 
1060
-   Example 43. t_set_auto_inv_100 usage
1060
+   Example 46. t_set_auto_inv_100 usage
1061 1061
 ...
1062 1062
 route {
1063 1063
 ...
... ...
@@ -1071,7 +1032,7 @@ route {
1071 1071
    Returns true if the failure route is executed for a branch that did
1072 1072
    timeout. It can be used only from the failure_route.
1073 1073
 
1074
-   Example 44. t_branch_timeout usage
1074
+   Example 47. t_branch_timeout usage
1075 1075
 ...
1076 1076
 failure_route[0]{
1077 1077
         if (t_branch_timeout()){
... ...
@@ -1086,7 +1047,7 @@ failure_route[0]{
1086 1086
    receive at least one reply in the past (the "current" reply is not
1087 1087
    taken into account). It can be used only from the failure_route.
1088 1088
 
1089
-   Example 45. t_branch_replied usage
1089
+   Example 48. t_branch_replied usage
1090 1090
 ...
1091 1091
 failure_route[0]{
1092 1092
         if (t_branch_timeout()){
... ...
@@ -1103,7 +1064,7 @@ failure_route[0]{
1103 1103
    Returns true if at least one of the current transactions branches did
1104 1104
    timeout.
1105 1105
 
1106
-   Example 46. t_any_timeout usage
1106
+   Example 49. t_any_timeout usage
1107 1107
 ...
1108 1108
 failure_route[0]{
1109 1109
         if (!t_branch_timeout()){
... ...
@@ -1120,7 +1081,7 @@ failure_route[0]{
1120 1120
    receive some reply in the past. If called from a failure or onreply
1121 1121
    route, the "current" reply is not taken into account.
1122 1122
 
1123
-   Example 47. t_any_replied usage
1123
+   Example 50. t_any_replied usage
1124 1124
 ...
1125 1125
 onreply_route[0]{
1126 1126
         if (!t_any_replied()){
... ...
@@ -1134,7 +1095,7 @@ onreply_route[0]{
1134 1134
    Returns true if "code" is the final reply received (or locally
1135 1135
    generated) in at least one of the current transactions branches.
1136 1136
 
1137
-   Example 48. t_grep_status usage
1137
+   Example 51. t_grep_status usage
1138 1138
 ...
1139 1139
 onreply_route[0]{
1140 1140
         if (t_grep_status("486")){
... ...
@@ -1147,7 +1108,7 @@ onreply_route[0]{
1147 1147
 
1148 1148
    Returns true if the current transaction was canceled.
1149 1149
 
1150
-   Example 49. t_is_canceled usage
1150
+   Example 52. t_is_canceled usage
1151 1151
 ...
1152 1152
 failure_route[0]{
1153 1153
         if (t_is_canceled()){
... ...
@@ -1161,7 +1122,7 @@ failure_route[0]{
1161 1161
    Returns true if the current transaction has already been expired, i.e.
1162 1162
    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
1163 1163
 
1164
-   Example 50. t_is_expired usage
1164
+   Example 53. t_is_expired usage
1165 1165
 ...
1166 1166
 failure_route[0]{
1167 1167
         if (t_is_expired()){
... ...
@@ -1172,17 +1133,17 @@ failure_route[0]{
1172 1172
 
1173 1173
 1.4.27.  t_relay_cancel()
1174 1174
 
1175
-   Forwards the CANCEL if the corresponding INVITE transaction exists.
1176
-   The function is supposed to be used at the very beginning of the
1177
-   script, because the CANCELs can be caught and the rest of the script
1178
-   can be bypassed this way. Do not disable reparse_invite module
1179
-   parameter, and call t_relay_cancel() right after the sanity tests.
1175
+   Forwards the CANCEL if the corresponding INVITE transaction exists. The
1176
+   function is supposed to be used at the very beginning of the script,
1177
+   because the CANCELs can be caught and the rest of the script can be
1178
+   bypassed this way. Do not disable reparse_invite module parameter, and
1179
+   call t_relay_cancel() right after the sanity tests.
1180 1180
 
1181 1181
    Return value is 0 (drop) if the corresponding INVITE was found and the
1182 1182
    CANCELs were successfully sent to the pending branches, true if the
1183 1183
    INVITE was not found, and false in case of any error.
1184 1184
 
1185
-   Example 51. t_relay_cancel usage
1185
+   Example 54. t_relay_cancel usage
1186 1186
 if (method == CANCEL) {
1187 1187
         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
1188 1188
                                   # nothing to do
... ...
@@ -1205,11 +1166,11 @@ if (method == CANCEL) {
1205 1205
    explicitly call this function unless something has to be logged for
1206 1206
    example.
1207 1207
 
1208
-   If the function parameter (optional) is set to 1, the message flags
1209
-   are overwritten with the flags of the INVITE. isflagset() can be used
1210
-   to check the flags of the previously forwarded INVITE in this case.
1208
+   If the function parameter (optional) is set to 1, the message flags are
1209
+   overwritten with the flags of the INVITE. isflagset() can be used to
1210
+   check the flags of the previously forwarded INVITE in this case.
1211 1211
 
1212
-   Example 52. t_lookup_cancel usage
1212
+   Example 55. t_lookup_cancel usage
1213 1213
 if (method == CANCEL) {
1214 1214
         if (t_lookup_cancel()) {
1215 1215
                 log("INVITE transaction exists");
... ...
@@ -1234,7 +1195,7 @@ if (method == CANCEL) {
1234 1234
    branch is added to the transaction, or it is explicitly replied in the
1235 1235
    script!
1236 1236
 
1237
-   Example 53. t_drop_replies() usage
1237
+   Example 56. t_drop_replies() usage
1238 1238
 ...
1239 1239
 failure_route[0]{
1240 1240
         if (t_check_status("5[0-9][0-9]")){
... ...
@@ -1265,7 +1226,7 @@ failure_route[0]{
1265 1265
    The transaction must be created by t_newtran() before calling
1266 1266
    t_save_lumps().
1267 1267
 
1268
-   Example 54. t_save_lumps() usage
1268
+   Example 57. t_save_lumps() usage
1269 1269
 route {
1270 1270
         ...
1271 1271
         t_newtran();
... ...
@@ -1290,6 +1251,61 @@ failure_route[1] {
1290 1290
         t_relay();
1291 1291
 }
1292 1292
 
1293
+1.4.31.  t_load_contacts()
1294
+
1295
+   Loads contacts in destination set in increasing qvalue order as values
1296
+   of contacts_avp. If all contacts in the destination set have the same
1297
+   qvalue, t_load_contacts() does not do anything thus minimizing
1298
+   performance impact of serial forking capability when it is not needed.
1299
+   Returns 1 if loading of contacts succeeded or there was nothing to do.
1300
+   Returns -1 on error (see syslog).
1301
+
1302
+   This function can be used from REQUEST_ROUTE.
1303
+
1304
+   Example 58. t_load_contacts usage
1305
+...
1306
+if (!t_load_contacts()) {
1307
+        sl_send_reply("500", "Server Internal Error - Cannot load contacts");
1308
+        exit;
1309
+};
1310
+...
1311
+
1312
+1.4.32.  t_next_contacts()
1313
+
1314
+   If transaction does not exist when t_next_contacts() is called,
1315
+   replaces Request-URI with the first contacts_avp value, adds the
1316
+   remaining contacts_avp values with the same qvalue as branches, and
1317
+   destroys those AVPs. It does nothing if there are no contacts_avp
1318
+   values. Returns 1 if there were no errors and -1 if an error occurred
1319
+   (see syslog).
1320
+
1321
+   If transaction does exist when t_next_contacts() is called, adds the
1322
+   first contacts_avp value and all following contacts_avp values with the
1323
+   same qvalue as new branches to request and destroys those AVPs. Returns
1324
+   1 if new branches were successfully added and -1 on error (see syslog)
1325
+   or if there were no more contacts_avp values.
1326
+
1327
+   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
1328
+
1329
+   Example 59. t_next_contacts usage
1330
+...
1331
+# First call after t_load_contacts() when transaction does not exist yet
1332
+# and contacts should be available
1333
+if (!t_next_contacts()) {
1334
+        sl_send_reply("500", "Server Internal Error - Cannot get contacts");
1335
+} else {
1336
+        t_relay();
1337
+};
1338
+...
1339
+# Following call, when transaction exists and there may or may not be
1340
+# contacts left
1341
+if (!t_next_contacts()) {
1342
+        t_reply("408", "Request Timeout");
1343
+} else {
1344
+        t_relay();
1345
+};
1346
+...
1347
+
1293 1348
 1.5. TM Module API
1294 1349
 
1295 1350
    Revision History
... ...
@@ -1342,21 +1358,21 @@ end of body
1342 1342
 1.5.1. Defines
1343 1343
 
1344 1344
      * ACK_TAG enables stricter matching of acknowledgments including
1345
-       to-tags. Without it, to-tags are ignored. It is disabled by
1346
-       default for two reasons:
1345
+       to-tags. Without it, to-tags are ignored. It is disabled by default
1346
+       for two reasons:
1347 1347
           + It eliminates an unlikely race condition in which
1348
-            transaction's to-tag is being rewritten by a 200 OK whereas
1349
-            an ACK is being looked up by to-tag.
1348
+            transaction's to-tag is being rewritten by a 200 OK whereas an
1349
+            ACK is being looked up by to-tag.
1350 1350
           + It makes UACs happy who set wrong to-tags.
1351 1351
        It should not make a difference, as there may be only one negative
1352
-       reply sent upstream and 200/ACKs are not matched as they
1353
-       constitute another transaction. It will make no difference at all
1354
-       when the new magic cookie matching is enabled anyway.
1352
+       reply sent upstream and 200/ACKs are not matched as they constitute
1353
+       another transaction. It will make no difference at all when the new
1354
+       magic cookie matching is enabled anyway.
1355 1355
      * CANCEL_TAG similarly enables strict matching of CANCELs including
1356 1356
        to-tags--act of mercy to UACs, who screw up the to-tags (however,
1357
-       it still depends on how forgiving the downstream UAS is). Like
1358
-       with ACK_TAG, all this complex transactions matching goes with
1359
-       RFC3261's magic cookie away anyway.
1357
+       it still depends on how forgiving the downstream UAS is). Like with
1358
+       ACK_TAG, all this complex transactions matching goes with RFC3261's
1359
+       magic cookie away anyway.
1360 1360
 
1361 1361
 1.5.2. Functions
1362 1362
 
... ...
@@ -1380,8 +1396,8 @@ end of body
1380 1380
 1.5.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
1381 1381
 unsigned int *label)
1382 1382
 
1383
-   For programmatic use only. This function together with t_continue()
1384
-   can be used to implement asynchronous actions: t_suspend() saves the
1383
+   For programmatic use only. This function together with t_continue() can
1384
+   be used to implement asynchronous actions: t_suspend() saves the
1385 1385
    transaction, returns its identifiers, and t_continue() continues the
1386 1386
    SIP request processing. (The request processing does not continue from
1387 1387
    the same point in the script, a separate route block defined by the
... ...
@@ -1403,17 +1419,17 @@ unsigned int *label)
1403 1403
 
1404 1404
    Usage: Allocate a memory block for storing the transaction identifiers
1405 1405
    (hash_index and label), and for storing also any variable related to
1406
-   the async query. Before calling t_suspend(), register for the
1407
-   following callbacks, and pass the pointer to the allocated shared
1408
-   memory as a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and
1409
-   TMCB_E2ECANCEL_IN (in case of INVITE transaction). The async operation
1410
-   can be cancelled, if it is still pending, when TMCB_ON_FAILURE or
1411
-   TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free the
1412
-   shared memory allocated for the async and SIP transaction identifiers.
1413
-   Once the async query result is available call t_continue(), see below.
1414
-   The SIP transaction must exist before calling t_suspend(), and the
1415
-   module function calling t_suspend() should return 0 to make sure that
1416
-   the script processing does not continue.
1406
+   the async query. Before calling t_suspend(), register for the following
1407
+   callbacks, and pass the pointer to the allocated shared memory as a
1408
+   parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN (in
1409
+   case of INVITE transaction). The async operation can be cancelled, if
1410
+   it is still pending, when TMCB_ON_FAILURE or TMCB_E2ECANCEL_IN is
1411
+   called. TMCB_DESTROY is suitable to free the shared memory allocated
1412
+   for the async and SIP transaction identifiers. Once the async query
1413
+   result is available call t_continue(), see below. The SIP transaction
1414
+   must exist before calling t_suspend(), and the module function calling
1415
+   t_suspend() should return 0 to make sure that the script processing
1416
+   does not continue.
1417 1417
 
1418 1418
 1.5.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
1419 1419
 action *route)
... ...
@@ -90,6 +90,7 @@ struct cfg_group_tm	default_tm_cfg = {
90 90
 			 * for every method except BYE by default */
91 91
 	1,	/* cancel_b_method used for e2e and 6xx cancels*/
92 92
 	1,	/* reparse_on_dns_failover */
93
+	INV_FR_TIME_OUT_NEXT
93 94
 };
94 95
 
95 96
 void	*tm_cfg = &default_tm_cfg;
... ...
@@ -179,5 +180,7 @@ cfg_def_t	tm_cfg_def[] = {
179 179
 		"if set to 1, the SIP message after a DNS failover is "
180 180
 		"constructed from the outgoing message buffer of the failed "
181 181
 		"branch instead of from the received request"},
182
+	{"fr_inv_timer_next",	CFG_VAR_INT,	0, 0, timer_fixup, 0,
183
+		"The value of fr_inv_timer for subsequent branches during serial forking"},
182 184
 	{0, 0, 0, 0, 0, 0}
183 185
 };
... ...
@@ -52,6 +52,10 @@
52 52
 #define FR_TIME_OUT        30000 /* ms */
53 53
 #define INV_FR_TIME_OUT   120000 /* ms */
54 54
 
55
+/*! \brief final response timers to be used for serial forwarding */
56
+#define INV_FR_TIME_OUT_FIRST 90000 /* ms */
57
+#define INV_FR_TIME_OUT_NEXT  30000 /* ms */
58
+
55 59
 /* WAIT timer ... tells how long state should persist in memory after
56 60
    a transaction was finalized*/
57 61
 #define WT_TIME_OUT       5000 /* ms */
... ...
@@ -129,6 +133,7 @@ struct cfg_group_tm {
129 129
 	unsigned int	tm_blst_methods_lookup;
130 130
 	unsigned int	cancel_b_flags;
131 131
 	int	reparse_on_dns_failover;
132
+	unsigned int fr_inv_timeout_next;
132 133
 };
133 134
 
134 135
 extern struct cfg_group_tm	default_tm_cfg;
... ...
@@ -1025,4 +1025,83 @@ failure_route[1] {
1025 1025
 	    </programlisting>
1026 1026
 	</example>
1027 1027
     </section>
1028
+
1029
+	<section>
1030
+		<title>
1031
+		<function moreinfo="none">t_load_contacts()</function>
1032
+		</title>
1033
+		<para>
1034
+                Loads contacts in destination set in increasing qvalue order as
1035
+                values of contacts_avp. If all contacts in the destination set
1036
+                have the same qvalue, t_load_contacts() does not do
1037
+                anything thus 
1038
+                minimizing performance impact of serial forking capability
1039
+                when it is not needed. Returns 1 if loading of contacts
1040
+                succeeded or there was nothing to do. Returns -1 on error (see
1041
+                syslog).
1042
+		</para>
1043
+		<para>
1044
+		This function can be used from REQUEST_ROUTE.
1045
+		</para>
1046
+		<example>
1047
+		<title><function>t_load_contacts</function> usage</title>
1048
+		<programlisting format="linespecific">
1049
+...
1050
+if (!t_load_contacts()) {
1051
+        sl_send_reply("500", "Server Internal Error - Cannot load contacts");
1052
+        exit;
1053
+};
1054
+...
1055
+</programlisting>
1056
+		</example>
1057
+	</section>
1058
+
1059
+	<section>
1060
+		<title>
1061
+		<function moreinfo="none">t_next_contacts()</function>
1062
+		</title>
1063
+		<para>
1064
+                If transaction does not exist when t_next_contacts() is
1065
+                called, replaces Request-URI with the
1066
+                first contacts_avp value, adds the remaining contacts_avp values
1067
+                with the same qvalue as branches, and destroys those AVPs. It
1068
+                does nothing if there are no contacts_avp values. Returns 1 if
1069
+                there were no errors and -1 if an error occurred (see syslog).
1070
+		</para>
1071
+                <para>
1072
+                If transaction does exist when t_next_contacts() is
1073
+                called, adds the first contacts_avp value and all
1074
+                following contacts_avp values with the 
1075
+                same qvalue as new branches to request and destroys those AVPs.
1076
+                Returns 1 if new branches were successfully added and -1 on
1077
+                error (see syslog) or if there were no more contacts_avp
1078
+                values.
1079
+                </para>
1080
+		<para>
1081
+		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
1082
+		</para>
1083
+		<example>
1084
+		<title><function>t_next_contacts</function> usage</title>
1085
+		<programlisting format="linespecific">
1086
+...
1087
+# First call after t_load_contacts() when transaction does not exist yet
1088
+# and contacts should be available
1089
+if (!t_next_contacts()) {
1090
+        sl_send_reply("500", "Server Internal Error - Cannot get contacts");
1091
+} else {
1092
+        t_relay();
1093
+};
1094
+...
1095
+# Following call, when transaction exists and there may or may not be
1096
+# contacts left
1097
+if (!t_next_contacts()) {
1098
+        t_reply("408", "Request Timeout");
1099
+} else {
1100
+        t_relay();
1101
+};
1102
+...
1103
+</programlisting>
1104
+		</example>
1105
+	</section>
1106
+
1028 1107
 </section>
... ...
@@ -743,4 +743,55 @@ onreply_route["stateless_replies"] {
743 743
 	</example>
744 744
     </section>
745 745
 
746
+	<section>
747
+		<title><varname>fr_inv_timer_next</varname> (integer)</title>
748
+		<para>
749
+                Value of the Final Response timeout for INVITE
750
+                transactions to be used during serial forwarding:
751
+		</para>
752
+		<para>
753
+                Function t_next_contacts() sets fr_inv_timer to
754
+                fr_inv_timer_next value if, after t_next_contacts() is
755
+                called, there are still lower qvalue contacts available,
756
+                and to fr_inv_timer value if there are not.
757
+		</para>
758
+		<para>
759
+		<emphasis>
760
+			Default value is 30.
761
+		</emphasis>
762
+		</para>
763
+		<example>
764
+		<title>Set <varname>fr_inv_timer_next</varname> parameter</title>
765
+		<programlisting format="linespecific">
766
+...
767
+modparam("tm", "fr_inv_timer_next", 10)
768
+...
769
+</programlisting>
770
+		</example>
771
+	</section>
772
+
773
+	<section>
774
+		<title><varname>contacts_avp</varname> (string)</title>
775
+		<para>
776
+                Internal AVP that t_load_contacts() function uses to store
777
+                contacts of the destination set and that
778
+                t_next_contacts() function uses to restore those contacts.
779
+		</para>
780
+		<para>
781
+		<emphasis>
782
+			Default value is "NULL"
783
+			(t_load_contacts()/t_next_contacts() functions
784
+			are disabled).
785
+		</emphasis>
786
+		</para>
787
+		<example>
788
+		<title>Set <varname>contacts_avp</varname> parameter</title>
789
+		<programlisting format="linespecific">
790
+...
791
+modparam("tm", "contacts_avp", "$avp(i:25)")
792
+...
793
+</programlisting>
794
+		</example>
795
+	</section>
796
+
746 797
 </section>
... ...
@@ -13,11 +13,20 @@
13 13
 		    <email>jiri@iptel.org</email>
14 14
 		</address>
15 15
 	    </author>
16
+		<author>
17
+		<firstname>Juha</firstname>
18
+		<surname>Heinanen</surname>
19
+	        <email>jh@tutpro.com</email>
20
+		</author>
16 21
 	</authorgroup>
17 22
 	<copyright>
18 23
 	    <year>2003</year>
19 24
 	    <holder>FhG FOKUS</holder>
20 25
 	</copyright>
26
+	<copyright>
27
+		<year>2008</year>
28
+		<holder>Juha Heinanen</holder>
29
+	</copyright>
21 30
 	<revhistory>
22 31
 	    <revision>
23 32
 		<revnumber>$Revision$</revnumber>
... ...
@@ -60,6 +60,7 @@
60 60
 #include "config.h"