Browse code

t_suspend() and t_continue() functions have been documented.

Miklos Tirpak authored on 05/12/2008 13:59:35
Showing 3 changed files
... ...
@@ -1,3 +1,4 @@
1
+
1 2
 1. TM Module
2 3
 
3 4
 Jiri Kuthan
... ...
@@ -7,7 +8,7 @@ Jiri Kuthan
7 8
    Copyright � 2003 FhG FOKUS
8 9
    Revision History
9 10
    Revision $Revision$ $Date$
10
-     __________________________________________________________________
11
+     _________________________________________________________________
11 12
 
12 13
    1.1. Overview
13 14
    1.2. Known Issues
... ...
@@ -43,89 +44,94 @@ Jiri Kuthan
43 44
         1.4.1. t_relay_to_udp(ip, port), t_relay_to_udp(),
44 45
                 t_relay_to_tcp(ip, port) t_relay_to_tcp()
45 46
                 t_relay_to_tls(ip, port) t_relay_to_tls()
46
-                t_relay_to_sctp(ip, port) t_relay_to_sctp()
47
-
48
-        1.4.2. t_relay() t_relay(host, port)
49
-        1.4.3. t_on_failure(failure_route)
50
-        1.4.4. t_on_reply(onreply_route)
51
-        1.4.5. t_on_branch(branch_route)
52
-        1.4.6. append_branch()
53
-        1.4.7. t_newtran()
54
-        1.4.8. t_reply(code, reason_phrase)
55
-        1.4.9. t_lookup_request()
56
-        1.4.10. t_retransmit_reply()
57
-        1.4.11. t_release()
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() 
58 59
         1.4.12. t_forward_nonack() t_forward_nonack(ip, port)
59 60
                 t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip,
60 61
                 port) t_forward_nonack_tls(ip, port)
61
-                t_forward_nonack_sctp(ip, port)
62
-
63
-        1.4.13. t_set_fr(fr_inv_timeout [, fr_timeout])
64
-        1.4.14. t_reset_fr()
65
-        1.4.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
66
-        1.4.16. t_reset_max_lifetime()
67
-        1.4.17. t_set_retr(retr_t1_interval, retr_t2_interval)
68
-        1.4.18. t_reset_retr()
69
-        1.4.19. t_set_auto_inv_100(0|1)
70
-        1.4.20. t_branch_timeout()
71
-        1.4.21. t_branch_replied()
72
-        1.4.22. t_any_timeout()
73
-        1.4.23. t_any_replied()
74
-        1.4.24. t_grep_status("code")
75
-        1.4.25. t_is_canceled()
76
-        1.4.26. t_relay_cancel()
77
-        1.4.27. t_drop_replies()
78
-        1.4.28. t_save_lumps()
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_relay_cancel() 
78
+        1.4.27. t_drop_replies() 
79
+        1.4.28. t_save_lumps() 
79 80
 
80 81
    1.5. TM Module API
81 82
 
82 83
         1.5.1. Defines
83 84
         1.5.2. Functions
84 85
 
85
-              1.5.2.1. register_tmcb(cb_type, cb_func)
86
-              1.5.2.2. load_tm(*import_structure)
86
+              1.5.2.1. register_tmcb(cb_type, cb_func) 
87
+              1.5.2.2. load_tm(*import_structure) 
88
+              1.5.2.3. int t_suspend(struct sip_msg *msg, unsigned int
89
+                      *hash_index, unsigned int *label) 
90
+
91
+              1.5.2.4. int t_continue(unsigned int hash_index, unsigned
92
+                      int label, struct action *route) 
87 93
 
88 94
 1.1. Overview
89 95
 
90
-   TM module enables stateful processing of SIP transactions. The main use
91
-   of stateful logic, which is costly in terms of memory and CPU, is some
92
-   services inherently need state. For example, transaction-based
96
+   TM module enables stateful processing of SIP transactions. The main
97
+   use of stateful logic, which is costly in terms of memory and CPU, is
98
+   some services inherently need state. For example, transaction-based
93 99
    accounting (module acc) needs to process transaction state as opposed
94 100
    to individual messages, and any kinds of forking must be implemented
95 101
    statefully. Other use of stateful processing is it trading CPU caused
96 102
    by retransmission processing for memory. That makes however only sense
97 103
    if CPU consumption per request is huge. For example, if you want to
98
-   avoid costly DNS resolution for every retransmission of a request to an
99
-   unresolvable destination, use stateful mode. Then, only the initial
104
+   avoid costly DNS resolution for every retransmission of a request to
105
+   an unresolvable destination, use stateful mode. Then, only the initial
100 106
    message burdens server by DNS queries, subsequent retransmissions will
101 107
    be dropped and will not result in more processes blocked by DNS
102 108
    resolution. The price is more memory consumption and higher processing
103 109
    latency.
104 110
 
105 111
    From user's perspective, there are these major functions : t_relay,
106
-   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction state,
107
-   absorb retransmissions from upstream, generate downstream
112
+   t_relay_to_udp and t_relay_to_tcp. All of them setup transaction
113
+   state, absorb retransmissions from upstream, generate downstream
108 114
    retransmissions and correlate replies to requests. t_relay forwards to
