PHONENUM Module

Daniel-Constantin Mierla

   asipto.com

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2017 Daniel-Constantin Mierla (asipto.com)
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. smode (int)
              3.2. resid (str)

        4. Functions

              4.1. phonenum_match(num, pvc)
              4.2. phonenum_match_cn(num, cnc, pvc)

        5. Pseudo Variables

   List of Examples

   1.1. Set smode parameter
   1.2. Set resid parameter
   1.3. phonenum_match usage
   1.4. phonenum_match_cn 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. smode (int)
        3.2. resid (str)

   4. Functions

        4.1. phonenum_match(num, pvc)
        4.2. phonenum_match_cn(num, cnc, pvc)

   5. Pseudo Variables

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

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:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * libphonenumber - the phone number library.

3. Parameters

   3.1. smode (int)
   3.2. resid (str)

3.1. smode (int)

   Phone number search mode (not in use yet).

   Default value is “0”.

   Example 1.1. Set smode parameter
...
modparam("phonenum", "smode", 0)
...

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

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

4. Functions

   4.1. phonenum_match(num, pvc)
   4.2. phonenum_match_cn(num, cnc, pvc)

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

   Example 1.3. 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");
    }
}
...

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

   Note from libphonenumber library docs: country name code is the region
   that is expected the number to be from. It is only used if the number
   being parsed is not written in international format. The country code
   for the number in this case would be stored as that of the region
   supplied. If the number is guaranteed to start with a '+' followed by
   the country calling code, then region 'ZZ'.

   The parameters can be static strings or strings with variables.

   It can be used from ANY_ROUTE.

   Example 1.4. 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");
    }
}
...

5. 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 (E164) phone number
          + natnum - nationally formatted 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
   https://www.kamailio.org/wikidocs/.
