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