109 115
    current URI (be it original request's URI or a URI changed by some of
110 116
    URI-modifying functions, such as sethost). t_relay_to_udp and
111 117
    t_relay_to_tcp forward to a specific address over UDP or TCP
112 118
    respectively.
113 119
 
114
-   In general, if TM is used, it copies clones of received SIP messages in
115
-   shared memory. That costs the memory and also CPU time (memcpys,
116
-   lookups, shmem locks, etc.) Note that non-TM functions operate over the
117
-   received message in private memory, that means that any core operations
118
-   will have no effect on statefully processed messages after creating the
119
-   transactional state. For example, calling record_route after t_relay is
120
-   pretty useless, as the RR is added to privately held message whereas
121
-   its TM clone is being forwarded.
120
+   In general, if TM is used, it copies clones of received SIP messages
121
+   in shared memory. That costs the memory and also CPU time (memcpys,
122
+   lookups, shmem locks, etc.) Note that non-TM functions operate over
123
+   the received message in private memory, that means that any core
124
+   operations will have no effect on statefully processed messages after
125
+   creating the transactional state. For example, calling record_route
126
+   after t_relay is pretty useless, as the RR is added to privately held
127
+   message whereas its TM clone is being forwarded.
122 128
 
123 129
    TM is quite big and uneasy to program--lot of mutexes, shared memory
124
-   access, malloc and free, timers--you really need to be careful when you
125
-   do anything. To simplify TM programming, there is the instrument of
126
-   callbacks. The callback mechanisms allow programmers to register their
127
-   functions to specific event. See t_hooks.h for a list of possible
128
-   events.
130
+   access, malloc and free, timers--you really need to be careful when
131
+   you do anything. To simplify TM programming, there is the instrument
132
+   of callbacks. The callback mechanisms allow programmers to register
133
+   their functions to specific event. See t_hooks.h for a list of
134
+   possible events.
129 135
 
130 136
    Other things programmers may want to know is UAC--it is a very
131 137
    simplistic code which allows you to generate your own transactions.
... ...
@@ -136,16 +142,16 @@ Jiri Kuthan
136 142
 
137 143
 1.2. Known Issues
138 144
 
139
-     * Possibly, performance could be improved by not parsing non-INVITEs,
140
-       as they do not be replied with 100, and do not result in
141
-       ACK/CANCELs, and other things which take parsing. However, we need
142
-       to rethink whether we don't need parsed headers later for something
143
-       else. Remember, when we now conserver a request in sh_mem, we can't
144
-       apply any pkg_mem operations to it any more. (that might be
145
-       redesigned too).
146
-     * Another performance improvement may be achieved by not parsing CSeq
147
-       in replies until reply branch matches branch of an INVITE/CANCEL in
148
-       transaction table.
145
+     * Possibly, performance could be improved by not parsing
146
+       non-INVITEs, as they do not be replied with 100, and do not result
147
+       in ACK/CANCELs, and other things which take parsing. However, we
148
+       need to rethink whether we don't need parsed headers later for
149
+       something else. Remember, when we now conserver a request in
150
+       sh_mem, we can't apply any pkg_mem operations to it any more.
151
+       (that might be redesigned too).
152
+     * Another performance improvement may be achieved by not parsing
153
+       CSeq in replies until reply branch matches branch of an
154
+       INVITE/CANCEL in transaction table.
149 155
      * t_replicate should be done more cleanly--Vias, Routes, etc. should
150 156
        be removed from a message prior to replicating it (well, does not
151 157
        matter any longer so much as there is a new replication module).
... ...
@@ -207,8 +213,8 @@ modparam("tm", "fr_inv_timer", 180000)
207 213
    fr_inv_timer will still be restarted for each increasing reply (e.g.
208 214
    180, 181, 182, ...). Another example when a transaction can live
209 215
    substantially more then its fr_inv_timer and where max_inv_lifetime
210
-   will help is when dns failover is used (each failed dns destination can
211
-   introduce a new branch).
216
+   will help is when dns failover is used (each failed dns destination
217
+   can introduce a new branch).
212 218
 
213 219
    The default value is 180000 ms (180 seconds - the rfc3261 timer C
214 220
    value).
... ...
@@ -241,7 +247,8 @@ modparam("tm", "max_inv_lifetime", 150000)
241 247
    failover is used (each failed dns destination can introduce a new
242 248
    branch).
243 249
 
244
-   The default value is 32000 ms (32 seconds - the rfc3261 timer F value).
250
+   The default value is 32000 ms (32 seconds - the rfc3261 timer F
251
+   value).
245 252
 
246 253
    See also: max_inv_lifetime, t_set_max_lifetime() (allows changing
247 254
    max_noninv_lifetime on a per transaction basis), t_reset_max_lifetime
... ...
@@ -254,11 +261,11 @@ modparam("tm", "max_inv_lifetime", 30000)
254 261
 
255 262
 1.3.5. wt_timer (integer)
256 263
 
257
-   Time for which a transaction stays in memory to absorb delayed messages
258
-   after it completed (in milliseconds); also, when this timer hits,
259
-   retransmission of local cancels is stopped (a puristic but complex
260
-   behavior would be not to enter wait state until local branches are
261
-   finished by a final reply or FR timer--we simplified).
264
+   Time for which a transaction stays in memory to absorb delayed
265
+   messages after it completed (in milliseconds); also, when this timer
266
+   hits, retransmission of local cancels is stopped (a puristic but
267
+   complex behavior would be not to enter wait state until local branches
268
+   are finished by a final reply or FR timer--we simplified).
262 269
 
