# &adminguide;

## Overview

This module provides transaction storage for the &kamailioname;. It stores in an internal table transactions for a Request-URI (R-URI) and adds branches to them later if new contacts for the AOR are added.

For each message, the module stores Request-URI (R-URI), &uri; and the internal transaction index and label.

When a transaction is destroyed by the TM module, it is removed from the module's table too.

## Dependencies

### &kamailio; modules

The following modules must be loaded before this module:

- REGISTRAR--registrar module-- used to lookup for new contacts and update the dset for the r-uri.

- TM--transaction module-- used to send &sip; requests.

- SL

### External libraries or applications

The following libraries or applications must be installed before running &kamailio; with this module:

- none.

## Parameters

### `hash_size` (integer)

The size of the hash table internally used to keep the transaction. A larger table is much faster but consumes more memory. The hash size must be a power of two, otherwise it will be rounded down to the nearest power of two.

Default value is 2048.

#### Set `hash_size` parameter

    ...
    modparam("tsilo", "hash_size", 1024)
    ...

### `use_domain` (integer)

Specify if the domain part of the URI should be also saved and used for storing and retrieving users' transactions. Useful in multi domain scenarios. Non 0 value means true.

Default value is 0.

#### Set `use_domain` parameter

    ...
    modparam("tsilo", "use_domain", 1)
    ...

## Functions

### `ts_store([uri])`

The method stores uri, tindex and tlabel of the current transaction. If the uri parameter is missing, then the value is taken from r-uri. The uri parameter can contain variables.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ts_store` usage

    ...
    if (is_method("INVITE")) {
        if (t_newtran()) {
            ts_store();
            # ts_store("sip:alice@$td");
        }
    }
    ...

### `ts_append(domain, ruri)`

The method add branches to all the stored transactions for the &sip; ruri passed as parameter, performing a contact lookup on the table specified by the domain parameter. The method should be called when a REGISTER request is received.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for looking up new contacts for r-uri.

- ruri - The r-uri for which we want to check existing transactions and add them new branches. Can be a static string value or a dynamic string with pseudo-variables.

Return codes:

- 1 - branches added.

  -1 - an internal error has produced (parsing error, memory error).

  -2 - no records found for the r-uri.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ts_append` usage

    ...
    if (is_method("REGISTER")) {
    	ts_append("location", "$tu");
    }
    ...

### `ts_append_by_contact(domain, ruri [, contact])`

Has almost the same intention as the ts_append(), but gives a possibility to append branches only for a specific location record (Contact URI). The contact's URI value can be either taken from the currently processed REGISTER or (optionally) given as a third parameter. If the Contact URI for a lookup is given as the parameter, it is possible to provide it as a pseudo-variable. The contact lookup is performed on the table specified by the domain parameter. The method should be called when a REGISTER request is received.

Meaning of the parameters is as follows:

- domain - Name of table that should be used for looking up new contacts for r-uri.

- ruri - The r-uri for which we want to check existing transactions and add them new branches. Can be a static string value or a dynamic string with pseudo-variables.

- contact - Optional, a value of the location record (contact URI) based on which to perform the branch appending. If not given, the value will be taken from the currently processed REGISTER. If a location lookup based on this Contact URI fails (no location record found), then the branch append will not happen.

Return codes:

- 1 - branches added.

  -1 - an internal error has produced (parsing error, memory error).

  -2 - no records found for the r-uri.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ts_append_by_contact` usage

    ...
    if (is_method("REGISTER")) {
    	$var(formatted_ct) = $(x_hdr(Contact){nameaddr.uri});
    	ts_append_by_contact("location", "$tu", "$var(formatted_ct)");
    }
    ...

### `ts_append_to(tindex, tlabel, domain, [uri])`

The method add branches to the transaction identified by tindex and tlabel, performing a contacts lookup on the table specified by the domain parameter. The method should be called when a REGISTER request is received.

Meaning of the parameters is as follows:

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

- domain - Name of table that should be used for looking up new contacts for r-uri.

- uri (optional) - uri for which to do lookup for new destinations.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ts_append_to` usage

    ...
    if (is_method("REGISTER")) {
    	$var(tindex) = ...
    	$var(tlabel) = ...
    	ts_append_to("$var(tindex)", "$var(tlabel)", "location");
    }
    ...

### `ts_append_branches(uri)`

Append the current internal branches to the transaction stored for the uri.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ts_append_branches` usage

    ...
        ts_append_branches("sip:alice@$td");
    ...

## RPC Commands

### `ts.dump`

Dumps the content of the TSILO table

Name: ts.dump

RPC Command Format:

    			kamctl rpc ts.dump

### `ts.lookup`

Dumps the transactions stored for the given RURI

Name: ts.lookup

RPC Command Format:

    			kamctl rpc ts.lookup sip:abcd@example.com

## Statistics

### `stored_ruris`

Number of ruris currently stored in the TSILO table.

### `stored_transactions`

Number of transactions currently stored in the TSILO table.

### `added_branches`

Total number of added branches from the startup.

### `total_ruris`

Total number of stored ruris from the startup.

### `total_transactions`

Total number of stored transactions from the startup.