Browse code

tm: docs: reason header modparams and script function

- docs for:
local_cancel_reason = 0|1
e2e_cancel_reason = 0|1
t_set_no_e2e_cancel_reason(0|1)
- regenerated README

Andrei Pelinescu-Onciul authored on 13/08/2010 10:30:26
Showing 5 changed files
... ...
@@ -38,6 +38,23 @@ modules:
38 38
            blst_rpl_clear_ignore(mask): like blst_rpl_ignore(mask), but
39 39
             clears instead of setting.
40 40
 tm:
41
+   - reason header support (RFC3326) both for CANCELs generated due to a
42
+      received final reply and for hop by hop CANCELs generated because of a
43
+      received CANCEL.
44
+      E.g.: reason header added for a CANCEL generated after a 200 reply was
45
+            received on one of the branches "Reason: SIP;cause=200".
46
+      The reason header support can be turned on/off using either tm
47
+      module parameters or in the end to end CANCEL case also on a per
48
+      transaction basis, using a script function:
49
+       local_cancel_reason = 0 | 1 (default 1/on) - turns on adding reason
50
+         headers for CANCELs generated due to a final reply. Can be changed
51
+         at runtime.
52
+       e2e_cancel_reason = 0 | 1 (default 1/on) - turns on copying reason
53
+         headers from a received end to end CANCEL (the generated hop by hop
54
+         CANCELs will have the same reason headers as the received CANCEL).
55
+         Can be changed at runtime.
56
+       t_set_no_e2e_cancel_reason(0|1) - enable/disable cancel reason 
57
+         header copying on a per transaction basis (0 - enable, 1 disable).
41 58
    - t_reply() can be used both from the main/core onreply_route{} and tm
42 59
      onreply_route[...]{}s.
43 60
 
... ...
@@ -57,6 +57,8 @@ Juha Heinanen
57 57
         1.4.35. default_reason (string)
58 58
         1.4.36. disable_6xx_block (integer)
59 59
         1.4.37. local_ack_mode (integer)
60
+        1.4.38. local_cancel_reason (boolean)
61
+        1.4.39. e2e_cancel_reason (boolean)
60 62
 
61 63
    1.5. Functions
62 64
 
... ...
@@ -105,6 +107,7 @@ Juha Heinanen
105 105
         1.5.35. t_set_disable_failover(0|1)
106 106
         1.5.36. t_replicate(params)
107 107
         1.5.37. t_relay_to(proxy, flags)
108
+        1.5.38. t_set_no_e2e_cancel_reason(0|1)
108 109
 
109 110
    1.6. TM Module API
110 111
 
... ...
@@ -119,6 +122,9 @@ Juha Heinanen
119 119
               1.6.2.4. int t_continue(unsigned int hash_index, unsigned
120 120
                       int label, struct action *route)
121 121
 
122
+              1.6.2.5. int t_cancel_suspend(unsigned int hash_index,
123
+                      unsigned int label)
124
+
122 125
 1.1. Overview
123 126
 
124 127
    TM module enables stateful processing of SIP transactions. The main use
... ...
@@ -1131,12 +1137,48 @@ Note
1131 1131
 modparam("tm", "local_ack_mode", 1)
1132 1132
 ...
1133 1133
 
1134
+1.4.38. local_cancel_reason (boolean)
1135
+
1136
+   Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1137
+   due to receiving a final reply. The reason header added will look like:
1138
+   "Reason: SIP;cause=<final_reply_code>".
1139
+
1140
+   Default value is 1 (enabled).
1141
+
1142
+   Can be set at runtime, e.g.:
1143
+        $ sercmd cfg.set_now_int tm local_cancel_reason 0
1144
+
1145
+   See also: e2e_cancel_reason.
1146
+
1147
+   Example 38. Set local_cancel_reason parameter
1148
+...
1149
+modparam("tm", "local_cancel_reason", "0")
1150
+...
1151
+
1152
+1.4.39. e2e_cancel_reason (boolean)
1153
+
1154
+   Enables/disables adding reason headers (RFC 3326) for CANCELs generated
1155
+   due to a received CANCEL. If enabled the reason headers from received
1156
+   CANCELs will be copied into the generated hop-by-hop CANCELs.
1157
+
1158
+   Default value is 1 (enabled).
1159
+
1160
+   Can be changed at runtime, e.g.:
1161
+        $ sercmd cfg.set_now_int tm e2e_cancel_reason 0
1162
+
1163
+   See also: t_set_no_e2e_cancel_reason() and local_cancel_reason.
1164
+
1165
+   Example 39. Set e2e_cancel_reason parameter
1166
+...
1167
+modparam("tm", "e2e_cancel_reason", "0")
1168
+...
1169
+
1134 1170
 1.5. Functions
1135 1171
 
1136 1172
    Revision History
1137 1173
    Revision $Revision$ $Date$
1138 1174
 
1139
-1.5.1. t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
1175
+1.5.1.  t_relay_to_udp(ip, port), t_relay_to_udp(), t_relay_to_tcp(ip, port)
1140 1176
 t_relay_to_tcp() t_relay_to_tls(ip, port) t_relay_to_tls()
1141 1177
 t_relay_to_sctp(ip, port) t_relay_to_sctp()
1142 1178
 
... ...
@@ -1156,7 +1198,7 @@ t_relay_to_sctp(ip, port) t_relay_to_sctp()
1156 1156
    derived from the message uri (using sip sepcific DNS lookups), but with
1157 1157
    the protocol corresponding to the function name.
1158 1158
 
1159
-   Example 38. t_relay_to_udp usage
1159
+   Example 40. t_relay_to_udp usage
1160 1160
 ...
1161 1161
 if (src_ip==10.0.0.0/8)
1162 1162
         t_relay_to_udp("1.2.3.4", "5060"); # sent to 1.2.3.4:5060 over udp