263 270
    Default value is 5000 ms (5 seconds).
264 271
 
... ...
@@ -272,8 +279,8 @@ modparam("tm", "wt_timer", 1000)
272 279
    Time after which a to-be-deleted transaction currently ref-ed by a
273 280
    process will be tried to be deleted again (in milliseconds).
274 281
 
275
-   Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction is
276
-   deleted the moment it's not referenced anymore).
282
+   Note: this parameter is obsolete for ser 2.1 (in 2.1 the transaction
283
+   is deleted the moment it's not referenced anymore).
277 284
 
278 285
    Default value is 200 milliseconds.
279 286
 
... ...
@@ -308,15 +315,16 @@ modparam("tm", "retr_timer2", 2000)
308 315
 
309 316
 1.3.9. noisy_ctimer (integer)
310 317
 
311
-   If set, INVITE transactions that time-out (FR INV timer) will be always
312
-   replied. If it's not set, the transaction has only one branch and no
313
-   response was ever received on this branch, it will be silently dropped
314
-   (no 408 reply will be generated) This behavior is overridden if a
315
-   request is forked, the transaction has a failure route or callback, or
316
-   some functionality explicitly turned it on for a transaction (like acc
317
-   does to avoid unaccounted transactions due to expired timer). Turn this
318
-   off only if you know the client UACs will timeout and their timeout
319
-   interval for INVITEs is lower or equal than tm's fr_inv_timer.
318
+   If set, INVITE transactions that time-out (FR INV timer) will be
319
+   always replied. If it's not set, the transaction has only one branch
320
+   and no response was ever received on this branch, it will be silently
321
+   dropped (no 408 reply will be generated) This behavior is overridden
322
+   if a request is forked, the transaction has a failure route or
323
+   callback, or some functionality explicitly turned it on for a
324
+   transaction (like acc does to avoid unaccounted transactions due to
325
+   expired timer). Turn this off only if you know the client UACs will
326
+   timeout and their timeout interval for INVITEs is lower or equal than
327
+   tm's fr_inv_timer.
320 328
 
321 329
    Default value is 1 (on).
322 330
 
... ...
@@ -329,9 +337,9 @@ modparam("tm", "noisy_ctimer", 1)
329 337
 
330 338
    If set (default), the fr_inv_timer for an INVITE transaction will be
331 339
    restarted for each provisional reply received (rfc3261 mandated
332
-   behaviour). If not set, the fr_inv_timer will be restarted only for the
333
-   first provisional replies and for increasing replies greater or equal
334
-   180 (e.g. 180, 181, 182, 185, ...).
340
+   behaviour). If not set, the fr_inv_timer will be restarted only for
341
+   the first provisional replies and for increasing replies greater or
342
+   equal 180 (e.g. 180, 181, 182, 185, ...).
335 343
 
336 344
    Setting it to 0 is especially useful when dealing with bad UAs that
337 345
    continuously retransmit 180s, not allowing the transaction to timeout
... ...
@@ -354,8 +362,8 @@ modparam("tm", "restart_fr_on_each_reply", 0)
354 362
    Setting it to 0 one can be used to enable doing first some tests or
355 363
    pre-processing on the INVITE and only if some conditions are met
356 364
    manually send a 100 (using t_reply()). Note however that in this case
357
-   all the 100s have to be sent "by hand". t_set_auto_inv_100() might help
358
-   to selectively turn off this feature only for some specific
365
+   all the 100s have to be sent "by hand". t_set_auto_inv_100() might
366
+   help to selectively turn off this feature only for some specific
359 367
    transactions.
360 368
 
361 369
    Default value is 1 (on).
... ...
@@ -371,8 +379,8 @@ modparam("tm", "auto_inv_100", 0)
371 379
 
372 380
    Unix socket transmission timeout, in milliseconds.
373 381
 
374
-   If unix sockets are used (e.g.: to communicate with sems) and sending a
375
-   message on a unix socket takes longer then unix_tx_timeout, the send
382
+   If unix sockets are used (e.g.: to communicate with sems) and sending
383
+   a message on a unix socket takes longer then unix_tx_timeout, the send
376 384
    will fail.
377 385
 
378 386
    The default value is 500 milliseconds.
... ...
@@ -389,8 +397,8 @@ modparam("tm", "unix_tx_timeout", 250)
389 397
    Proxy-Authenticate headers from all the 401 and 407 replies will be
390 398
    aggregated in a new final reply. If only one branch received the
391 399
    winning 401 or 407 then this reply will be forwarded (no new one will
392
-   be built). If 0 only the first 401, or if no 401 was received the first
393
-   407, will be forwarded (no header aggregation).
400
+   be built). If 0 only the first 401, or if no 401 was received the
401
+   first 407, will be forwarded (no header aggregation).
394 402
 
395 403
    Default value is 1 (required by rfc3261).
396 404
 
... ...
@@ -403,15 +411,15 @@ modparam("tm", "aggregate_challenges", 0)
403 411
 
404 412
    If set (default), the CANCEL and negative ACK requests are constructed
