# &adminguide;

## Overview

This module translates a numerical prefix into a domain and updates accordingly the request &uri;.

The module looks up at the R-&uri; part of a message and if the user part begins with an established prefix it will update the &uri;. Updating the uri consists of: remove the prefix from the user part of the uri and keep the rest as the user part of the new uri. The host and port are changed with the domain matched for the leading prefix and the domain in From URI.

<prefix><userid><:password>@<mydomain.com> ...

and the result will be:

<userid><:password>@<domain[:port]>...

### prefix-domain translation

    prefix=123, domain(FROM)=siphub.org

    entry in database:
     sdomain=siphub.org
        domain[123]=alpha.org
        domain[124]=beta.org
        domain[125]=gamma.org

    The RURI will be updated in the following way"
    sip:12391001@mydomain.com  => sip:91001@alpha.org

The prefix could be prefixed by other digits. These digits will not be used to look up the domain (the classic example, 00 used for international calls, then follows the country prefix). For more information on this, see 'prefix' parameter.

- A sample config file is located in './doc/'.

- MySQL script to create the database needed by PDT is located in '../../scripts/mysql/pdt-create.sql'

  The database is loaded by &kamailio; only at start up time and only cache is used to lookup domains. Check the MI Functions for adding/deleting prefix-domain pairs or reloading from database at runtime.

- Sample shell scripts to manage prefix-domain pairs are also located in './doc/' (pdt_fifo_list.sh).

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- A &kamailio; database module (e.g., mysql, dbtext).

### External Libraries or Applications

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

- None.

## Parameters

### `db_url` (string)

URL of the database table to be used.

Default value is &defaultdb;.

#### Set `db_url` parameter

    ...
    modparam("pdt", "db_url", "&exampledb;")
    ...

### `db_table` (string)

Table name.

Default value is pdt.

#### Set `db_table` parameter

    ...
    modparam("pdt", "db_table", "pdt")
    ...

### `sdomain_column` (string)

Name of 'sdomain' column.

Default value is sdomain.

#### Set `sdomain_column` parameter

    ...
    modparam("pdt", "domain_column", "source_domain")
    ...

### `prefix_column` (string)

Name of 'prefix' column.

Default value is prefix.

#### Set `prefix_column` parameter

    ...
    modparam("pdt", "prefix_column", "prefix")
    ...

### `domain_column` (string)

Name of 'domain' column.

Default value is domain.

#### Set `domain_column` parameter

    ...
    modparam("pdt", "domain_column", "hostname")
    ...

### `prefix` (string)

Default leading prefix who denotes what &uri; needs to be translated - if it is NULL the module will not check the R-&uri; against it and the PDT prefix is considered starting from the first digit. Otherwise, the module will check first if the R-&uri; starts with it and will skip it to look up the domain.

Default value is NULL.

#### Set `prefix` parameter

    ...
    modparam("pdt", "prefix", "00")
    ...

### `fetch_rows` (integer)

Number of rows to be loaded in one step from database.

Default value is 1000.

#### Set `fetch_rows` parameter

    ...
    modparam("pdt", "fetch_rows", 4000)
    ...

### `char_list` (string)

The list with characters allowed in prefix.

Default value is 0123456789.

#### Set `char_list` parameter

    ...
    modparam("pdt", "char_list", "0123456789*+")
    ...

### `check_domain` (integer)

