TMX Module

Daniel-Constantin Mierla

   asipto.com
   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.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. Functions

              3.1. t_cancel_branches(which)
              3.2. t_cancel_callid(callid, cseq, flag)
              3.3. t_reply_callid(callid, cseq, code, reason)
              3.4. t_flush_flags()
              3.5. t_is_failure_route()
              3.6. t_is_branch_route()
              3.7. t_suspend()
              3.8. t_continue(tindex, tlabel, rtname)

        4. Exported pseudo-variables
        5. MI Commands

              5.1. t_uac_dlg
              5.2. t_uac_cancel
              5.3. t_hash
              5.4. t_reply
              5.5. t_reply_callid

        6. Exported statistics

              6.1. received_replies
              6.2. relayed_replies
              6.3. local_replies
              6.4. UAS_transactions
              6.5. UAC_transactions
              6.6. 2xx_transactions
              6.7. 3xx_transactions
              6.8. 4xx_transactions
              6.9. 5xx_transactions
              6.10. 6xx_transactions
              6.11. inuse_transactions

   List of Examples

   1.1. t_cancel_branches usage
   1.2. t_cancel_callid usage
   1.3. t_reply_callid usage
   1.4. t_flush_flags usage
   1.5. t_is_failure_route usage
   1.6. t_is_branch_route usage
   1.7. t_suspend usage
   1.8. t_continue usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Functions

        3.1. t_cancel_branches(which)
        3.2. t_cancel_callid(callid, cseq, flag)
        3.3. t_reply_callid(callid, cseq, code, reason)
        3.4. t_flush_flags()
        3.5. t_is_failure_route()
        3.6. t_is_branch_route()
        3.7. t_suspend()
        3.8. t_continue(tindex, tlabel, rtname)

   4. Exported pseudo-variables
   5. MI Commands

        5.1. t_uac_dlg
        5.2. t_uac_cancel
        5.3. t_hash
        5.4. t_reply
        5.5. t_reply_callid

   6. Exported statistics

        6.1. received_replies
        6.2. relayed_replies
        6.3. local_replies
        6.4. UAS_transactions
        6.5. UAC_transactions
        6.6. 2xx_transactions
        6.7. 3xx_transactions
        6.8. 4xx_transactions
        6.9. 5xx_transactions
        6.10. 6xx_transactions
        6.11. inuse_transactions

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/1.5.x/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. Functions

   3.1. t_cancel_branches(which)
   3.2. t_cancel_callid(callid, cseq, flag)
   3.3. t_reply_callid(callid, cseq, code, reason)
   3.4. t_flush_flags()
   3.5. t_is_failure_route()
   3.6. t_is_branch_route()
   3.7. t_suspend()
   3.8. t_continue(tindex, tlabel, rtname)

3.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.1. t_cancel_branches usage
...
if (t_cancel_branches("all")) {
        xlog("cancelled all branches\n");
}
...

3.2.  t_cancel_callid(callid, cseq, flag)

   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.

   This function can be used in ANY_ROUTE.

   Example 1.2. t_cancel_callid usage
...
if (t_cancel_callid("123qaz", "5", "22")) {
        xlog("transaction cancelled\n");
}
...

3.3.  t_reply_callid(callid, cseq, code, reason)

   Send reply to first INVITE 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.3. t_reply_callid usage
...
if (t_reply_callid("123qaz", "5", "458", "Replied remotely")) {
        xlog("transaction replied\n");
}
...

3.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.4. t_flush_flags usage
...
t_flush_flags();
...

3.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.5. t_is_failure_route usage
...
failure_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_failure_route()) { ... }
}
...

3.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.6. t_is_branch_route usage
...
branch_route[xyz] {
    route(abc);
}

route[abc] {
    if(t_is_branch_route()) { ... }
}
...

3.7.  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.7. t_suspend usage
...
if(t_suspend())
{
    xlog("proceesing suspended in trasaction [$T(id_index):$T(id_label)]\n");
    exit;
}
...

3.8.  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.

   This function can be used in ANY_ROUTE.

   Example 1.8. t_continue usage
...
tcontinue('123', '456', 'MYROUTE');
...

4. Exported pseudo-variables

     * $T_branch_idx
     * $T_reply_code
     * $T_req(pv)
     * $T_rpl(pv)

   Exported pseudo-variables are documented at
   http://www.kamailio.org/dokuwiki/.

5. MI Commands

   5.1. t_uac_dlg
   5.2. t_uac_cancel
   5.3. t_hash
   5.4. t_reply
   5.5. t_reply_callid

5.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)

5.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.

5.3.  t_hash

   Gets information about the load of TM internal hash table.

   Parameters:
     * none

5.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)

5.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)

6. Exported statistics

   6.1. received_replies
   6.2. relayed_replies
   6.3. local_replies
   6.4. UAS_transactions
   6.5. UAC_transactions
   6.6. 2xx_transactions
   6.7. 3xx_transactions
   6.8. 4xx_transactions
   6.9. 5xx_transactions
   6.10. 6xx_transactions
   6.11. inuse_transactions

   Exported statistics are listed in the next sections. All statistics
   except “inuse_transactions” can be reset.

6.1. received_replies

   Total number of total replies received by TM module.

6.2. relayed_replies

   Total number of replies received and relayed by TM module.

6.3. local_replies

   Total number of replies local generated by TM module.

6.4. UAS_transactions

   Total number of transactions created by received requests.

6.5. UAC_transactions

   Total number of transactions created by local generated requests.

6.6. 2xx_transactions

   Total number of transactions completed with 2xx replies.

6.7. 3xx_transactions

   Total number of transactions completed with 3xx replies.

6.8. 4xx_transactions

   Total number of transactions completed with 4xx replies.

6.9. 5xx_transactions

   Total number of transactions completed with 5xx replies.

6.10. 6xx_transactions

   Total number of transactions completed with 6xx replies.

6.11. inuse_transactions

   Number of transactions existing in memory at current time.