405 413
    from the INVITE message which was sent out instead of building them
406
-   from the received request. The disadvantage is that the outgoing INVITE
407
-   has to be partially re-parsed, the advantage is that the CANCEL/ACK is
408
-   always RFC 3261-compliant, it always contains the same route-set as the
409
-   INVITE message. Do not disable the INVITE re-parsing for example in the
410
-   following cases:
414
+   from the received request. The disadvantage is that the outgoing
415
+   INVITE has to be partially re-parsed, the advantage is that the
416
+   CANCEL/ACK is always RFC 3261-compliant, it always contains the same
417
+   route-set as the INVITE message. Do not disable the INVITE re-parsing
418
+   for example in the following cases:
411 419
 
412 420
    - The INVITE contains a preloaded route-set, and SER forwards the
413
-   message to the next hop according to the Route header. The Route header
414
-   is not removed in the CANCEL without reparse_invite=1.
421
+   message to the next hop according to the Route header. The Route
422
+   header is not removed in the CANCEL without reparse_invite=1.
415 423
 
416 424
    - SER record-routes, thus an in-dialog INVITE contains a Route header
417 425
    which is removed during loose routing. If the in-dialog INVITE is
... ...
@@ -431,8 +439,8 @@ modparam("tm", "reparse_invite", 0)
431 439
    CANCEL and negative ACK messages if they were present in the outgoing
432 440
    INVITE.
433 441
 
434
-   Note, that the parameter value effects only those headers which are not
435
-   covered by RFC-3261 (which are neither mandatory nor prohibited in
442
+   Note, that the parameter value effects only those headers which are
443
+   not covered by RFC-3261 (which are neither mandatory nor prohibited in
436 444
    CANCEL and ACK), and the parameter can be used only together with
437 445
    reparse_invite=1.
438 446
 
... ...
@@ -448,8 +456,8 @@ modparam("tm", "ac_extra_hdrs", "myfavoriteheaders-")
448 456
    If set and the blacklist support is enabled, every 503 reply source is
449 457
    added to the blacklist. The initial blacklist timeout (or ttl) depends
450 458
    on the presence of a Retry-After header in the reply and the values of
451
-   the following tm parameters: blst_503_def_timeout, blst_503_min_timeout
452
-   and blst_503_max_timeout.
459
+   the following tm parameters: blst_503_def_timeout,
460
+   blst_503_min_timeout and blst_503_max_timeout.
453 461
 
454 462
    WARNING:blindly allowing 503 blacklisting could be very easily
455 463
    exploited for DOS attacks in most network setups.
... ...
@@ -550,8 +558,8 @@ modparam("tm", "blst_methods_lookup", 1)
550 558
    values are 0, 1, and 2.
551 559
 
552 560
    0 will immediately stop the request (INVITE) retransmission on the
553
-   branch and it will behave as if the branch was immediately replied with
554
-   a 487 (a fake internal 487 reply). The advantage is the unreplied
561
+   branch and it will behave as if the branch was immediately replied
562
+   with a 487 (a fake internal 487 reply). The advantage is the unreplied
555 563
    branches will be terminated immediately. However it introduces a race
556 564
    risk with a possible slightly delayed 2xx reply. In this case we could
557 565
    have an UA receiving a 2xx after a 487. Moreover this risk is greatly
... ...
@@ -563,16 +571,16 @@ modparam("tm", "blst_methods_lookup", 1)
563 571
    1 will keep retransmitting the request on unreplied branches. If a
564 572
    provisional answer is later received a CANCEL will be immediately sent
565 573
    back (attempting to quickly trigger a 487). This approach is race free
566
-   and avoids the 2xx after 487 problem, but it's more resource intensive:
567
-   faced with a branch towards and UA that doesn't answer, a CANCEL
568
-   attempt will keep the transaction alive for the whole timeout interval
569
-   (fr_timer).
574
+   and avoids the 2xx after 487 problem, but it's more resource
575
+   intensive: faced with a branch towards and UA that doesn't answer, a
576
+   CANCEL attempt will keep the transaction alive for the whole timeout
577
+   interval (fr_timer).
570 578
 
571 579
    2 will send and retransmit CANCEL even on unreplied branches, stopping
572
-   the request retransmissions. This has the same advantages as 1 and also
573
-   avoids the extra roundtrip in the case of the provisional reply, but
574
-   it's not RFC 3261 conforming (the RFC allows sending CANCELs only on
575
-   pending branches).
580
+   the request retransmissions. This has the same advantages as 1 and
581
+   also avoids the extra roundtrip in the case of the provisional reply,
582
+   but it's not RFC 3261 conforming (the RFC allows sending CANCELs only
583
+   on pending branches).
576 584
 
577 585
    The default value is 1.
578 586
 
... ...
@@ -595,11 +603,11 @@ modparam("tm", "cancel_b_method", 1)
595 603
    Note: If the parameter is set, branch route block and
596 604
    TMCB_REQUEST_FWDED callback are not called in case of the failover.
597 605
 
