kamailio/modules/tmx

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.