Debian Codegraph @

src/modules/app_jsdt/README

raw
1 app_jsdt 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. load (str)
29 3.2. loaddir (str)
30 3.3. mode (int)
31
32 4. Functions
33
34 4.1. jsdt_dofile(path)
35 4.2. jsdt_dostring(script)
36 4.3. jsdt_run(function, params)
37 4.4. jsdt_runstring(script)
38
39 5. RPC Commands
40
41 5.1. app_jsdt.reload
42 5.2. app_jsdt.api_list
43
44 6. Example of usage
45
46 List of Examples
47
48 1.1. Set load parameter
49 1.2. Set loaddir parameter
50 1.3. Set mode parameter
51 1.4. jsdt_dofile usage
52 1.5. jsdt_dostring usage
53 1.6. jsdt_run usage
54 1.7. jsdt_runstring usage
55
56 Chapter 1. Admin Guide
57
58 Table of Contents
59
60 1. Overview
61 2. Dependencies
62
63 2.1. Kamailio Modules
64 2.2. External Libraries or Applications
65
66 3. Parameters
67
68 3.1. load (str)
69 3.2. loaddir (str)
70 3.3. mode (int)
71
72 4. Functions
73
74 4.1. jsdt_dofile(path)
75 4.2. jsdt_dostring(script)
76 4.3. jsdt_run(function, params)
77 4.4. jsdt_runstring(script)
78
79 5. RPC Commands
80
81 5.1. app_jsdt.reload
82 5.2. app_jsdt.api_list
83
84 6. Example of usage
85
86 1. Overview
87
88 This module allows executing JavaScript scripts from the Kamailio
89 configuration file. It exports all KEMI functions to JavaScript in
90 order to access the currently processed SIP message. These functions
91 are named within the JavaScript object 'KSR'.
92
93 The module is based on the Duktape JavaScript engine
94 (http://www.duktape.org), which is a fast and easy to embed JavaScript
95 interpreter. The exported API from Kamailio to JavaScript is documented
96 in the wiki.
97
98 The module has two JavaScript contexts:
99 * first is used for functions jsdt_dofile() and jsdt_dostring().
100 * second is used for function jsdt_run() and parameter 'load' and
101 'loaddir'. Therefore jsdt_run() cannot execute functions from
102 scripts loaded via jsdt_dofile() in config. This is kind of caching
103 mode, avoiding reading file every time, but you must be sure you do
104 not have something that is executed by default and requires access
105 to SIP message. This environment is also used by KEMI framework for
106 the config SIP routing functions.
107
108 2. Dependencies
109
110 2.1. Kamailio Modules
111 2.2. External Libraries or Applications
112
113 2.1. Kamailio Modules
114
115 The following modules must be loaded before this module:
116 * none.
117
118 2.2. External Libraries or Applications
119
120 The following libraries or applications must be installed before
121 running Kamailio with this module loaded:
122 * libm - the math library (part of standard system libraries - it is
123 needed to complile embedded Duktape JS interpreter).
124
125 3. Parameters
126
127 3.1. load (str)
128 3.2. loaddir (str)
129 3.3. mode (int)
130
131 3.1. load (str)
132
133 Set the path to the JavaScript file to be loaded at startup. Then you
134 can use jsdt_run(function, params) to execute a function from the
135 script at runtime. If you use it for KEMI configuration, then it has to
136 include the required functions.
137
138 Default value is “null”.
139
140 Example 1.1. Set load parameter
141 ...
142 modparam("app_jsdt", "load", "/usr/local/etc/kamailio/js/myscript.js")
143 ...
144
145 3.2. loaddir (str)
146
147 Set the path to the folder containing JavaScript files to be loaded at
148 startup. All .js files in the folder will be loaded and combined into a
149 single javascript script. Then you can use jsdt_run(function, params)
150 to execute a function from the script at runtime. If you use it for
151 KEMI configuration, then it has to include the required functions.
152
153 Default value is “null”.
154
155 Example 1.2. Set loaddir parameter
156 ...
157 modparam("app_jsdt", "loaddir", "/usr/local/etc/kamailio/js")
158 ...
159
160 3.3. mode (int)
161
162 Control if the API to load JavaScript module (nodejs interface) is
163 initialized or not.
164
165 Default value is “1” (initialize).
166
167 Example 1.3. Set mode parameter
168 ...
169 modparam("app_jsdt", "mode", 0)
170 ...
171
172 4. Functions
173
174 4.1. jsdt_dofile(path)
175 4.2. jsdt_dostring(script)
176 4.3. jsdt_run(function, params)
177 4.4. jsdt_runstring(script)
178
179 4.1. jsdt_dofile(path)
180
181 Execute the JavaScript script stored in 'path'. The parameter can be a
182 string with pseudo-variables evaluated at runtime.
183
184 Example 1.4. jsdt_dofile usage
185 ...
186 jsdt_dofile("/usr/local/etc/kamailio/js/myscript.js");
187 ...
188
189 4.2. jsdt_dostring(script)
190
191 Execute the JavaScript script stored in parameter. The parameter can be
192 a string with pseudo-variables.
193
194 Example 1.5. jsdt_dostring usage
195 ...
196 if(!jsdt_dostring('KSR.dbg("test message\n")'))
197 {
198 xdbg("SCRIPT: failed to execute js script!\n");
199 }
200 ...
201
202 4.3. jsdt_run(function, params)
203
204 Execute the JS function 'func' giving params as parameters. There can
205 be up to 3 string parameters. The function must exist in the script
206 loaded at startup via parameter 'load'. Parameters can be strings with
207 pseudo-variables that are evaluated at runtime.
208
209 Example 1.6. jsdt_run usage
210 ...
211 if(!jsdt_run("js_append_fu_to_reply"))
212 {
213 xdbg("SCRIPT: failed to execute js function!\n");
214 }
215 ...
216 jsdt_run("js_funcx", "$rU", "2");
217 ...
218
219 4.4. jsdt_runstring(script)
220
221 Execute the JS script stored in parameter. The parameter can be a
222 string with pseudo-variables. The script is executed in JS context
223 specific to loaded JS files at startup.
224
225 Example 1.7. jsdt_runstring usage
226 ...
227 if(!jsdt_runstring('KSR.dbg("Hello World from $fU\n")'))
228 {
229 xdbg("failed to execute js script!\n");
230 }
231 ...
232
233 5. RPC Commands
234
235 5.1. app_jsdt.reload
236 5.2. app_jsdt.api_list
237
238 5.1. app_jsdt.reload
239
240 Marks the need to reload the js script. The actual reload is done by
241 every working process when the next call to jsdt_run() function or KEMI
242 config is executed.
243
244 Name: app_jsdt.reload
245
246 Parameters: none
247
248 Example:
249 ...
250 kamctl rpc app_jsdt.reload
251 ...
252
253 5.2. app_jsdt.api_list
254
255 List the functions available via Kemi framework.
256
257 Name: app_jsdt.api_list
258
259 Parameters: none
260
261 Example:
262 ...
263 kamctl rpc app_jsdt.api_list
264 ...
265
266 6. Example of usage
267
268 Create your JS script and store it on the file system, say:
269 '/usr/local/etc/kamailio/js/myscript.js'.
270 ...
271 function sr_append_fu_to_reply()
272 {
273 KSR.hdr.append_to_reply("P-From: " + KSR.pv.get("$fu") + "\r\n");
274 }
275 ...
276
277 Load the script via parameter 'load' and execute function via
278 jsdt_run(...).
279 ...
280 modparam("app_jsdt", "load", "/usr/local/etc/kamailio/js/myscript.js")
281 ...
282 request_route {
283 ...
284 if(!jsdt_run("sr_append_fu_to_reply"))
285 {
286 xdbg("SCRIPT: failed to execute js function!\n");
287 }
288 ...
289 }
290 ...