Module will check if destination domain is duplicated for same source domain (1 - check; 0 - don't check).

Default value is 1.

#### Set `check_domain` parameter

    ...
    modparam("pdt", "check_domain", 0)
    ...

### `mode` (integer)

If set to 1, duplicated prefixes are ingnored and starting continues, if 0, then starting or loading fails.

Default value is 0.

#### Set `mode` parameter

    ...
    modparam("pdt", "mode", 1)
    ...

## Functions

### `prefix2domain(rewrite_mode, multidomain_mode)`

Build a new &uri; if it is necessary. Returns 1 when the translation was made or there was nothing to translate (user part of the &uri; is empty, it does not match the prefix parameter or there is no domain associated with a possible prefix from user part). Returns -1 in error cases.

The translation is done based on lookup up for an entry in the database where the sdomain equals the domain in FROM uri, and the prefix matches the beginning of the user part of the RURI. If such an entry is found, then the domain in RURI is updated with the domain of this entry (sdomain, prefix, domain).

There is also the possibility to have the translation of &uri; regardless of source domain. This can be achieved inserting in the database entries where sdomain has the value "*".

The rewrite_mode parameter specifies whether to strip or not the prefix from user part. The possible values are:

- 0: the prefix is removed along with the leading prefix.

- 1: only the leading prefix is removed.

- 2: the user part of the URI is not changed.

- $PV : any PV holding one of the above values.

The multidomain_mode parameter specifies the kind of multidomain support to use. The possible values are:

- 0 : Translation of &uri; regardless of source domain.

- 1 : Translation of &uri; using as source domain the domain in From-URI.

- 2 : Translation of &uri; using as source domain the domain in From-URI. In case there is no entry for the required sdomain, it tries the translation using "*" as sdomain.

- $PV : any PV holding one of the above values.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `prefix2domain` usage

    ...
    prefix2domain("2", "2");
    ...
    $var(a) = 1;
    prefix2domain("$var(a)", "2");
    ...

### `prefix2domain(rewrite_mode)`

The same as prefix2domain(rewrite_mode, "0"), that is without multidomain support, translation of &uri; being done regardless of the source domain.

    ...
    prefix2domain("2");
    ...

### `prefix2domain()`

The same as prefix2domain("0", "0").

    ...
    prefix2domain();
    ...

### `pd_translate(sdomain, rewrite_mode)`

Translate R-URI based on source domain and longest prefix matching. Returns 1 when the translation was made or there was nothing to translate. Returns -1 in error cases.

The translation is done based on lookup up for an entry in the database where the sdomain parameter equals the sdomain in database table.

The sdomain parameter specifies the source domain to be used to match the longest prefix. Can be a static string or dynamic parameter with variables inside.

The rewrite_mode parameter specifies whether to strip or not the prefix from user part. The possible values are:

- 0: the prefix is removed along with the leading prefix.

- 1: only the leading prefix is removed.

- 2: the user part of the URI is not changed.

- $PV : any PV holding one of the above values.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE or BRANCH_ROUTE.

#### `pd_translate` usage

    ...
    pd_translate("$fd", "2");
    ...
    pd_translate("*", "$var(a)");
    ...

## RPC Commands

The database is loaded by &kamailio; at start up time. The module uses only the cache to look up domains. If you want to add or delete a new prefix-domain pair at runtime you have to use RPC commands. All changes made via these commands are applied to database and the cache is updated correspondingly.

### `pdt.list`

Produces a listing of the entries prefixes/domains/sdomains.

Name: pdt.list

Parameters:

- _sdomain_ : a source domain value.

- _prefix_ : a prefix value

- _domain_: a domain value

"." (dot) means NULL value

The comparison operation is 'START WITH' -- if domain is 'a' then all domains starting with 'a' are listed.

RPC Command Example:

    ...
    &kamctl; rpc pdt.list kamailio.org 123
    ...

Examples:

- pdt.list siph 2 . : Lists the entries where sdomain is starting with 'siph', prefix is starting with '2' and domain is anything

- pdt.list siph 2 : Lists the entries where sdomain is starting with 'siph', prefix is starting with '2' and domain is anything

- pdt.list . 2 open : Lists the entries where sdomain is anything, prefix starts with '2' and domain starts with 'open'.

### `pdt.reload`

Reload all sdomain-prefix-domain records from database.

Name: pdt.reload

Parameters:

- none

RPC Command Example:

    ...
    &kamctl; rpc pdt.reload
    ...