... ...
@@ -1164,7 +1206,7 @@ else
1164 1164
         t_relay_to_tcp(); # relay to msg. uri, but over tcp
1165 1165
 ...
1166 1166
 
1167
-1.5.2. t_relay() t_relay(host, port)
1167
+1.5.2.  t_relay() t_relay(host, port)
1168 1168
 
1169 1169
    Relay a message statefully either to the destination indicated in the
1170 1170
    current URI (if called without any parameters) or to the specified host
... ...
@@ -1183,7 +1225,7 @@ else
1183 1183
    Returns a negative value on failure--you may still want to send a
1184 1184
    negative reply upstream statelessly not to leave upstream UAC in lurch.
1185 1185
 
1186
-   Example 39. t_relay usage
1186
+   Example 41. t_relay usage
1187 1187
 ...
1188 1188
 if (!t_relay())
1189 1189
 {
... ...
@@ -1192,7 +1234,7 @@ if (!t_relay())
1192 1192
 };
1193 1193
 ...
1194 1194
 
1195
-1.5.3. t_on_failure(failure_route)
1195
+1.5.3.  t_on_failure(failure_route)
1196 1196
 
1197 1197
    Sets failure routing block, to which control is passed after a
1198 1198
    transaction completed with a negative result but before sending a final
... ...
@@ -1212,7 +1254,7 @@ if (!t_relay())
1212 1212
    Meaning of the parameters is as follows:
1213 1213
      * failure_route - Failure route block to be called.
1214 1214
 
1215
-   Example 40. t_on_failure usage
1215
+   Example 42. t_on_failure usage
1216 1216
 ...