598
-   Disadvantage: only the via header is replaced in the message buffer, so
599
-   the outgoing socket address is not corrected in any other part of the
600
-   message. It is dangerous on multihomed hosts: when the new SIP request
601
-   after the DNS failover is sent via different interface than the first
602
-   request, the message can contain incorrect ip address in the
606
+   Disadvantage: only the via header is replaced in the message buffer,
607
+   so the outgoing socket address is not corrected in any other part of
608
+   the message. It is dangerous on multihomed hosts: when the new SIP
609
+   request after the DNS failover is sent via different interface than
610
+   the first request, the message can contain incorrect ip address in the
603 611
    Record-Route header for instance.
604 612
 
605 613
    Default value is 1.
... ...
@@ -612,9 +620,9 @@ modparam("tm", "reparse_on_dns_failover", 0)
612 620
 1.3.24. on_sl_reply (string)
613 621
 
614 622
    Sets reply route block, to which control is passed when a reply is
615
-   received that has no associated transaction. The reply is passed to the
616
-   core for stateless forwarding after the route block execution unless it
617
-   returns 0.
623
+   received that has no associated transaction. The reply is passed to
624
+   the core for stateless forwarding after the route block execution
625
+   unless it returns 0.
618 626
 
619 627
    Example 24. Set on_sl_reply parameter
620 628
 ...
... ...
@@ -648,8 +656,8 @@ t_relay_to_sctp(ip, port) t_relay_to_sctp()
648 656
      * port - Port number.
649 657
 
650 658
    If no parameters are specified the message is sent to a destination
651
-   derived from the message uri (using sip sepcific DNS lookups), but with
652
-   the protocol corresponding to the function name.
659
+   derived from the message uri (using sip sepcific DNS lookups), but
660
+   with the protocol corresponding to the function name.
653 661
 
654 662
    Example 25. t_relay_to_udp usage
655 663
 ...
... ...
@@ -662,21 +670,22 @@ else
662 670
 1.4.2.  t_relay() t_relay(host, port)
663 671
 
664 672
    Relay a message statefully either to the destination indicated in the
665
-   current URI (if called without any parameters) or to the specified host
666
-   and port. In the later case (host and port specified) the protocol used
667
-   is the same protocol on which the message was received.
673
+   current URI (if called without any parameters) or to the specified
674
+   host and port. In the later case (host and port specified) the
675
+   protocol used is the same protocol on which the message was received.
668 676
 
669 677
    t_relay() is the statefull version for forward(uri:host, uri:port)
670 678
    while t_relay(host, port) is similar to forward(host, port).
671 679
 
672 680
    In the forward to uri case (t_relay()), if the original URI was
673 681
    rewritten (by UsrLoc, RR, strip/prefix, etc.) the new URI will be
674
-   taken). The destination (including the protocol) is determined from the
675
-   uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
682
+   taken). The destination (including the protocol) is determined from
683
+   the uri, using SIP specific DNS resolving if needed (NAPTR, SRV a.s.o
676 684
    depending also on the dns options).
677 685
 
678 686
    Returns a negative value on failure--you may still want to send a
679
-   negative reply upstream statelessly not to leave upstream UAC in lurch.
687
+   negative reply upstream statelessly not to leave upstream UAC in
688
+   lurch.
680 689
 
681 690
    Example 26. t_relay usage
682 691
 ...
... ...
@@ -690,19 +699,19 @@ if (!t_relay())
690 699
 1.4.3.  t_on_failure(failure_route)
691 700
 
692 701
    Sets failure routing block, to which control is passed after a
