Debian Codegraph @

src/modules/phonenum/README

raw
1 PHONENUM Module
2
3 Daniel-Constantin Mierla
4
5 asipto.com
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11 <[email protected]>
12
13 Copyright © 2017 Daniel-Constantin Mierla (asipto.com)
14 __________________________________________________________________
15
16 Table of Contents
17
18 1. Admin Guide
19
20 1. Overview
21 2. Dependencies
22
23 2.1. Kamailio Modules
24 2.2. External Libraries or Applications
25
26 3. Parameters
27
28 3.1. smode (int)
29 3.2. resid (str)
30
31 4. Functions
32
33 4.1. phonenum_match(num, pvc)
34 4.2. phonenum_match_cn(num, cnc, pvc)
35
36 5. Pseudo Variables
37
38 List of Examples
39
40 1.1. Set smode parameter
41 1.2. Set resid parameter
42 1.3. phonenum_match usage
43 1.4. phonenum_match_cn usage
44
45 Chapter 1. Admin Guide
46
47 Table of Contents
48
49 1. Overview
50 2. Dependencies
51
52 2.1. Kamailio Modules
53 2.2. External Libraries or Applications
54
55 3. Parameters
56
57 3.1. smode (int)
58 3.2. resid (str)
59
60 4. Functions
61
62 4.1. phonenum_match(num, pvc)
63 4.2. phonenum_match_cn(num, cnc, pvc)
64
65 5. Pseudo Variables
66
67 1. Overview
68
69 This module allows real-time queries against the libphonenumber to be
70 performed from the config script. With that it is possible to get
71 normalize and get details about a phone number.
72
73 More details about libphonenumber can be found at
74 https://github.com/googlei18n/libphonenumber.
75
76 This module exports a new class of pseudo-variables - $phn(pvc=>key) -
77 to enable access to the results of a query to the database.
78
79 Many queries can be done and store results in different containers to
80 be able to use in parallel.
81
82 2. Dependencies
83
84 2.1. Kamailio Modules
85 2.2. External Libraries or Applications
86
87 2.1. Kamailio Modules
88
89 The following modules must be loaded before this module:
90 * none.
91
92 2.2. External Libraries or Applications
93
94 The following libraries or applications must be installed before
95 running Kamailio with this module loaded:
96 * libphonenumber - the phone number library.
97
98 3. Parameters
99
100 3.1. smode (int)
101 3.2. resid (str)
102
103 3.1. smode (int)
104
105 Phone number search mode (not in use yet).
106
107 Default value is “0”.
108
109 Example 1.1. Set smode parameter
110 ...
111 modparam("phonenum", "smode", 0)
112 ...
113
114 3.2. resid (str)
115
116 Preregister result container id during initialization, enabling the use
117 of the module in KEMI scripts. In native kamailio.cfg file,
118 registration is done when parsing config and finding variables.
119
120 Default value is “” (empty).
121
122 Example 1.2. Set resid parameter
123 ...
124 modparam("phonenum", "resid", "src")
125 ...
126 if(phonenum_match("1-484-555-8888", "src")) {
127 ...
128 }
129 ...
130
131 4. Functions
132
133 4.1. phonenum_match(num, pvc)
134 4.2. phonenum_match_cn(num, cnc, pvc)
135
136 4.1. phonenum_match(num, pvc)
137
138 Match num against the libphonenumber and set the attributes inside the
139 pvc result container. The function has to be called before accessing a
140 key via: $phn(pvc=>key).
141
142 The parameters can be static strings or strings with variables.
143
144 It can be used from ANY_ROUTE.
145
146 Example 1.3. phonenum_match usage
147 ...
148 if(phonenum_match("1-484-555-8888", "src")) {
149 if($phn(src=>valid)==1) {
150 xlog("number normalized to: $phn(src=>normalized)\n");
151 } else {
152 xlog("number normalization error: $phn(src=>error)\n");
153 }
154 }
155 ...
156
157 4.2. phonenum_match_cn(num, cnc, pvc)
158
159 Match num against the libphonenumber and set the attributes inside the
160 pvc container, restricting the rules with a country name code (two
161 letter, e.g: "DE", "US", "ES"). The function has to be called before
162 accessing a key via: $phn(pvc=>key).
163
164 Note from libphonenumber library docs: country name code is the region
165 that is expected the number to be from. It is only used if the number
166 being parsed is not written in international format. The country code
167 for the number in this case would be stored as that of the region
168 supplied. If the number is guaranteed to start with a '+' followed by
169 the country calling code, then region 'ZZ'.
170
171 The parameters can be static strings or strings with variables.
172
173 It can be used from ANY_ROUTE.
174
175 Example 1.4. phonenum_match_cn usage
176 ...
177 if(phonenum_match_cn("1-484-555-8888", "US", "src")) {
178 if($phn(src=>valid)==1) {
179 xlog("number normalized to: $phn(src=>normalized)\n");
180 } else {
181 xlog("number normalization error: $phn(src=>error)\n");
182 }
183 }
184 ...
185
186 5. Pseudo Variables
187
188 * $phn(pvc=>key) - pvc is an identifier for this query result; it is
189 designated by the second parameter of phonenum_match(). The key can
190 be one of the following:
191 + number - phone number that is matched
192 + valid - 1 if the matched number has a valid result; 0
193 otherwise
194 + normalized - normalized (E164) phone number
195 + natnum - nationally formatted phone number
196 + cctel - country code for phone number
197 + ccname - country code name
198 + ltype - local network type
199 + ndesc - phone number description
200 + error - error string if phone number matching fails.
201
202 Exported pseudo-variables are documented at
203 https://www.kamailio.org/wikidocs/.