1217 1217
 route {
1218 1218
     t_on_failure("1");
... ...
@@ -1229,7 +1271,7 @@ failure_route[1] {
1229 1229
    See test/onr.cfg for a more complex example of combination of serial
1230 1230
    with parallel forking.
1231 1231
 
1232
-1.5.4. t_on_reply(onreply_route)
1232
+1.5.4.  t_on_reply(onreply_route)
1233 1233
 
1234 1234
    Sets the reply routing block, to which control is passed when a reply
1235 1235
    for the current transaction is received. Note that the set of commands
... ...
@@ -1238,7 +1280,7 @@ failure_route[1] {
1238 1238
    Meaning of the parameters is as follows:
1239 1239
      * onreply_route - Onreply route block to be called.
1240 1240
 
1241
-   Example 41. t_on_reply usage
1241
+   Example 43. t_on_reply usage
1242 1242
 ...
1243 1243
 loadmodule "/usr/local/lib/ser/modules/nathelper.so"
1244 1244
 ...
... ...
@@ -1259,7 +1301,7 @@ es');
1259 1259
         }
1260 1260
 }
1261 1261
 
1262
-1.5.5. t_on_branch(branch_route)
1262
+1.5.5.  t_on_branch(branch_route)
1263 1263
 
1264 1264
    Sets the branch routing block, to which control is passed after forking
1265 1265
    (when a new branch is created). For now branch routes are intended only
... ...
@@ -1270,7 +1312,7 @@ es');
1270 1270
    Meaning of the parameters is as follows:
1271 1271
      * branch_route - branch route block to be called.
1272 1272
 
1273
-   Example 42. t_on_branch usage
1273
+   Example 44. t_on_branch usage
1274 1274
 ...
1275 1275
 route {
1276 1276
         t_on_branch("1");
... ...
@@ -1283,12 +1325,12 @@ branch_route[1] {
1283 1283
         }
1284 1284
 }
1285 1285
 
1286
-1.5.6. append_branch()
1286
+1.5.6.  append_branch()
1287 1287
 
1288 1288
    Similarly to t_fork_to, it extends destination set by a new entry. The
1289 1289
    difference is that current URI is taken as new entry.
1290 1290
 
1291
-   Example 43. append_branch usage
1291
+   Example 45. append_branch usage
1292 1292
 ...
1293 1293
 set_user("john");
1294 1294
 t_fork();
... ...
@@ -1297,13 +1339,13 @@ t_fork();
1297 1297
 t_relay();
1298 1298
 ...
1299 1299
 
1300
-1.5.7. t_newtran()
1300
+1.5.7.  t_newtran()
1301 1301
 
1302 1302
    Creates a new transaction, returns a negative value on error. This is
1303 1303
    the only way a script can add a new transaction in an atomic way.
1304 1304
    Typically, it is used to deploy a UAS.
1305 1305
 
1306
-   Example 44. t_newtran usage
1306
+   Example 46. t_newtran usage
1307 1307
 ...
1308 1308
 if (t_newtran()) {
1309 1309
     log("UAS logic");
... ...
@@ -1313,7 +1355,7 @@ if (t_newtran()) {
1313 1313
 
1314 1314
    See test/uas.cfg for more examples.
1315 1315
 
1316
-1.5.8. t_reply(code, reason_phrase)
1316
+1.5.8.  t_reply(code, reason_phrase)
1317 1317
 
1318 1318
    Sends a stateful reply after a transaction has been established. See
1319 1319
    t_newtran for usage.
... ...
@@ -1322,12 +1364,12 @@ if (t_newtran()) {
1322 1322
      * code - Reply code number.
1323 1323
      * reason_phrase - Reason string.
1324 1324
 
1325
-   Example 45. t_reply usage
1325
+   Example 47. t_reply usage
1326 1326
 ...
1327 1327
 t_reply("404", "Not found");
1328 1328
 ...
1329 1329
 
1330
-1.5.9. t_lookup_request()
1330
+1.5.9.  t_lookup_request()
1331 1331
 
1332 1332
    Checks if a transaction exists. Returns a positive value if so,
1333 1333
    negative otherwise. Most likely you will not want to use it, as a
... ...
@@ -1335,33 +1377,33 @@ t_reply("404", "Not found");
1335 1335
    none was found. However this is safely (atomically) done using
1336 1336
    t_newtran.
1337 1337
 
1338
-   Example 46. t_lookup_request usage
1338
+   Example 48. t_lookup_request usage
1339 1339
 ...
1340 1340
 if (t_lookup_request()) {
1341 1341
     ...
1342 1342
 };
1343 1343
 ...
1344 1344
 
1345
-1.5.10. t_retransmit_reply()
1345
+1.5.10.  t_retransmit_reply()
1346 1346
 
1347 1347
    Retransmits a reply sent previously by UAS transaction.
1348 1348
 
1349
-   Example 47. t_retransmit_reply usage
1349
+   Example 49. t_retransmit_reply usage
1350 1350
 ...
1351 1351
 t_retransmit_reply();
1352 1352
 ...
1353 1353
 
1354
-1.5.11. t_release()
1354
+1.5.11.  t_release()
1355 1355
 
1356 1356
    Remove transaction from memory (it will be first put on a wait timer to
1357 1357
    absorb delayed messages).
1358 1358
 
1359
-   Example 48. t_release usage
1359
+   Example 50. t_release usage
1360 1360
 ...
1361 1361
 t_release();
1362 1362
 ...
1363 1363
 
1364
-1.5.12. t_forward_nonack() t_forward_nonack(ip, port)
1364
+1.5.12.  t_forward_nonack() t_forward_nonack(ip, port)
1365 1365
 t_forward_nonack_udp(ip, port) t_forward_nonack_tcp(ip, port)
1366 1366
 t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
1367 1367
 
... ...
@@ -1371,12 +1413,12 @@ t_forward_nonack_tls(ip, port) t_forward_nonack_sctp(ip, port)
1371 1371
      * ip - IP address where the message should be sent.
1372 1372
      * port - Port number.
1373 1373
 
1374
-   Example 49. t_forward_nonack usage
1374
+   Example 51. t_forward_nonack usage
1375 1375
 ...
1376 1376
 t_forward_nonack("1.2.3.4", "5060");
1377 1377
 ...
1378 1378
 
1379
-1.5.13. t_set_fr(fr_inv_timeout [, fr_timeout])
1379
+1.5.13.  t_set_fr(fr_inv_timeout [, fr_timeout])
1380 1380
 
1381 1381
    Sets the fr_inv_timeout and optionally fr_timeout for the current
1382 1382
    transaction or for transactions created during the same script
... ...
@@ -1394,7 +1436,7 @@ t_forward_nonack("1.2.3.4", "5060");
1394 1394
 
1395 1395
    See also: fr_timer, fr_inv_timer, t_reset_fr().
1396 1396
 
1397
-   Example 50. t_set_fr usage
1397
+   Example 52. t_set_fr usage
1398 1398
 ...
1399 1399
 route {
1400 1400
         t_set_fr(10000); # set only fr invite timeout to 10s
... ...
@@ -1410,7 +1452,7 @@ branch_route[1] {
1410 1410
         }
1411 1411
 }
1412 1412
 
1413
-1.5.14. t_reset_fr()
1413
+1.5.14.  t_reset_fr()
1414 1414
 
1415 1415
    Resets the fr_inv_timer and fr_timer for the current transaction to the
1416 1416
    default values (set using the tm module parameters fr_inv_timer and
... ...
@@ -1421,7 +1463,7 @@ branch_route[1] {
1421 1421
 
1422 1422
    See also: fr_timer, fr_inv_timer, t_set_fr.
1423 1423
 
1424
-   Example 51. t_reset_fr usage
1424
+   Example 53. t_reset_fr usage
1425 1425
 ...
1426 1426
 route {
1427 1427
 ...
... ...
@@ -1429,7 +1471,7 @@ route {
1429 1429
 ...
1430 1430
 }
1431 1431
 
1432
-1.5.15. t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1432
+1.5.15.  t_set_max_lifetime(inv_lifetime, noninv_lifetime)
1433 1433
 
1434 1434
    Sets the maximum lifetime for the current INVITE or non-INVITE
1435 1435
    transaction, or for transactions created during the same script
... ...
@@ -1447,7 +1489,7 @@ route {
1447 1447
 
1448 1448
    See also: max_inv_lifetime, max_noninv_lifetime, t_reset_max_lifetime.
1449 1449
 
1450
-   Example 52. t_set_max_lifetime usage
1450
+   Example 54. t_set_max_lifetime usage
1451 1451
 ...
1452 1452
 route {
1453 1453
     if (src_ip=1.2.3.4)
... ...
@@ -1458,7 +1500,7 @@ route {
1458 1458
                                           # INVITE and to 15s if not
1459 1459
 }
1460 1460
 
1461
-1.5.16. t_reset_max_lifetime()
1461
+1.5.16.  t_reset_max_lifetime()
1462 1462
 
1463 1463
    Resets the the maximum lifetime for the current INVITE or non-INVITE
1464 1464
    transaction to the default value (set using the tm module parameter
... ...
@@ -1469,7 +1511,7 @@ route {
1469 1469
 
1470 1470
    See also: max_inv_lifetime, max_noninv_lifetime, t_set_max_lifetime.
1471 1471
 
1472
-   Example 53. t_reset_max_lifetime usage
1472
+   Example 55. t_reset_max_lifetime usage
1473 1473
 ...
1474 1474
 route {
1475 1475
 ...
... ...
@@ -1477,7 +1519,7 @@ route {
1477 1477
 ...
1478 1478
 }
1479 1479
 
1480
-1.5.17. t_set_retr(retr_t1_interval, retr_t2_interval)
1480
+1.5.17.  t_set_retr(retr_t1_interval, retr_t2_interval)
1481 1481
 
1482 1482
    Sets the retr_t1_interval and retr_t2_interval for the current
1483 1483
    transaction or for transactions created during the same script
... ...
@@ -1507,7 +1549,7 @@ route {
1507 1507
 
1508 1508
    See also: retr_timer1, retr_timer2, t_reset_retr().
1509 1509
 
1510
-   Example 54. t_set_retr usage
1510
+   Example 56. t_set_retr usage
1511 1511
 ...
1512 1512
 route {
1513 1513
         t_set_retr(250, 0); # set only T1 to 250 ms
... ...
@@ -1523,7 +1565,7 @@ branch_route[1] {
1523 1523
         }
1524 1524
 }
1525 1525
 
1526
-1.5.18. t_reset_retr()
1526
+1.5.18.  t_reset_retr()
1527 1527
 
1528 1528
    Resets the retr_timer1 and retr_timer2 for the current transaction to
1529 1529
    the default values (set using the tm module parameters retr_timer1 and
... ...
@@ -1534,7 +1576,7 @@ branch_route[1] {
1534 1534
 
1535 1535
    See also: retr_timer1, retr_timer2, t_set_retr.
1536 1536
 
1537
-   Example 55. t_reset_retr usage
1537
+   Example 57. t_reset_retr usage
1538 1538
 ...
1539 1539
 route {
1540 1540
 ...
... ...
@@ -1542,7 +1584,7 @@ route {
1542 1542
 ...
1543 1543
 }
1544 1544
 
1545
-1.5.19. t_set_auto_inv_100(0|1)
1545
+1.5.19.  t_set_auto_inv_100(0|1)
1546 1546
 
1547 1547
    Switch automatically sending 100 replies to INVITEs on/off on a per
1548 1548
    transaction basis. It overrides the auto_inv_100 value for the current
... ...
@@ -1550,7 +1592,7 @@ route {
1550 1550
 
1551 1551
    See also: auto_inv_100.
1552 1552
 
1553
-   Example 56. t_set_auto_inv_100 usage
1553
+   Example 58. t_set_auto_inv_100 usage
1554 1554
 ...
1555 1555
 route {
1556 1556
 ...
... ...
@@ -1559,12 +1601,12 @@ route {
1559 1559
 ...
1560 1560
 }
1561 1561
 
1562
-1.5.20. t_branch_timeout()
1562
+1.5.20.  t_branch_timeout()
1563 1563
 
1564 1564
    Returns true if the failure route is executed for a branch that did
1565 1565
    timeout. It can be used only from the failure_route.
1566 1566
 
1567
-   Example 57. t_branch_timeout usage
1567
+   Example 59. t_branch_timeout usage
1568 1568
 ...
1569 1569
 failure_route[0]{
1570 1570
         if (t_branch_timeout()){
... ...
@@ -1573,13 +1615,13 @@ failure_route[0]{
1573 1573
         }
1574 1574
 }
1575 1575
 
1576
-1.5.21. t_branch_replied()
1576
+1.5.21.  t_branch_replied()
1577 1577
 
1578 1578
    Returns true if the failure route is executed for a branch that did
1579 1579
    receive at least one reply in the past (the "current" reply is not
1580 1580
    taken into account). It can be used only from the failure_route.
1581 1581
 
1582
-   Example 58. t_branch_replied usage
1582
+   Example 60. t_branch_replied usage
1583 1583
 ...
1584 1584
 failure_route[0]{
1585 1585
         if (t_branch_timeout()){
... ...
@@ -1591,12 +1633,12 @@ failure_route[0]{
1591 1591
         }
1592 1592
 }
1593 1593
 
1594
-1.5.22. t_any_timeout()
1594
+1.5.22.  t_any_timeout()
1595 1595
 
1596 1596
    Returns true if at least one of the current transactions branches did
1597 1597
    timeout.
1598 1598
 
1599
-   Example 59. t_any_timeout usage
1599
+   Example 61. t_any_timeout usage
1600 1600
 ...
1601 1601
 failure_route[0]{
1602 1602
         if (!t_branch_timeout()){
... ...
@@ -1607,13 +1649,13 @@ failure_route[0]{
1607 1607
         }
1608 1608
 }
1609 1609
 
1610
-1.5.23. t_any_replied()
1610
+1.5.23.  t_any_replied()
1611 1611
 
1612 1612
    Returns true if at least one of the current transactions branches did
1613 1613
    receive some reply in the past. If called from a failure or onreply
1614 1614
    route, the "current" reply is not taken into account.
1615 1615
 
1616
-   Example 60. t_any_replied usage
1616
+   Example 62. t_any_replied usage
1617 1617
 ...
1618 1618
 onreply_route[0]{
1619 1619
         if (!t_any_replied()){
... ...
@@ -1622,12 +1664,12 @@ onreply_route[0]{
1622 1622
         }
1623 1623
 }
1624 1624
 
1625
-1.5.24. t_grep_status("code")
1625
+1.5.24.  t_grep_status("code")
1626 1626
 
1627 1627
    Returns true if "code" is the final reply received (or locally
1628 1628
    generated) in at least one of the current transactions branches.
1629 1629
 
1630
-   Example 61. t_grep_status usage
1630
+   Example 63. t_grep_status usage
1631 1631
 ...
1632 1632
 onreply_route[0]{
1633 1633
         if (t_grep_status("486")){
... ...
@@ -1636,11 +1678,11 @@ onreply_route[0]{
1636 1636
         }
1637 1637
 }
1638 1638
 
1639
-1.5.25. t_is_canceled()
1639
+1.5.25.  t_is_canceled()
1640 1640
 
1641 1641
    Returns true if the current transaction was canceled.
1642 1642
 
1643
-   Example 62. t_is_canceled usage
1643
+   Example 64. t_is_canceled usage
1644 1644
 ...
1645 1645
 failure_route[0]{
1646 1646
         if (t_is_canceled()){
... ...
@@ -1649,12 +1691,12 @@ failure_route[0]{
1649 1649
         }
1650 1650
 }
1651 1651
 
1652
-1.5.26. t_is_expired()
1652
+1.5.26.  t_is_expired()
1653 1653
 
1654 1654
    Returns true if the current transaction has already been expired, i.e.
1655 1655
    the max_inv_lifetime/max_noninv_lifetime interval has already elapsed.
1656 1656
 
1657
-   Example 63. t_is_expired usage
1657
+   Example 65. t_is_expired usage
1658 1658
 ...
1659 1659
 failure_route[0]{
1660 1660
         if (t_is_expired()){
... ...
@@ -1663,7 +1705,7 @@ failure_route[0]{
1663 1663
         }
1664 1664
 }
1665 1665
 
1666
-1.5.27. t_relay_cancel()
1666
+1.5.27.  t_relay_cancel()
1667 1667
 
1668 1668
    Forwards the CANCEL if the corresponding INVITE transaction exists. The
1669 1669
    function is supposed to be used at the very beginning of the script,
... ...
@@ -1675,7 +1717,7 @@ failure_route[0]{
1675 1675
    CANCELs were successfully sent to the pending branches, true if the
1676 1676
    INVITE was not found, and false in case of any error.
1677 1677
 
1678
-   Example 64. t_relay_cancel usage
1678
+   Example 66. t_relay_cancel usage
1679 1679
 if (method == CANCEL) {
1680 1680
         if (!t_relay_cancel()) {  # implicit drop if relaying was successful,
1681 1681
                                   # nothing to do
... ...
@@ -1688,7 +1730,7 @@ if (method == CANCEL) {
1688 1688
         # do the same as for INVITEs
1689 1689
 }
1690 1690
 
1691
-1.5.28. t_lookup_cancel(), t_lookup_cancel(1)
1691
+1.5.28.  t_lookup_cancel(), t_lookup_cancel(1)
1692 1692
 
1693 1693
    Returns true if the corresponding INVITE transaction exists for a
1694 1694
    CANCEL request. The function can be called at the beginning of the
... ...
@@ -1702,7 +1744,7 @@ if (method == CANCEL) {
1702 1702
    overwritten with the flags of the INVITE. isflagset() can be used to
1703 1703
    check the flags of the previously forwarded INVITE in this case.
1704 1704
 
1705
-   Example 65. t_lookup_cancel usage
1705
+   Example 67. t_lookup_cancel usage
1706 1706
 if (method == CANCEL) {
1707 1707
         if (t_lookup_cancel()) {
1708 1708
                 log("INVITE transaction exists");
... ...
@@ -1720,7 +1762,7 @@ if (method == CANCEL) {
1720 1720
         # do the same as for INVITEs
1721 1721
 }
1722 1722
 
1723
-1.5.29. t_drop_replies([mode])
1723
+1.5.29.  t_drop_replies([mode])
1724 1724
 
1725 1725
    Drops all the previously received replies in failure_route block to
1726 1726
    make sure that none of them is picked up again.
... ...
@@ -1732,7 +1774,7 @@ if (method == CANCEL) {
1732 1732
    Dropping replies works only if a new branch is added to the
1733 1733
    transaction, or it is explicitly replied in the script!
1734 1734
 
1735
-   Example 66. t_drop_replies() usage
1735
+   Example 68. t_drop_replies() usage
1736 1736
 ...
1737 1737
 failure_route[0]{
1738 1738
         if (t_check_status("5[0-9][0-9]")){
... ...
@@ -1748,7 +1790,7 @@ failure_route[0]{
1748 1748
         }
1749 1749
 }
1750 1750
 
1751
-1.5.30. t_save_lumps()
1751
+1.5.30.  t_save_lumps()
1752 1752
 
1753 1753
    Forces the modifications of the processed SIP message to be saved in
1754 1754
    shared memory before t_relay() is called. The new branches which are
... ...
@@ -1763,7 +1805,7 @@ failure_route[0]{
1763 1763
    The transaction must be created by t_newtran() before calling
1764 1764
    t_save_lumps().
1765 1765
 
1766
-   Example 67. t_save_lumps() usage
1766
+   Example 69. t_save_lumps() usage
1767 1767
 route {
1768 1768
         ...
1769 1769
         t_newtran();
... ...
@@ -1788,7 +1830,7 @@ failure_route[1] {
1788 1788
         t_relay();
1789 1789
 }
1790 1790
 
1791
-1.5.31. t_load_contacts()
1791
+1.5.31.  t_load_contacts()
1792 1792
 
1793 1793
    This is the first of the two functions that can be used to implement
1794 1794
    serial/parallel forking based on the q value of individual branches in
... ...
@@ -1833,7 +1875,7 @@ failure_route[1] {
1833 1833
 
1834 1834
    This function can be used from REQUEST_ROUTE.
1835 1835
 
1836
-   Example 68. t_load_contacts usage
1836
+   Example 70. t_load_contacts usage
1837 1837
 ...
1838 1838
 if (!t_load_contacts()) {
1839 1839
         sl_send_reply("500", "Server Internal Error - Cannot load contacts");
... ...
@@ -1841,7 +1883,7 @@ if (!t_load_contacts()) {
1841 1841
 };
1842 1842
 ...
1843 1843
 
1844
-1.5.32. t_next_contacts()
1844
+1.5.32.  t_next_contacts()
1845 1845
 
1846 1846
    The function t_next_contacts is the second of the two functions that
1847 1847
    can be used to implement serial/parallel forking based on the q value
... ...
@@ -1885,7 +1927,7 @@ if (!t_load_contacts()) {
1885 1885
    especially if you expect to have many serially forked branches. See the
1886 1886
    documentation of that parameter for more details.
1887 1887
 
1888
-   Example 69. t_next_contacts usage
1888
+   Example 71. t_next_contacts usage
1889 1889
 ...
1890 1890
 # First call after t_load_contacts() when transaction does not exist yet
1891 1891
 # and contacts should be available
... ...
@@ -1904,7 +1946,7 @@ if (!t_next_contacts()) {
1904 1904
 };
1905 1905
 ...
1906 1906
 
1907
-1.5.33. t_check_trans()
1907
+1.5.33.  t_check_trans()
1908 1908
 
1909 1909
    t_check_trans() can be used to quickly check if a message belongs or is
1910 1910
    related to a transaction. It behaves differently for different types of
... ...
@@ -1949,12 +1991,12 @@ Note
1949 1949
 
1950 1950
    See also: t_lookup_request(), t_lookup_cancel().
1951 1951
 
1952
-   Example 70. t_check_trans usage
1952
+   Example 72. t_check_trans usage
1953 1953
 if ( method == "CANCEL" && !t_check_trans())
1954 1954
         sl_reply("403", "cancel out of the blue forbidden");
1955 1955
 # note: in this example t_check_trans() can be replaced by t_lookup_cancel()
1956 1956
 
1957
-1.5.34. t_set_disable_6xx(0|1)
1957
+1.5.34.  t_set_disable_6xx(0|1)
1958 1958
 
1959 1959
    Turn off/on 6xx replies special rfc conformant handling on a per
1960 1960
    transaction basis. If turned off (t_set_disable_6xx("1")) 6XXs will be
... ...
@@ -1964,7 +2006,7 @@ if ( method == "CANCEL" && !t_check_trans())
1964 1964
 
1965 1965
    See also: disable_6xx_block.
1966 1966
 
1967
-   Example 71. t_set_disable_6xx usage
1967
+   Example 73. t_set_disable_6xx usage
1968 1968
 ...
1969 1969
 route {
1970 1970
 ...
... ...
@@ -1973,13 +2015,13 @@ route {
1973 1973
 ...
1974 1974
 }
1975 1975
 
1976
-1.5.35. t_set_disable_failover(0|1)
1976
+1.5.35.  t_set_disable_failover(0|1)
1977 1977
 
1978 1978
    Turn off/on dns failover on a per transaction basis.
1979 1979
 
1980 1980
    See also: use_dns_failover.
1981 1981
 
1982
-   Example 72. t_set_disable_failover usage
1982
+   Example 74. t_set_disable_failover usage
1983 1983
 ...
1984 1984
 route {
1985 1985
 ...
... ...
@@ -1988,7 +2030,7 @@ route {
1988 1988
 ...
1989 1989
 }
1990 1990
 
1991
-1.5.36. t_replicate(params)
1991
+1.5.36.  t_replicate(params)
1992 1992
 
1993 1993
    Replicate the SIP request to a specific address.
1994 1994
 
... ...
@@ -2010,7 +2052,7 @@ route {
2010 2010
      * hostport - address in "host:port" format. It can be given via an
2011 2011
        AVP.
2012 2012
 
2013
-   Example 73. t_replicate usage
2013
+   Example 75. t_replicate usage
2014 2014
 ...
2015 2015
 # sent to 1.2.3.4:5060 over tcp
2016 2016
 t_replicate("sip:1.2.3.4:5060;transport=tcp");
... ...
@@ -2023,7 +2065,7 @@ t_replicate("sip:$var(h);transport=tls");
2023 2023
 t_replicate_to_udp("1.2.3.4", "5060");
2024 2024
 ...
2025 2025
 
2026
-1.5.37. t_relay_to(proxy, flags)
2026
+1.5.37.  t_relay_to(proxy, flags)
2027 2027
 
2028 2028
    Forward the SIP request to a specific address, controlling internal
2029 2029
    behavior via flags.
... ...
@@ -2045,7 +2087,7 @@ t_replicate_to_udp("1.2.3.4", "5060");
2045 2045
             effect anymore).
2046 2046
           + 0x04 - disable dns failover.
2047 2047
 
2048
-   Example 74. t_replicate usage
2048
+   Example 76. t_replicate usage
2049 2049
 ...
2050 2050
 # sent to 1.2.3.4:5060 over tcp
2051 2051
 t_relay_to("tcp:1.2.3.4:5060");
... ...
@@ -2057,6 +2099,27 @@ t_relay_to("tls:1.2.3.4");
2057 2057
 t_relay_to("0x01");
2058 2058
 ...
2059 2059
 
2060
+1.5.38.  t_set_no_e2e_cancel_reason(0|1)
2061
+
2062
+   Enables/disables reason header (RFC 3326) copying from the triggering
2063
+   received CANCEL to the generated hop-by-hop CANCEL. 0 enables and 1
2064
+   disables.
2065
+
2066
+   It overrides the e2e_cancel_reason setting (module parameter) for the
2067
+   current transaction.
2068
+
2069
+   See also: e2e_cancel_reason.
2070
+
2071
+   Example 77. t_set_no_e2e_cancel_reason usage
2072
+...
2073
+route {
2074
+...
2075
+        if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
2076
+                t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header c
2077
+opying
2078
+...
2079
+}
2080
+
2060 2081
 1.6. TM Module API
2061 2082
 
2062 2083
    Revision History
... ...
@@ -2126,7 +2189,7 @@ end of body
2126 2126
 
2127 2127
 1.6.2. Functions
2128 2128
 
2129
-1.6.2.1. register_tmcb(cb_type, cb_func)
2129
+1.6.2.1.  register_tmcb(cb_type, cb_func)
2130 2130
 
2131 2131
    For programmatic use only--register a function to be called back on an
2132 2132
    event. See t_hooks.h for more details.
... ...
@@ -2135,7 +2198,7 @@ end of body
2135 2135
      * cb_type - Callback type.
2136 2136
      * cb_func - Callback function.
2137 2137
 
2138
-1.6.2.2. load_tm(*import_structure)
2138
+1.6.2.2.  load_tm(*import_structure)
2139 2139
 
2140 2140
    For programmatic use only--import exported TM functions. See the acc
2141 2141
    module for an example of use.
... ...
@@ -2143,7 +2206,7 @@ end of body
2143 2143
    Meaning of the parameters is as follows:
2144 2144
      * import_structure - Pointer to the import structure.
2145 2145
 
2146
-1.6.2.3. int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
2146
+1.6.2.3.  int t_suspend(struct sip_msg *msg, unsigned int *hash_index,
2147 2147
 unsigned int *label)
2148 2148
 
2149 2149
    For programmatic use only. This function together with t_continue() can
... ...
@@ -2181,7 +2244,7 @@ unsigned int *label)
2181 2181
    t_suspend() should return 0 to make sure that the script processing
2182 2182
    does not continue.
2183 2183
 
2184
-1.6.2.4. int t_continue(unsigned int hash_index, unsigned int label, struct
2184
+1.6.2.4.  int t_continue(unsigned int hash_index, unsigned int label, struct
2185 2185
 action *route)
2186 2186
 
2187 2187
    For programmatic use only. This function is the pair of t_suspend(),
... ...
@@ -2196,3 +2259,19 @@ action *route)
2196 2196
      * route - route block to execute.
2197 2197
 
2198 2198
    Return value: 0 - success, <0 - error.
2199
+
2200
+1.6.2.5.  int t_cancel_suspend(unsigned int hash_index, unsigned int label)
2201
+
2202
+   For programmatic use only. This function is for revoking t_suspend()
2203
+   from the same process as it was executed before. t_cancel_suspend() can
2204
+   be used when something fails after t_suspend() has already been
2205
+   executed and it turns out that the transcation should not have been
2206
+   suspended. The function cancels the FR timer of the transacation.
2207
+
2208
+   The message lumps are saved by t_suspend() which cannot be restored.
2209
+
2210
+   Meaning of the parameters is as follows:
2211
+     * hash_index - transaction identifier.
2212
+     * label - transaction identifier.
2213
+
2214
+   Return value: 0 - success, <0 - error.
... ...
@@ -1224,7 +1224,9 @@ if (!t_next_contacts()) {
1224 1224
 				INVITE transactions) it will return true if the corresponding
1225 1225
 				INVITE transaction is found and still active and false if not.
1226 1226
 				</para>
1227
-				<note>Note that the e2e ACK matching is more of a hint
1227
+				<note>
1228
+				<para>
1229
+				Note that the e2e ACK matching is more of a hint
1228 1230
 				then a certainty. A delayed e2e ACK might arrive after the
1229 1231
 				transaction wait time elapses, when the INVITE transaction no
1230 1232
 				longer exists and thus would not match anything. There are
... ...
@@ -1232,6 +1234,7 @@ if (!t_next_contacts()) {
1232 1232
 				for e2e ACK matching (since this is not needed for a statefull
1233 1233
 				proxy and it requires additional memory, tm will not keep this
1234 1234
 				information unless needed by some other module or callbacks).
1235
+				</para>
1235 1236
 				</note>
1236 1237
 			</listitem>
1237 1238
 			<listitem>
... ...
@@ -1332,27 +1335,27 @@ route {
1332 1332
 	<para>
1333 1333
 		There are several function prototypes:
1334 1334
 		<itemizedlist>
1335
-		<listitem>
1335
+		<listitem><para>
1336 1336
 	    <function>t_replicate(uri)</function>,
1337
-		</listitem>
1338
-		<listitem>
1337
+		</para></listitem>
1338
+		<listitem><para>
1339 1339
 	    <function>t_replicate(host, port)</function>,
1340
-		</listitem>
1341
-		<listitem>
1340
+		</para></listitem>
1341
+		<listitem><para>
1342 1342
 	    <function>t_replicat_udp(host, port)</function>
1343
-		</listitem>
1344
-		<listitem>
1343
+		</para></listitem>
1344
+		<listitem><para>
1345 1345
 	    <function>t_replicate_tcp(host, port)</function>
1346
-		</listitem>
1347
-		<listitem>
1346
+		</para></listitem>
1347
+		<listitem><para>
1348 1348
 	    <function>t_replicate_tls(host, port)</function>
1349
-		</listitem>
1350
-		<listitem>
1349
+		</para></listitem>
1350
+		<listitem><para>
1351 1351
 	    <function>t_replicate_sctp(host, port)</function>
1352
-		</listitem>
1353
-		<listitem>
1352
+		</para></listitem>
1353
+		<listitem><para>
1354 1354
 	    <function>t_replicate_to(proto, hostport)</function>
1355
-		</listitem>
1355
+		</para></listitem>
1356 1356
 		</itemizedlist>
1357 1357
 	</para>
1358 1358
 	<para>Meaning of the parameters is as follows:</para>
... ...
@@ -1408,18 +1411,18 @@ t_replicate_to_udp("1.2.3.4", "5060");
1408 1408
 	<para>
1409 1409
 		There are several function prototypes:
1410 1410
 		<itemizedlist>
1411
-		<listitem>
1411
+		<listitem><para>
1412 1412
 	    <function>t_relay_to()</function>,
1413
-		</listitem>
1414
-		<listitem>
1413
+		</para></listitem>
1414
+		<listitem><para>
1415 1415
 	    <function>t_relay_to(proxy)</function>,
1416
-		</listitem>
1417
-		<listitem>
1416
+		</para></listitem>
1417
+		<listitem><para>
1418 1418
 	    <function>t_relay_to(flags)</function>
1419
-		</listitem>
1420
-		<listitem>
1419
+		</para></listitem>
1420
+		<listitem><para>
1421 1421
 	    <function>t_relay_to(proxy, flags)</function>
1422
-		</listitem>
1422
+		</para></listitem>
1423 1423
 		</itemizedlist>
1424 1424
 	</para>
1425 1425
 	<para>Meaning of the parameters is as follows:</para>
... ...
@@ -1468,4 +1471,36 @@ t_relay_to("0x01");
1468 1468
 	</example>
1469 1469
     </section>
1470 1470
 
1471
+
1472
+	<section id="t_set_no_e2e_cancel_reason">
1473
+	<title>
1474
+		<function>t_set_no_e2e_cancel_reason(0|1)</function>
1475
+	</title>
1476
+	<para>
1477
+		Enables/disables reason header (RFC 3326) copying from the triggering
1478
+		received CANCEL to the generated hop-by-hop CANCEL. 0 enables and
1479
+		1 disables.
1480
+	</para>
1481
+	<para>
1482
+		It overrides the <varname>e2e_cancel_reason</varname> setting (module
1483
+		 parameter) for the current transaction.
1484
+	</para>
1485
+	<para>
1486
+		See also: <varname>e2e_cancel_reason</varname>.
1487
+	</para>
1488
+	<example>
1489
+		<title><function>t_set_no_e2e_cancel_reason</function> usage</title>
1490
+		<programlisting>
1491
+...
1492
+route {
1493
+...
1494
+	if (src_ip!=10.0.0.0/8) #  don't trust CANCELs from the outside
1495
+		t_set_no_e2e_cancel_reason(1); # turn off CANCEL reason header copying
1496
+...
1497
+}
1498
+		</programlisting>
1499
+	</example>
1500
+	</section>
1501
+
1502
+
1471 1503
 </section>
... ...
@@ -45,9 +45,11 @@ modparam("tm", "fr_timer", 10000)
45 45
 	</para>
46 46
 	<para>
47 47
 	</para>
48
+	<para>
48 49
 		Note: this timer can be restarted when a provisional response is
49 50
 		received. For more details see
50 51
 		<varname>restart_fr_on_each_reply</varname>.
52
+	</para>
51 53
 	<para>
52 54
 	    Default value is 120000 ms (120 seconds).
53 55
 	</para>
... ...
@@ -1142,11 +1144,11 @@ modparam("tm", "disable_6xx_block", 1)
1142 1142
 		reply.
1143 1143
 		</para></listitem>
1144 1144
 	</itemizedlist>
1145
-	<note>
1145
+	<note><para>
1146 1146
 	Mode 1 and 2 break the rfc, but are useful to deal with some simple UAs
1147 1147
 	behind the NAT cases (no different routing for the ACK and the contact 
1148 1148
 	contains an address behind the NAT).
1149
-	</note>
1149
+	</para></note>
1150 1150
 	<para>
1151 1151
 		The default value is 0 (rfc conformant behaviour).
1152 1152
 	</para>
... ...
@@ -1166,4 +1168,66 @@ modparam("tm", "local_ack_mode", 1)
1166 1166
 	</example>
1167 1167
 	</section>
1168 1168
 
1169
+
1170
+	<section id="local_cancel_reason">
1171
+		<title><varname>local_cancel_reason</varname> (boolean)</title>
1172
+		<para>
1173
+			Enables/disables adding reason headers (RFC 3326) for CANCELs
1174
+			generated due to receiving a final reply. The reason header added
1175
+			will look like: "Reason: SIP;cause=&lt;final_reply_code&gt;".
1176
+		</para>
1177
+		<para>
1178
+			Default value is 1 (enabled).
1179
+		</para>
1180
+		<para>
1181
+			Can be set at runtime, e.g.:
1182
+			<programlisting>
1183
+	$ sercmd cfg.set_now_int tm local_cancel_reason 0
1184
+			</programlisting>
1185
+		</para>
1186
+		<para>
1187
+			See also: <varname>e2e_cancel_reason</varname>.
1188
+		</para>
1189
+		<example>
1190
+			<title>Set <varname>local_cancel_reason</varname> parameter</title>
1191
+			<programlisting>
1192
+...
1193
+modparam("tm", "local_cancel_reason", "0")
1194
+...
1195
+			</programlisting>
1196
+		</example>
1197
+	</section>
1198
+
1199
+
1200
+	<section id="e2e_cancel_reason">
1201
+		<title><varname>e2e_cancel_reason</varname> (boolean)</title>
1202
+		<para>
1203
+			Enables/disables adding reason headers (RFC 3326) for CANCELs
1204
+			generated due to a received CANCEL.  If enabled the reason headers
1205
+			from received CANCELs will be copied into the generated hop-by-hop
1206
+			CANCELs.
1207
+		</para>
1208
+		<para>
1209
+			Default value is 1 (enabled).
1210
+		</para>
1211
+		<para>
1212
+			Can be changed at runtime, e.g.:
1213
+			<programlisting>
1214
+	$ sercmd cfg.set_now_int tm e2e_cancel_reason 0
1215
+			</programlisting>
1216
+		</para>
1217
+		<para>
1218
+			See also: <function>t_set_no_e2e_cancel_reason()</function> and
1219
+						<varname>local_cancel_reason</varname>.
1220
+		</para>
1221
+		<example>
1222
+			<title>Set <varname>e2e_cancel_reason</varname> parameter</title>
1223
+			<programlisting>
1224
+...
1225
+modparam("tm", "e2e_cancel_reason", "0")
1226
+...
1227
+			</programlisting>
1228
+		</example>
1229
+	</section>
1230
+
1169 1231
 </section>
... ...
@@ -1,6 +1,13 @@
1 1
 <?xml version="1.0" encoding="UTF-8"?>
2 2
 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
3
-   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
3
+	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4
+	[ <!ENTITY % local.common.attrib
5
+	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
6
+	 <!-- Include general documentation entities -->
7
+	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
8
+	 %docentities;
9
+	]
10
+>
4 11
 
5 12
 <section id="tm" xmlns:xi="http://www.w3.org/2001/XInclude">
6 13
     <sectioninfo>