693
-   transaction completed with a negative result but before sending a final
694
-   reply. In the referred block, you can either start a new branch (good
695
-   for services such as forward_on_no_reply) or send a final reply on your
696
-   own (good for example for message silo, which received a negative reply
697
-   from upstream and wants to tell upstream "202 I will take care of it").
698
-   Note that the set of commands which are usable within failure_routes is
699
-   strictly limited to rewriting URI, initiating new branches, logging,
700
-   and sending stateful replies (t_reply). Any other commands may result
701
-   in unpredictable behavior and possible server failure. Note that
702
-   whenever failure_route is entered, uri is reset to value which it had
703
-   on relaying. If it temporarily changed during a reply_route processing,
704
-   subsequent reply_route will ignore the changed value and use again the
705
-   original one.
702
+   transaction completed with a negative result but before sending a
703
+   final reply. In the referred block, you can either start a new branch
704
+   (good for services such as forward_on_no_reply) or send a final reply
705
+   on your own (good for example for message silo, which received a
706
+   negative reply from upstream and wants to tell upstream "202 I will
707
+   take care of it"). Note that the set of commands which are usable
708
+   within failure_routes is strictly limited to rewriting URI, initiating
709
+   new branches, logging, and sending stateful replies (t_reply). Any
710
+   other commands may result in unpredictable behavior and possible
711
+   server failure. Note that whenever failure_route is entered, uri is
712
+   reset to value which it had on relaying. If it temporarily changed
713
+   during a reply_route processing, subsequent reply_route will ignore
714
+   the changed value and use again the original one.
706 715
 
707 716
    Meaning of the parameters is as follows:
708 717
      * failure_route - Failure route block to be called.
... ...
@@ -746,8 +755,8 @@ route {
746 755
 onreply_route[1] {
747 756
         if (status=~ "(183)|2[0-9][0-9]"){
748 757
                 force_rtp_proxy();
749
-                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=y
750
-es');
758
+                search_append('^(Contact|m)[ \t]*:.*sip:[^>[:cntrl:]]*', ';nat=
759
+yes');
751 760
         }
752 761
         if (nat_uac_test("1")){
753 762
                 fix_nated_contact();
... ...
@@ -756,11 +765,12 @@ es');
756 765
 
757 766
 1.4.5.  t_on_branch(branch_route)
758 767
 
759
-   Sets the branch routing block, to which control is passed after forking
760
-   (when a new branch is created). For now branch routes are intended only
761
-   for last minute changes of the SIP messages (like adding new headers).
762
-   Note that the set of commands which are usable within branch_routes is
763
-   very limited. It is not possible to drop a message or generate a reply.
768
+   Sets the branch routing block, to which control is passed after
769
+   forking (when a new branch is created). For now branch routes are
770
+   intended only for last minute changes of the SIP messages (like adding
771
+   new headers). Note that the set of commands which are usable within
772
+   branch_routes is very limited. It is not possible to drop a message or
773
+   generate a reply.
764 774
 
765 775
    Meaning of the parameters is as follows:
766 776
      * branch_route - branch route block to be called.
... ...
@@ -848,8 +858,8 @@ t_retransmit_reply();
848 858
 
849 859
 1.4.11.  t_release()
850 860
 
851
-   Remove transaction from memory (it will be first put on a wait timer to
852
-   absorb delayed messages).
861
+   Remove transaction from memory (it will be first put on a wait timer
862
+   to absorb delayed messages).
853 863
 
854 864
    Example 35. t_release usage
855 865
 ...
... ...
@@ -907,9 +917,9 @@ branch_route[1] {
907 917
 
908 918
 1.4.14.  t_reset_fr()
909 919
 
910
-   Resets the fr_inv_timer and fr_timer for the current transaction to the
911
-   default values (set using the tm module parameters fr_inv_timer and
912
-   fr_timer).
920
+   Resets the fr_inv_timer and fr_timer for the current transaction to
921
+   the default values (set using the tm module parameters fr_inv_timer
922
+   and fr_timer).
913 923
 
914 924
    It will effectively cancel any previous calls to t_set_fr for the same
915 925
    transaction.
... ...
@@ -928,9 +938,9 @@ route {
928 938
 
929 939
    Sets the maximum lifetime for the current INVITE or non-INVITE
930 940
    transaction, or for transactions created during the same script
931
-   invocation, after calling this function (that's why it takes values for
932
-   both INVITE and non-INVITE). If one of the parameters is 0, its value
933
-   won't be changed.
941
+   invocation, after calling this function (that's why it takes values
942
+   for both INVITE and non-INVITE). If one of the parameters is 0, its
943
+   value won't be changed.
934 944
 
935 945
    It works as a per transaction max_inv_lifetime or max_noninv_lifetime.
936 946
 
... ...
@@ -959,8 +969,8 @@ route {
959 969
    transaction to the default value (set using the tm module parameter
960 970
    max_inv_lifetime or max_noninv_lifetime).
961 971
 
962
-   It will effectively cancel any previous calls to t_set_max_lifetime for
963
-   the same transaction.
972
+   It will effectively cancel any previous calls to t_set_max_lifetime
973
+   for the same transaction.
964 974
 
965 975
    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
966 976
 
... ...
@@ -976,9 +986,9 @@ route {
976 986
 
977 987
    Sets the retr_t1_interval and retr_t2_interval for the current
978 988
    transaction or for transactions created during the same script
979
-   invocation, after calling this function. If one of the parameters is 0,
980
-   it's value won't be changed. If the transaction is already created (e.g
981
-   called after t_relay() or in an onreply_route) all the existing
989
+   invocation, after calling this function. If one of the parameters is
990
+   0, it's value won't be changed. If the transaction is already created
991
+   (e.g called after t_relay() or in an onreply_route) all the existing
982 992
    branches will have their retransmissions intervals updated on-the-fly:
983 993
    if the retransmission interval for the branch has not yet reached T2
984 994
    the interval will be reset to retr_t1_interval, else to
... ...
@@ -986,11 +996,11 @@ route {
986 996
    interval expires (after the next retransmission, the next-next
987 997
    retransmission will take place at retr_t1_interval or
988 998
    retr_t2_interval). All new branches of the same transaction will start
989
-   with the new values. This function will work even if it's called in the
990
-   script before a transaction creating function (e.g.: t_set_retr(500,
991
-   4000); t_relay()). All new transaction created after this function
992
-   call, during the same script invocation will use the new values. Note
993
-   that this function will work only if tm is compile with
999
+   with the new values. This function will work even if it's called in
1000
+   the script before a transaction creating function (e.g.:
1001
+   t_set_retr(500, 4000); t_relay()). All new transaction created after
1002
+   this function call, during the same script invocation will use the new
1003
+   values. Note that this function will work only if tm is compile with
994 1004
    -DTM_DIFF_RT_TIMEOUT (which increases every transaction size with 4
995 1005
    bytes).
996 1006
 
... ...
@@ -1146,11 +1156,11 @@ failure_route[0]{
1146 1156
 
1147 1157
 1.4.26.  t_relay_cancel()
1148 1158
 
1149
-   Forwards the CANCEL if the corresponding INVITE transaction exists. The
1150
-   function is supposed to be used at the very beginning of the script,
1151
-   because the CANCELs can be caught and the rest of the script can be
1152
-   bypassed this way. Do not disable reparse_invite module parameter, and
1153
-   call t_relay_cancel() right after the sanity tests.
1159
+   Forwards the CANCEL if the corresponding INVITE transaction exists.
1160
+   The function is supposed to be used at the very beginning of the
1161
+   script, because the CANCELs can be caught and the rest of the script
1162
+   can be bypassed this way. Do not disable reparse_invite module
1163
+   parameter, and call t_relay_cancel() right after the sanity tests.
1154 1164
 
1155 1165
    Return value is 0 (drop) if the corresponding INVITE was found and the
1156 1166
    CANCELs were successfully sent to the pending branches, true if the
... ...
@@ -1284,21 +1294,21 @@ end of body
1284 1294
 1.5.1. Defines
1285 1295
 
1286 1296
      * ACK_TAG enables stricter matching of acknowledgments including
1287
-       to-tags. Without it, to-tags are ignored. It is disabled by default
1288
-       for two reasons:
1297
+       to-tags. Without it, to-tags are ignored. It is disabled by
1298
+       default for two reasons:
1289 1299
           + It eliminates an unlikely race condition in which
1290
-            transaction's to-tag is being rewritten by a 200 OK whereas an
1291
-            ACK is being looked up by to-tag.
1300
+            transaction's to-tag is being rewritten by a 200 OK whereas
1301
+            an ACK is being looked up by to-tag.
1292 1302
           + It makes UACs happy who set wrong to-tags.
1293 1303
        It should not make a difference, as there may be only one negative
1294
-       reply sent upstream and 200/ACKs are not matched as they constitute
1295
-       another transaction. It will make no difference at all when the new
1296
-       magic cookie matching is enabled anyway.
1304
+       reply sent upstream and 200/ACKs are not matched as they
1305
+       constitute another transaction. It will make no difference at all
1306
+       when the new magic cookie matching is enabled anyway.
1297 1307
      * CANCEL_TAG similarly enables strict matching of CANCELs including
1298 1308
        to-tags--act of mercy to UACs, who screw up the to-tags (however,
1299
-       it still depends on how forgiving the downstream UAS is). Like with
1300
-       ACK_TAG, all this complex transactions matching goes with RFC3261's
1301
-       magic cookie away anyway.
1309
+       it still depends on how forgiving the downstream UAS is). Like
1310
+       with ACK_TAG, all this complex transactions matching goes with
1311
+       RFC3261's magic cookie away anyway.
1302 1312
 
1303 1313
 1.5.2. Functions
1304 1314
 
... ...
@@ -1318,3 +1328,57 @@ end of body
1318 1328
 
1319 1329
    Meaning of the parameters is as follows:
1320 1330
      * import_structure - Pointer to the import structure.
1331
+
1332
+1.5.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
1333
+unsigned int *label)
1334
+
1335
+   For programmatic use only. This function together with t_continue()
1336
+   can be used to implement asynchronous actions: t_suspend() saves the
1337
+   transaction, returns its identifiers, and t_continue() continues the
1338
+   SIP request processing. (The request processing does not continue from
1339
+   the same point in the script, a separate route block defined by the
1340
+   parameter of t_continue() is executed instead. The reply lock is held
1341
+   during the route block execution.) FR timer is ticking while the
1342
+   transaction is suspended, and the transaction's failure route is
1343
+   executed if t_continue() is not called in time.
1344
+
1345
+   Missing: message lumps are saved by t_suspend() and are not updated by
1346
+   the subsequent t_relay(). This means that the modifications made
1347
+   between them are lost.
1348
+
1349
+   Meaning of the parameters is as follows:
1350
+     * msg - SIP message pointer.
1351
+     * hash_index - transaction identifier.
1352
+     * label - transaction identifier.
1353
+
1354
+   Return value: 0 - success, <0 - error.
1355
+
1356
+   Usage: Allocate a memory block for storing the transaction identifiers
1357
+   (hash_index and label), and for storing also any variable related to
1358
+   the async query. Before calling t_suspend(), register for the
1359
+   following callbacks, and pass the pointer to the allocated shared
1360
+   memory as a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and
1361
+   TMCB_E2ECANCEL_IN (in case of INVITE transaction). The async operation
1362
+   can be cancelled, if it is still pending, when TMCB_ON_FAILURE or
1363
+   TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free the
1364
+   shared memory allocated for the async and SIP transaction identifiers.
1365
+   Once the async query result is available call t_continue(), see below.
1366
+   The SIP transaction must exist before calling t_suspend(), and the
1367
+   module function calling t_suspend() should return 0 to make sure that
1368
+   the script processing does not continue.
1369
+
1370
+1.5.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
1371
+action *route)
1372
+
1373
+   For programmatic use only. This function is the pair of t_suspend(),
1374
+   and is supposed to be called when the asynchronous query result is
1375
+   available. The function executes a route block with the saved SIP
1376
+   message. It is possible to add more branches to the transaction, or
1377
+   send a reply from the route block.
1378
+
1379
+   Meaning of the parameters is as follows:
1380
+     * hash_index - transaction identifier.
1381
+     * label - transaction identifier.
1382
+     * route - route block to execute.
1383
+
1384
+   Return value: 0 - success, <0 - error.
... ...
@@ -155,6 +155,93 @@ end of body
155 155
 		</listitem>
156 156
 	    </itemizedlist>
157 157
 	</section>
158
+
159
+	<section id="t_suspend">
160
+	    <title>
161
+	    	<function>int t_suspend(struct sip_msg *msg,
162
+			unsigned int *hash_index, unsigned int *label)</function>
163
+	    </title>
164
+	    <para>
165
+	    	For programmatic use only.
166
+		This function together with t_continue() can be used to
167
+		implement asynchronous actions: t_suspend() saves the transaction,
168
+		returns its identifiers, and t_continue() continues the
169
+		SIP request processing. (The request processing does not continue
170
+		from the same point in the script, a separate route block defined
171
+		by the parameter of t_continue() is executed instead. The reply lock
172
+		is held during the route block execution.)
173
+		FR timer is ticking while the transaction is suspended, and the
174
+		transaction's failure route is executed if t_continue() is not
175
+		called in time.
176
+	    </para>
177
+	    <para>
178
+		Missing: message lumps are saved by t_suspend() and are not updated by
179
+		the subsequent t_relay(). This means that the modifications made
180
+		between them are lost.
181
+	    </para>
182
+	    <para>Meaning of the parameters is as follows:</para>
183
+	    <itemizedlist>
184
+		<listitem>
185
+		    <para><emphasis>msg</emphasis> - SIP message pointer.
186
+		    </para>
187
+		</listitem>
188
+		<listitem>
189
+		    <para><emphasis>hash_index</emphasis> - transaction identifier.
190
+		    </para>
191
+		</listitem>
192
+		<listitem>
193
+		    <para><emphasis>label</emphasis> - transaction identifier.
194
+		    </para>
195
+		</listitem>
196
+	    </itemizedlist>
197
+	    <para>Return value: 0 - success, &lt;0 - error.</para>
198
+	    <para>
199
+		Usage: Allocate a memory block for storing the transaction identifiers
200
+		(hash_index and label), and for storing also any variable related to
201
+		the async query. Before calling t_suspend(), register for the following
202
+		callbacks, and pass the pointer to the allocated shared memory as
203
+		a parameter: TMCB_ON_FAILURE, TMCB_DESTROY, and TMCB_E2ECANCEL_IN
204
+		(in case of INVITE transaction). The async operation can be
205
+		cancelled, if it is still pending, when TMCB_ON_FAILURE or
206
+		TMCB_E2ECANCEL_IN is called. TMCB_DESTROY is suitable to free
207
+		the shared memory allocated for the async and SIP transaction identifiers.
208
+		Once the async query result is available call t_continue(), see below.
209
+		The SIP transaction must exist before calling t_suspend(), and the module
210
+		function calling t_suspend() should return 0 to make sure that the script
211
+		processing does not continue.
212
+	    </para>
213
+	</section>
214
+
215
+	<section id="t_continue">
216
+	    <title>
217
+		<function>int t_continue(unsigned int hash_index, unsigned int label,
218
+		                struct action *route)</function>
219
+	    </title>
220
+	    <para>
221
+		For programmatic use only.
222
+		This function is the pair of t_suspend(), and is supposed
223
+		to be called when the asynchronous query result is available.
224
+		The function executes a route block with the saved SIP message.
225
+		It is possible to add more branches to the transaction, or send
226
+		a reply from the route block.
227
+	    </para>
228
+	    <para>Meaning of the parameters is as follows:</para>
229
+	    <itemizedlist>
230
+		<listitem>
231
+		    <para><emphasis>hash_index</emphasis> - transaction identifier.
232
+		    </para>
233
+		</listitem>
234
+		<listitem>
235
+		    <para><emphasis>label</emphasis> - transaction identifier.
236
+		    </para>
237
+		</listitem>
238
+		<listitem>
239
+		    <para><emphasis>route</emphasis> - route block to execute.
240
+		    </para>
241
+		</listitem>
242
+	    </itemizedlist>
243
+	    <para>Return value: 0 - success, &lt;0 - error.</para>
244
+	</section>
158 245
     </section>
159 246
     
160 247
 </section>
... ...
@@ -38,6 +38,14 @@
38 38
 #include "timer.h"
39 39
 #include "t_suspend.h"
40 40
 
41
+/* Suspends the transaction for later use.
42
+ * Save the returned hash_index and label to get
43
+ * back to the SIP request processing, see the readme.
44
+ *
45
+ * Return value:
46
+ * 	0  - success
47
+ * 	<0 - failure
48
+ */
41 49
 int t_suspend(struct sip_msg *msg,
42 50
 		unsigned int *hash_index, unsigned int *label)
43 51
 {
... ...
@@ -85,6 +93,14 @@ int t_suspend(struct sip_msg *msg,
85 93
 	return 0;
86 94
 }
87 95
 
96
+/* Continues the SIP request processing previously saved by
97
+ * t_suspend(). The script does not continue from the same
98
+ * point, but a separate route block is executed instead.
99
+ *
100
+ * Return value:
101
+ * 	0  - success
102
+ * 	<0 - failure
103
+ */
88 104
 int t_continue(unsigned int hash_index, unsigned int label,
89 105
 		struct action *route)
90 106
 {