mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
599 lines
14 KiB
599 lines
14 KiB
TMX Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
asipto.com
|
|
<miconda@gmail.com>
|
|
|
|
Juha Heinanen
|
|
|
|
TutPro Inc.
|
|
<jh@tutpro.com>
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Juha Heinanen
|
|
|
|
<jh@tutpro.com>
|
|
|
|
Copyright © 2009 Daniel-Constantin Mierla
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. precheck_trans
|
|
|
|
4. Functions
|
|
|
|
4.1. t_cancel_branches(which)
|
|
4.2. t_cancel_callid(callid, cseq, flag [, rcode])
|
|
4.3. t_reply_callid(callid, cseq, code, reason)
|
|
4.4. t_flush_flags()
|
|
4.5. t_is_failure_route()
|
|
4.6. t_is_branch_route()
|
|
4.7. t_is_reply_route()
|
|
4.8. t_is_request_route()
|
|
4.9. t_suspend()
|
|
4.10. t_continue(tindex, tlabel, rtname)
|
|
4.11. t_reuse_branch()
|
|
4.12. t_precheck_trans()
|
|
|
|
5. Exported pseudo-variables
|
|
6. MI Commands
|
|
|
|
6.1. t_uac_dlg
|
|
6.2. t_uac_cancel
|
|
6.3. t_hash
|
|
6.4. t_reply
|
|
6.5. t_reply_callid
|
|
|
|
7. Statistics
|
|
|
|
7.1. UAS_transactions
|
|
7.2. UAC_transactions
|
|
7.3. 2xx_transactions
|
|
7.4. 3xx_transactions
|
|
7.5. 4xx_transactions
|
|
7.6. 5xx_transactions
|
|
7.7. 6xx_transactions
|
|
7.8. inuse_transactions
|
|
7.9. active_transactions
|
|
7.10. rpl_received
|
|
7.11. rpl_absorbed
|
|
7.12. rpl_relayed
|
|
7.13. rpl_generated
|
|
7.14. rpl_sent
|
|
|
|
List of Examples
|
|
|
|
1.1. precheck_trans usage
|
|
1.2. t_cancel_branches usage
|
|
1.3. t_cancel_callid usage
|
|
1.4. t_reply_callid usage
|
|
1.5. t_flush_flags usage
|
|
1.6. t_is_failure_route usage
|
|
1.7. t_is_branch_route usage
|
|
1.8. t_is_reply_route usage
|
|
1.9. t_is_request_route usage
|
|
1.10. t_suspend usage
|
|
1.11. t_continue usage
|
|
1.12. t_reuse_branch usage
|
|
1.13. t_precheck_trans usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. precheck_trans
|
|
|
|
4. Functions
|
|
|
|
4.1. t_cancel_branches(which)
|
|
4.2. t_cancel_callid(callid, cseq, flag [, rcode])
|
|
4.3. t_reply_callid(callid, cseq, code, reason)
|
|
4.4. t_flush_flags()
|
|
4.5. t_is_failure_route()
|
|
4.6. t_is_branch_route()
|
|
4.7. t_is_reply_route()
|
|
4.8. t_is_request_route()
|
|
4.9. t_suspend()
|
|
4.10. t_continue(tindex, tlabel, rtname)
|
|
4.11. t_reuse_branch()
|
|
4.12. t_precheck_trans()
|
|
|
|
5. Exported pseudo-variables
|
|
6. MI Commands
|
|
|
|
6.1. t_uac_dlg
|
|
6.2. t_uac_cancel
|
|
6.3. t_hash
|
|
6.4. t_reply
|
|
6.5. t_reply_callid
|
|
|
|
7. Statistics
|
|
|
|
7.1. UAS_transactions
|
|
7.2. UAC_transactions
|
|
7.3. 2xx_transactions
|
|
7.4. 3xx_transactions
|
|
7.5. 4xx_transactions
|
|
7.6. 5xx_transactions
|
|
7.7. 6xx_transactions
|
|
7.8. inuse_transactions
|
|
7.9. active_transactions
|
|
7.10. rpl_received
|
|
7.11. rpl_absorbed
|
|
7.12. rpl_relayed
|
|
7.13. rpl_generated
|
|
7.14. rpl_sent
|
|
|
|
1. Overview
|
|
|
|
This module collects extensions from Kamailio TM module.
|
|
|
|
Kamailio TM (Transaction Management) module documentation is available
|
|
at: http://www.kamailio.org/docs/modules/stable/tm.html
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* tm - transaction management.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* None.
|
|
|
|
3. Parameters
|
|
|
|
3.1. precheck_trans
|
|
|
|
3.1. precheck_trans
|
|
|
|
Enable/disable transaction pre-check via t_precheck_trans() function.
|
|
If set to 0, the internal structures are not created at startup and the
|
|
funcation will return false always.
|
|
|
|
Default value is 1 (enabled).
|
|
|
|
Example 1.1. precheck_trans usage
|
|
...
|
|
modparam("tmx", "precheck_trans", 0)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. t_cancel_branches(which)
|
|
4.2. t_cancel_callid(callid, cseq, flag [, rcode])
|
|
4.3. t_reply_callid(callid, cseq, code, reason)
|
|
4.4. t_flush_flags()
|
|
4.5. t_is_failure_route()
|
|
4.6. t_is_branch_route()
|
|
4.7. t_is_reply_route()
|
|
4.8. t_is_request_route()
|
|
4.9. t_suspend()
|
|
4.10. t_continue(tindex, tlabel, rtname)
|
|
4.11. t_reuse_branch()
|
|
4.12. t_precheck_trans()
|
|
|
|
4.1. t_cancel_branches(which)
|
|
|
|
Cancel branches of an active SIP transaction. The function can be
|
|
called for a SIP reply that will identify the current branch.
|
|
|
|
Parameter can be:.
|
|
* all - cancel all branches.
|
|
* others - cancel all branches but the current one.
|
|
* this - cancel current branch.
|
|
|
|
This function can be used in ONREPLY_ROUTE.
|
|
|
|
Example 1.2. t_cancel_branches usage
|
|
...
|
|
if (t_cancel_branches("all")) {
|
|
xlog("cancelled all branches\n");
|
|
}
|
|
...
|
|
|
|
4.2. t_cancel_callid(callid, cseq, flag [, rcode])
|
|
|
|
Cancel first INVITE transaction identified by callid and cseq. It sets
|
|
the flag if the value is greater than zero
|
|
|
|
Parameters:.
|
|
* callid - call-id value.
|
|
* cseq - cseq number.
|
|
* flag - index of the flag to set.
|
|
* rcode - code to be added as cause attribute in Reason header for
|
|
generated CANCEL request. This parameter is optional.
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
Example 1.3. t_cancel_callid usage
|
|
...
|
|
if (t_cancel_callid("123qaz", "5", "22")) {
|
|
xlog("transaction cancelled\n");
|
|
}
|
|
...
|
|
if (t_cancel_callid("123qaz", "5", "22", "200")) {
|
|
xlog("transaction cancelled with [Reason: cause=200]\n");
|
|
}
|
|
...
|
|
|
|
4.3. t_reply_callid(callid, cseq, code, reason)
|
|
|
|
Send reply to first transaction identified by callid and cseq.
|
|
|
|
Parameters:.
|
|
* callid - call-id value.
|
|
* cseq - cseq number.
|
|
* code - reply code.
|
|
* reason - reply reason.
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
Example 1.4. t_reply_callid usage
|
|
...
|
|
if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
|
|
xlog("transaction replied\n");
|
|
}
|
|
...
|
|
|
|
4.4. t_flush_flags()
|
|
|
|
Flush the flags from current SIP message into the already created
|
|
transaction. It make sense only in routing block if the transaction was
|
|
created via t_newtran() and the flags have been altered since.
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.5. t_flush_flags usage
|
|
...
|
|
t_flush_flags();
|
|
...
|
|
|
|
4.5. t_is_failure_route()
|
|
|
|
Returns true if the top-executed route block is failure_route.
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.6. t_is_failure_route usage
|
|
...
|
|
failure_route[xyz] {
|
|
route(abc);
|
|
}
|
|
|
|
route[abc] {
|
|
if(t_is_failure_route()) { ... }
|
|
}
|
|
...
|
|
|
|
4.6. t_is_branch_route()
|
|
|
|
Returns true if the top-executed route block is branch_route.
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.7. t_is_branch_route usage
|
|
...
|
|
branch_route[xyz] {
|
|
route(abc);
|
|
}
|
|
|
|
route[abc] {
|
|
if(t_is_branch_route()) { ... }
|
|
}
|
|
...
|
|
|
|
4.7. t_is_reply_route()
|
|
|
|
Returns true if the top-executed route block is reply_route.
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.8. t_is_reply_route usage
|
|
...
|
|
reply_route[xyz] {
|
|
route(abc);
|
|
}
|
|
|
|
route[abc] {
|
|
if(t_is_reply_route()) { ... }
|
|
}
|
|
...
|
|
|
|
4.8. t_is_request_route()
|
|
|
|
Returns true if the top-executed route block is request_route.
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.9. t_is_request_route usage
|
|
...
|
|
request_route[xyz] {
|
|
route(abc);
|
|
}
|
|
|
|
route[abc] {
|
|
if(t_is_request_route()) { ... }
|
|
}
|
|
...
|
|
|
|
4.9. t_suspend()
|
|
|
|
Suspend the execution of SIP request in a transaction. If transaction
|
|
was not created yet, it is created by this function. Returns true in
|
|
case of success and internal transaction index and label are available
|
|
via $T(id_index) and $T(id_label).
|
|
|
|
This function can be used from ANY_ROUTE .
|
|
|
|
Example 1.10. t_suspend usage
|
|
...
|
|
if(t_suspend())
|
|
{
|
|
xlog("proceesing suspended in trasaction [$T(id_index):$T(id_label)]\n");
|
|
exit;
|
|
}
|
|
...
|
|
|
|
4.10. t_continue(tindex, tlabel, rtname)
|
|
|
|
Continue the execution of the transaction identified by tindex and
|
|
tlabel with the actions defined in route[rtname].
|
|
|
|
Parameters:.
|
|
* tindex - internal index of transaction. Can be an integer or a
|
|
pseudo-variable.
|
|
* tlabel - internal label of transaction. Can be an integer or a
|
|
pseudo-variable.
|
|
* rtname - the name of the route block to execute. Can be a static
|
|
string value or a dynamic string with pseudo-variables.
|
|
|
|
Important note: the route[rtname] is executed in the context of a
|
|
failure (same behaviour for functions as they were used in a
|
|
failure_route block).
|
|
|
|
This function can be used in ANY_ROUTE.
|
|
|
|
Example 1.11. t_continue usage
|
|
...
|
|
t_continue('123', '456', 'MYROUTE');
|
|
...
|
|
route[MYROUTE] {
|
|
xlog("executed by t continue\n");
|
|
...
|
|
}
|
|
...
|
|
|
|
4.11. t_reuse_branch()
|
|
|
|
Creates new "main" branch by making copy of branch-failure branch.
|
|
Currently the following branch attributes are copied from
|
|
branch-failure branch: request-uri, ruid, path, instance, and branch
|
|
flags.
|
|
|
|
This function can be used from tm:branch-failure event_route.
|
|
|
|
Example 1.12. t_reuse_branch usage
|
|
...
|
|
event_route [tm:branch-failure:contact] {
|
|
t_reuse_branch();
|
|
setbflag(10);
|
|
t_relay();
|
|
exit;
|
|
}
|
|
...
|
|
|
|
4.12. t_precheck_trans()
|
|
|
|
Check if current processed message is handled by other process. This
|
|
function is useful to catch retransmissions before transaction is
|
|
created. The function returns true if the request is handled by another
|
|
process.
|
|
|
|
Note that ACK and CANCEL requests are not tracked by this function, the
|
|
return code being false for them.
|
|
|
|
This function can be used from REQUEST_ROUTE .
|
|
|
|
Example 1.13. t_precheck_trans usage
|
|
...
|
|
# handle retransmissions
|
|
if(t_precheck_trans()) {
|
|
t_check_trans();
|
|
exit;
|
|
}
|
|
t_check_trans();
|
|
...
|
|
|
|
5. Exported pseudo-variables
|
|
|
|
* $T_branch_idx
|
|
* $T_reply_code
|
|
* $T_reply_reason
|
|
* $T_reply_last
|
|
* $T_req(pv)
|
|
* $T_rpl(pv)
|
|
* $T_reply_ruid
|
|
* $T_branch(name)
|
|
* $T_inv(pv)
|
|
* $T(name)
|
|
|
|
Exported pseudo-variables are documented at
|
|
http://www.kamailio.org/wiki/.
|
|
|
|
6. MI Commands
|
|
|
|
6.1. t_uac_dlg
|
|
6.2. t_uac_cancel
|
|
6.3. t_hash
|
|
6.4. t_reply
|
|
6.5. t_reply_callid
|
|
|
|
6.1. t_uac_dlg
|
|
|
|
Generates and sends a local SIP request.
|
|
|
|
Parameters:
|
|
* method - request method
|
|
* RURI - request SIP URI
|
|
* NEXT HOP - next hop SIP URI (OBP); use “.” if no value.
|
|
* socket - local socket to be used for sending the request; use “.”
|
|
if no value.
|
|
* headers - set of additional headers to be added to the request; at
|
|
least “From” and “To” headers must be specify)
|
|
* body - (optional, may not be present) request body (if present,
|
|
requires the “Content-Type” and “Content-length” headers)
|
|
|
|
6.2. t_uac_cancel
|
|
|
|
Generates and sends a CANCEL for an existing local SIP request.
|
|
|
|
Parameters:
|
|
* callid - callid of the INVITE request to be cancelled.
|
|
* cseq - cseq of the INVITE request to be cancelled.
|
|
|
|
6.3. t_hash
|
|
|
|
Gets information about the load of TM internal hash table.
|
|
|
|
Parameters:
|
|
* none
|
|
|
|
6.4. t_reply
|
|
|
|
Generates and sends a reply for an existing inbound SIP transaction.
|
|
|
|
Parameters:
|
|
* code - reply code
|
|
* reason - reason phrase.
|
|
* trans_id - transaction identifier (has the hash_entry:label format)
|
|
* to_tag - To tag to be added to TO header
|
|
* new_headers - extra headers to be appended to the reply; use a dot
|
|
(“.”) char only if there are no headers;
|
|
* body - (optional, may not be present) reply body (if present,
|
|
requires the “Content-Type” and “Content-length” headers)
|
|
|
|
6.5. t_reply_callid
|
|
|
|
Generates and sends a reply for an existing inbound SIP transaction.
|
|
|
|
Parameters:
|
|
* code - reply code
|
|
* reason - reason phrase.
|
|
* callid - SIP Call-ID header
|
|
* cseq - SIP CSeq header
|
|
* to_tag - To tag to be added to TO header
|
|
* new_headers - extra headers to be appended to the reply; use a dot
|
|
(“.”) char only if there are no headers;
|
|
* body - (optional, may not be present) reply body (if present,
|
|
requires the “Content-Type” and “Content-length” headers)
|
|
|
|
7. Statistics
|
|
|
|
7.1. UAS_transactions
|
|
7.2. UAC_transactions
|
|
7.3. 2xx_transactions
|
|
7.4. 3xx_transactions
|
|
7.5. 4xx_transactions
|
|
7.6. 5xx_transactions
|
|
7.7. 6xx_transactions
|
|
7.8. inuse_transactions
|
|
7.9. active_transactions
|
|
7.10. rpl_received
|
|
7.11. rpl_absorbed
|
|
7.12. rpl_relayed
|
|
7.13. rpl_generated
|
|
7.14. rpl_sent
|
|
|
|
Exported statistics are listed in the next sections. All statistics
|
|
except “inuse_transactions” can be reset.
|
|
|
|
7.1. UAS_transactions
|
|
|
|
Total number of transactions created by received requests.
|
|
|
|
7.2. UAC_transactions
|
|
|
|
Total number of transactions created by local generated requests.
|
|
|
|
7.3. 2xx_transactions
|
|
|
|
Total number of transactions completed with 2xx replies.
|
|
|
|
7.4. 3xx_transactions
|
|
|
|
Total number of transactions completed with 3xx replies.
|
|
|
|
7.5. 4xx_transactions
|
|
|
|
Total number of transactions completed with 4xx replies.
|
|
|
|
7.6. 5xx_transactions
|
|
|
|
Total number of transactions completed with 5xx replies.
|
|
|
|
7.7. 6xx_transactions
|
|
|
|
Total number of transactions completed with 6xx replies.
|
|
|
|
7.8. inuse_transactions
|
|
|
|
Number of transactions existing in memory at current time.
|
|
|
|
7.9. active_transactions
|
|
|
|
Number of ongoing transactions at current time.
|
|
|
|
7.10. rpl_received
|
|
|
|
Total number of replies received by TM module.
|
|
|
|
7.11. rpl_absorbed
|
|
|
|
Total number of replies received and not relayed by TM module.
|
|
|
|
7.12. rpl_relayed
|
|
|
|
Total number of replies received and relayed by TM module.
|
|
|
|
7.13. rpl_generated
|
|
|
|
Total number of replies locally generated and relayed by TM module.
|
|
|
|
7.14. rpl_sent
|
|
|
|
Total number of replies relayed by TM module.
|