# &adminguide;

## Overview

This module allows real-time queries against the libphonenumber to be performed from the config script. With that it is possible to get normalize and get details about a phone number.

More details about libphonenumber can be found at https://github.com/googlei18n/libphonenumber.

This module exports a new class of pseudo-variables - $phn(pvc=>key) - to enable access to the results of a query to the database.

Many queries can be done and store results in different containers to be able to use in parallel.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

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

- libphonenumber - the phone number library.

## Parameters

### `smode` (int)

Phone number search mode (not in use yet).

Default value is 0.

#### Set `smode` parameter

    ...
    modparam("phonenum", "smode", 0)
    ...

### `resid` (str)

Preregister result container id during initialization, enabling the use of the module in KEMI scripts. In native &kamailio;.cfg file, registration is done when parsing config and finding variables.

Default value is (empty).

#### Set `resid` parameter

    ...
    modparam("phonenum", "resid", "src")
    ...
    if(phonenum_match("1-484-555-8888", "src")) {
       ...
    }
    ...

## Functions

### `phonenum_match(num, pvc)`

Match num against the libphonenumber and set the attributes inside the pvc result container. The function has to be called before accessing a key via: $phn(pvc=>key).

The parameters can be static strings or strings with variables.

It can be used from ANY_ROUTE.

#### `phonenum_match` usage

    ...
    if(phonenum_match("1-484-555-8888", "src")) {
        if($phn(src=>valid)==1) {
            xlog("number normalized to: $phn(src=>normalized)\n");
        } else {
            xlog("number normalization error: $phn(src=>error)\n");
        }
    }
    ...

### `phonenum_match_cn(num, cnc, pvc)`

Match num against the libphonenumber and set the attributes inside the pvc container, restricting the rules with a country name code (two letter, e.g: "DE", "US", "ES"). The function has to be called before accessing a key via: $phn(pvc=>key).

The parameters can be static strings or strings with variables.

It can be used from ANY_ROUTE.

#### `phonenum_match_cn` usage

    ...
    if(phonenum_match_cn("1-484-555-8888", "US", "src")) {
        if($phn(src=>valid)==1) {
            xlog("number normalized to: $phn(src=>normalized)\n");
        } else {
            xlog("number normalization error: $phn(src=>error)\n");
        }
    }
    ...

## Pseudo Variables

- $phn(pvc=>key) - pvc is an identifier for this query result; it is designated by the second parameter of phonenum_match(). The key can be one of the following:

  - number - phone number that is matched

  - valid - 1 if the matched number has a valid result; 0 otherwise

  - normalized - normalized phone number

  - cctel - country code for phone number

  - ccname - country code name

  - ltype - local network type

  - ndesc - phone number description

  - error - error string if phone number matching fails.

Exported pseudo-variables are documented at &kamwikilink;.