| 1 |
ERLANG Module |
| 2 |
|
| 3 |
Seudin Kasumovic |
| 4 |
|
| 5 |
<[email protected]> |
| 6 |
|
| 7 |
Edited by |
| 8 |
|
| 9 |
Seudin Kasumovic |
| 10 |
|
| 11 |
<[email protected]> |
| 12 |
|
| 13 |
Copyright © 2015 Bicom Systems Ltd. |
| 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. no_cnodes (int) |
| 29 |
3.2. cnode_alivename (str) |
| 30 |
3.3. cnode_host (str) |
| 31 |
3.4. erlang_nodename (str) |
| 32 |
3.5. cookie (str) |
| 33 |
3.6. trace_level (int) |
| 34 |
3.7. rpc_reply_with_struct (int) |
| 35 |
|
| 36 |
4. Exported pseudo variables |
| 37 |
|
| 38 |
4.1. Overview |
| 39 |
4.2. Attributes |
| 40 |
4.3. $erl_atom(name) |
| 41 |
4.4. $erl_list(name) |
| 42 |
4.5. $erl_tuple(name) |
| 43 |
4.6. $erl_pid(name) |
| 44 |
4.7. $erl_ref(name) |
| 45 |
4.8. $erl_xbuff(name) |
| 46 |
|
| 47 |
5. Functions |
| 48 |
|
| 49 |
5.1. erl_rpc(mod, fun, args, reply) |
| 50 |
5.2. erl_reg_send(server, msg) |
| 51 |
5.3. erl_send(pid, msg) |
| 52 |
5.4. erl_reply(msg) |
| 53 |
|
| 54 |
6. Event routes |
| 55 |
|
| 56 |
6.1. Registered pseudo process |
| 57 |
6.2. event_route[erlang:self] |
| 58 |
|
| 59 |
2. Using Kamailio from Erlang |
| 60 |
|
| 61 |
1. RPC calls from Erlang |
| 62 |
|
| 63 |
3. Developer Guide |
| 64 |
|
| 65 |
1. Available Functions |
| 66 |
|
| 67 |
1.1. erl_load_api(erl_api) |
| 68 |
1.2. rpc(reply, module, function, args) |
| 69 |
1.3. reg_send(server, msg) |
| 70 |
1.4. send(pid, msg) |
| 71 |
1.5. reply(msg) |
| 72 |
1.6. xavp2xbuff(xbuff, xavp) |
| 73 |
1.7. xbuff2xavp(xavp, xbuff) |
| 74 |
|
| 75 |
List of Examples |
| 76 |
|
| 77 |
1.1. Set no_cnodes parameter |
| 78 |
1.2. Set cnode_alivename parameter |
| 79 |
1.3. Set cnode_host parameter |
| 80 |
1.4. Set erlang_nodename parameter |
| 81 |
1.5. Set cookie parameter |
| 82 |
1.6. Set trace_level parameter |
| 83 |
1.7. Example of using attribute length |
| 84 |
1.8. Example of using attributes type and format |
| 85 |
1.9. Example set and print to log $erl_atom |
| 86 |
1.10. Example of using $erl_list |
| 87 |
1.11. Example of using erl_tuple |
| 88 |
1.12. Example of using $erl_pid |
| 89 |
1.13. Example of using erl_ref |
| 90 |
1.14. Example of using $erl_xbuff |
| 91 |
1.15. Example of using erl_rpc |
| 92 |
1.16. Example of using erl_reg_send |
| 93 |
1.17. Example of using erl_send |
| 94 |
1.18. Example of use erl_reply |
| 95 |
1.19. Example of registered process |
| 96 |
1.20. Example of using default event route |
| 97 |
2.1. Example of RPC call from erlang shell with no response |
| 98 |
2.2. Example, check is line registered |
| 99 |
2.3. Example get config variable |
| 100 |
2.4. Example get dialog statistics |
| 101 |
3.1. Example of using API |
| 102 |
|
| 103 |
Chapter 1. Admin Guide |
| 104 |
|
| 105 |
Table of Contents |
| 106 |
|
| 107 |
1. Overview |
| 108 |
2. Dependencies |
| 109 |
|
| 110 |
2.1. Kamailio Modules |
| 111 |
2.2. External Libraries or Applications |
| 112 |
|
| 113 |
3. Parameters |
| 114 |
|
| 115 |
3.1. no_cnodes (int) |
| 116 |
3.2. cnode_alivename (str) |
| 117 |
3.3. cnode_host (str) |
| 118 |
3.4. erlang_nodename (str) |
| 119 |
3.5. cookie (str) |
| 120 |
3.6. trace_level (int) |
| 121 |
3.7. rpc_reply_with_struct (int) |
| 122 |
|
| 123 |
4. Exported pseudo variables |
| 124 |
|
| 125 |
4.1. Overview |
| 126 |
4.2. Attributes |
| 127 |
4.3. $erl_atom(name) |
| 128 |
4.4. $erl_list(name) |
| 129 |
4.5. $erl_tuple(name) |
| 130 |
4.6. $erl_pid(name) |
| 131 |
4.7. $erl_ref(name) |
| 132 |
4.8. $erl_xbuff(name) |
| 133 |
|
| 134 |
5. Functions |
| 135 |
|
| 136 |
5.1. erl_rpc(mod, fun, args, reply) |
| 137 |
5.2. erl_reg_send(server, msg) |
| 138 |
5.3. erl_send(pid, msg) |
| 139 |
5.4. erl_reply(msg) |
| 140 |
|
| 141 |
6. Event routes |
| 142 |
|
| 143 |
6.1. Registered pseudo process |
| 144 |
6.2. event_route[erlang:self] |
| 145 |
|
| 146 |
1. Overview |
| 147 |
|
| 148 |
Erlang is a general-purpose programming language and runtime |
| 149 |
environment. Erlang has built-in support for concurrency, distribution |
| 150 |
and fault tolerance. This module provides interact with Erlang node. |
| 151 |
The module allows sending, receiving Erlang messages and RPC calls |
| 152 |
between each other. |
| 153 |
|
| 154 |
2. Dependencies |
| 155 |
|
| 156 |
2.1. Kamailio Modules |
| 157 |
2.2. External Libraries or Applications |
| 158 |
|
| 159 |
2.1. Kamailio Modules |
| 160 |
|
| 161 |
The following modules must be loaded before this module: |
| 162 |
* None |
| 163 |
|
| 164 |
2.2. External Libraries or Applications |
| 165 |
|
| 166 |
The following libraries or applications must be installed before |
| 167 |
running Kamailio with this module loaded: |
| 168 |
* ei - Erlang interface C library. |
| 169 |
The routines for handling the Erlang binary term format and |
| 170 |
communicate with with distributed Erlang. For more details see |
| 171 |
Erlang Interface Reference Manual |
| 172 |
* epmd - Erlang Port Mapper Daemon. |
| 173 |
This daemon acts as a name server on all hosts involved in |
| 174 |
distributed Erlang computations. For more details see Erlang Port |
| 175 |
Mapper Daemon Manual. |
| 176 |
|
| 177 |
epmd must running on the same host where Kamailio is running. Erlang |
| 178 |
does not need to be installed on the same host where Kamailio is |
| 179 |
running. |
| 180 |
|
| 181 |
3. Parameters |
| 182 |
|
| 183 |
3.1. no_cnodes (int) |
| 184 |
3.2. cnode_alivename (str) |
| 185 |
3.3. cnode_host (str) |
| 186 |
3.4. erlang_nodename (str) |
| 187 |
3.5. cookie (str) |
| 188 |
3.6. trace_level (int) |
| 189 |
3.7. rpc_reply_with_struct (int) |
| 190 |
|
| 191 |
3.1. no_cnodes (int) |
| 192 |
|
| 193 |
Number of erlang C node processes to be started to handle the |
| 194 |
communication tasks. A C node is a C program written to act as a hidden |
| 195 |
node in a distributed Erlang system. |
| 196 |
|
| 197 |
Default value is 1. |
| 198 |
|
| 199 |
Example 1.1. Set no_cnodes parameter |
| 200 |
... |
| 201 |
modparam("erlang", "no_cnodes", 2) |
| 202 |
... |
| 203 |
|
| 204 |
3.2. cnode_alivename (str) |
| 205 |
|
| 206 |
alivename is the registered name of the Kamailio process. |
| 207 |
|
| 208 |
Note, if the no_cnodes is greater than 1, then alivename of Kamailio |
| 209 |
process will be suffixed with number. |
| 210 |
|
| 211 |
Example 1.2. Set cnode_alivename parameter |
| 212 |
... |
| 213 |
modparam("erlang", "cnode_alivename", "proxy") |
| 214 |
... |
| 215 |
|
| 216 |
3.3. cnode_host (str) |
| 217 |
|
| 218 |
C node host is the name of the machine we're running on. If long names |
| 219 |
are to be used, it should be fully qualified. |
| 220 |
|
| 221 |
Example 1.3. Set cnode_host parameter |
| 222 |
... |
| 223 |
modparam("erlang", "cnode_host", "kamailio.lan") |
| 224 |
... |
| 225 |
|
| 226 |
3.4. erlang_nodename (str) |
| 227 |
|
| 228 |
The format of the node name is a name@host where name is the name given |
| 229 |
by the user and host is the full host name if long names are used, or |
| 230 |
the first part of the host name if short names are used. |
| 231 |
|
| 232 |
Example 1.4. Set erlang_nodename parameter |
| 233 |
... |
| 234 |
modparam("erlang", "erlang_nodename", "[email protected]") |
| 235 |
... |
| 236 |
|
| 237 |
3.5. cookie (str) |
| 238 |
|
| 239 |
Each node has its own magic cookie. When a nodes tries to connect to |
| 240 |
another node, the magic cookies are compared If they do not match, the |
| 241 |
connected node rejects the connection. |
| 242 |
|
| 243 |
Example 1.5. Set cookie parameter |
| 244 |
... |
| 245 |
modparam("erlang", "cookie", "secretcookie") |
| 246 |
... |
| 247 |
|
| 248 |
3.6. trace_level (int) |
| 249 |
|
| 250 |
Used to set tracing on the distribution. The parameter is different |
| 251 |
verbosity level. A higher level means more information. Useful in |
| 252 |
development, but in production should be disabled. |
| 253 |
|
| 254 |
The different tracelevels has the following messages: |
| 255 |
1. Verbose error messages |
| 256 |
2. Above messages and verbose warning messages |
| 257 |
3. Above messages and progress reports for connection handling |
| 258 |
4. Above messages and progress reports for communication |
| 259 |
5. Above messages and progress reports for data conversion |
| 260 |
|
| 261 |
Default value is 0, no verbose is set. To see trace log on stdout, |
| 262 |
Kamailio must be started with -E option. |
| 263 |
|
| 264 |
Example 1.6. Set trace_level parameter |
| 265 |
... |
| 266 |
modparam("erlang", "trace_level", 5) |
| 267 |
... |
| 268 |
|
| 269 |
3.7. rpc_reply_with_struct (int) |
| 270 |
|
| 271 |
Prepend Erlang atom struct in RPC Kamailio reply where RPC struct is |
| 272 |
generated. Some libraries for converting erlang term in JSON require |
| 273 |
atom struct as first element in tuple to convert list of properties |
| 274 |
into javscript object. |
| 275 |
Default value is 0 (disabled). |
| 276 |
|
| 277 |
4. Exported pseudo variables |
| 278 |
|
| 279 |
4.1. Overview |
| 280 |
4.2. Attributes |
| 281 |
4.3. $erl_atom(name) |
| 282 |
4.4. $erl_list(name) |
| 283 |
4.5. $erl_tuple(name) |
| 284 |
4.6. $erl_pid(name) |
| 285 |
4.7. $erl_ref(name) |
| 286 |
4.8. $erl_xbuff(name) |
| 287 |
|
| 288 |
4.1. Overview |
| 289 |
|
| 290 |
Erlang provides a number of data types but not all of them are |
| 291 |
supported by Kamailio. This module provides several of them as pseudo |
| 292 |
variables. These pseudo variables allow user to create Erlang message |
| 293 |
or function arguments and receive result from Erlang node. Some Erlang |
| 294 |
variables can contain other data types, so we introduced several |
| 295 |
attributes to determine type, length, or get formatted output useful |
| 296 |
for debug, quick compare or put into the log. |
| 297 |
|
| 298 |
4.2. Attributes |
| 299 |
|
| 300 |
Exported pseudo variable has several attributes to get type, length and |
| 301 |
formatted output readable by transformations or user. Pseudo variable |
| 302 |
by self determine variable type, but we need to know what type on some |
| 303 |
position is. |
| 304 |
* type |
| 305 |
get variable type. Possible types are: atom, integer, list, string, |
| 306 |
tuple, pid and ref. |
| 307 |
* length |
| 308 |
get length of list or tuple. |
| 309 |
* format |
| 310 |
Prints a term, in clear text. It tries to resemble the term |
| 311 |
printing in the Erlang shell. |
| 312 |
|
| 313 |
Example 1.7. Example of using attribute length |
| 314 |
... |
| 315 |
xlogl("L_DEBUG","The number of elements in list L: $erl_list(L=>length)\n"); |
| 316 |
xlogl("L_DEBUG","The number of elements in tuple T: $erl_tuple(T=>length)\n"); |
| 317 |
... |
| 318 |
|
| 319 |
> example of log output: |
| 320 |
|
| 321 |
DEBUG: <script>: 120:The number of elements in list L: 4 |
| 322 |
DEBUG: <script>: 121:The number of elements in tuple T: 2 |
| 323 |
... |
| 324 |
|
| 325 |
Example 1.8. Example of using attributes type and format |
| 326 |
... |
| 327 |
xlogl("L_DEBUG","list L in clear text: $erl_list(L=>format), the type at index 2 |
| 328 |
: $erl_list(L[2]=>type)\n"); |
| 329 |
xlogl("L_DEBUG","tuple T in clear text: $erltuple(T=>format), the type at index |
| 330 |
1: $erl_tuple[T[1]=>type)\n"); |
| 331 |
... |
| 332 |
|
| 333 |
> example of log output: |
| 334 |
|
| 335 |
DEBUG: <script>: 130:list L in clear text: [example, list, 4, "items"], the type |
| 336 |
at index 2: integer |
| 337 |
DEBUG: <script>: 131:tuple T in clear text: {example, tuple}, the type at index |
| 338 |
1: atom |
| 339 |
... |
| 340 |
|
| 341 |
4.3. $erl_atom(name) |
| 342 |
|
| 343 |
erl_atom pseudo variable allows create analog to Erlang atom data type. |
| 344 |
Erlang atom is a literal, a constant with name. Formatted output pseudo |
| 345 |
variable atom could be enclosed in single quotes (') if it does not |
| 346 |
begin with a lower-case letter or if it contains other characters than |
| 347 |
alphanumeric characters, underscore (_), or @. |
| 348 |
|
| 349 |
Example 1.9. Example set and print to log $erl_atom |
| 350 |
... |
| 351 |
$erl_atom(A) = "badrpc"; |
| 352 |
xlogl("L_DEBUG","$$erl_atom(A): $erl_atom(A=>format)\n"); |
| 353 |
... |
| 354 |
|
| 355 |
> log output is: |
| 356 |
|
| 357 |
DEBUG: <script>: 123:$erl_atom(A): badrpc |
| 358 |
... |
| 359 |
|
| 360 |
4.4. $erl_list(name) |
| 361 |
|
| 362 |
Compound data type with a variable number of terms. Formally, a list is |
| 363 |
either the empty list [] or consists of one or more elements. |
| 364 |
|
| 365 |
Behavior of the list is the same as AVP variable. Set value without |
| 366 |
index prepends element on list. You are able to replace element at |
| 367 |
given index. List supports [*] index to get whole list or reset all |
| 368 |
elements in the list. To create empty list set whole list to $null. |
| 369 |
|
| 370 |
Example 1.10. Example of using $erl_list |
| 371 |
... |
| 372 |
$erl_atom(E) = "example"; |
| 373 |
$erl_list(L) = "list"; |
| 374 |
$erl_list(L) = "of"; |
| 375 |
$erl_list(L) = $erl_atom(E); |
| 376 |
|
| 377 |
xlogl("L_DEBUG","length(L): $erl_list(L=>length), format(L): $erl_list(L=>format |
| 378 |
)\n"); |
| 379 |
|
| 380 |
# empty list |
| 381 |
$erl_tuple(E[*]) = $null; |
| 382 |
|
| 383 |
xlogl("L_DEBUG","length(E): $erl_list(E=>length), format(E): $erl_list(L=>format |
| 384 |
)\n"); |
| 385 |
... |
| 386 |
|
| 387 |
> log output is: |
| 388 |
|
| 389 |
DEBUG: <script>: 143:length(L): 3, format(L): [example, "of", "list"] |
| 390 |
DEBUG: <script>: 148:length(E): 0, format(E): [] |
| 391 |
... |
| 392 |
|
| 393 |
4.5. $erl_tuple(name) |
| 394 |
|
| 395 |
From the Erlang point of view the tuple compound data type with a fixed |
| 396 |
number of terms. The module implementation of tuple has the same |
| 397 |
behavior as the list. |
| 398 |
|
| 399 |
Example 1.11. Example of using erl_tuple |
| 400 |
... |
| 401 |
$erl_atom(line) = "line"; |
| 402 |
$erl_atom(id) = "id"; |
| 403 |
$erl_atom(owner)= "owner"; |
| 404 |
|
| 405 |
$var(user) = "Bob"; |
| 406 |
|
| 407 |
$erl_tuple(owner) = $var(user); |
| 408 |
$erl_tuple(owner) = $erl_atom(owner); |
| 409 |
|
| 410 |
$erl_tuple(id) = 23; |
| 411 |
$erl_tuple(id) = $erl_atom(id); |
| 412 |
|
| 413 |
$erl_list(L) = $erl_tuple(owner); |
| 414 |
$erl_list(L) = $erl_tuple(id); |
| 415 |
|
| 416 |
$erl_tuple(T) = $erl_list(L); |
| 417 |
$erl_tuple(T) = $erl_atom(line); |
| 418 |
|
| 419 |
xlogl("L_DEBUG","length(T): $erl_tuple(T=>length), format(T): $erl_tuple(T=>form |
| 420 |
at)\n"); |
| 421 |
... |
| 422 |
|
| 423 |
> log output is: |
| 424 |
... |
| 425 |
DEBUG: <script>: 153:length(T): 2, format(T): {line, [{id, 23}, {owner, "Bob"}]} |
| 426 |
... |
| 427 |
|
| 428 |
4.6. $erl_pid(name) |
| 429 |
|
| 430 |
erl_pid holds Eralng process identifier. Provides access to Erlang PID |
| 431 |
value and could be used in send message. |
| 432 |
|
| 433 |
Example 1.12. Example of using $erl_pid |
| 434 |
... |
| 435 |
if ($erl_xbuff(msg[0]=>type) == "pid") { |
| 436 |
$erl_pid(pid) = $erl_xbuff(msg[0]); |
| 437 |
xlogl("L_INFO","Received PID: $erl_pid(pid=>format)\n"); |
| 438 |
} |
| 439 |
... |
| 440 |
|
| 441 |
4.7. $erl_ref(name) |
| 442 |
|
| 443 |
erl_ref holds Erlang reference. Provides access to reference value and |
| 444 |
could be used in send message. |
| 445 |
|
| 446 |
Example 1.13. Example of using erl_ref |
| 447 |
... |
| 448 |
if ($erl_xbuff(msg[0]=>type) == "ref") { |
| 449 |
$erl_ref(ref) = $erl_xbuff(msg[0]); |
| 450 |
xlogl("L_INFO","Reference: $erl_ref(ref=>format)\n"); |
| 451 |
} |
| 452 |
... |
| 453 |
|
| 454 |
4.8. $erl_xbuff(name) |
| 455 |
|
| 456 |
erl_xbuff is created as generic pseudo variable to acts as other pseudo |
| 457 |
variables exported from module. It's useful when in advance we don't |
| 458 |
know what variable type to expect. The behavior of variable depends of |
| 459 |
initialization. Module functions expect this PV as return value, and PV |
| 460 |
for incoming Erlang message. |
| 461 |
|
| 462 |
Example 1.14. Example of using $erl_xbuff |
| 463 |
... |
| 464 |
# Tuple T from previous example |
| 465 |
|
| 466 |
$erl_xbuff(X) = $erl_tuple(T); |
| 467 |
|
| 468 |
xlogl("L_DEBUG","typeof(X): $erl_xbuff(X=>type), length(X): $erl_xbuff(X=>length |
| 469 |
), format(X): $erl_xbuff(X=>format)\n"); |
| 470 |
... |
| 471 |
|
| 472 |
> log output is: |
| 473 |
... |
| 474 |
DEBUG: <script>: 410:typeof(X): tuple, length(X): 2, format(X): {line, [{id, 23} |
| 475 |
, {owner, "Bob"}]} |
| 476 |
... |
| 477 |
|
| 478 |
5. Functions |
| 479 |
|
| 480 |
5.1. erl_rpc(mod, fun, args, reply) |
| 481 |
5.2. erl_reg_send(server, msg) |
| 482 |
5.3. erl_send(pid, msg) |
| 483 |
5.4. erl_reply(msg) |
| 484 |
|
| 485 |
5.1. erl_rpc(mod, fun, args, reply) |
| 486 |
|
| 487 |
This function supports calling Erlang functions on remote nodes. |
| 488 |
|
| 489 |
The parameter mod and fun are module and function name respectively. It |
| 490 |
can be a static string or a dynamic string value with config variables. |
| 491 |
|
| 492 |
The parameter args is list of arguments passed to function, so it must |
| 493 |
be list, or xbuff that contains list. |
| 494 |
|
| 495 |
The parameter reply is result from RPC call. It must be xbuff to accept |
| 496 |
any result. |
| 497 |
|
| 498 |
Function returns false on error to send or wrong arguments passed to |
| 499 |
function. If executing remote function caused error function still |
| 500 |
returns true but error is encoded into repl parameter. |
| 501 |
|
| 502 |
Example 1.15. Example of using erl_rpc |
| 503 |
... |
| 504 |
# example of call erlang:list_to_tuple(["one","two"]) |
| 505 |
# on remote node |
| 506 |
|
| 507 |
$erl_list(L) = "two"; |
| 508 |
$erl_list(L) = "one"; |
| 509 |
|
| 510 |
# put list into list |
| 511 |
$erl_list(args) = $erl_list(L); |
| 512 |
|
| 513 |
erl_rpc("erlang", "list_to_tuple", "$erl_list(args)", "$erl_xbuff(repl)"); |
| 514 |
|
| 515 |
xlogl("L_DEBUG","type(repl): $erl_xbuff(repl=>type), format(repl): $erl_xbuff(re |
| 516 |
pl=>format)\n"); |
| 517 |
|
| 518 |
> log output: |
| 519 |
... |
| 520 |
DEBUG: <script>: 386:type(repl): tuple, format(repl): {"one", "two"} |
| 521 |
... |
| 522 |
|
| 523 |
5.2. erl_reg_send(server, msg) |
| 524 |
|
| 525 |
This function sends an Erlang term to a registered process. |
| 526 |
|
| 527 |
The argument server is the registered name of the intended recipient |
| 528 |
process on remote node. |
| 529 |
|
| 530 |
The argument msg is containing the message to be sent. |
| 531 |
|
| 532 |
Example 1.16. Example of using erl_reg_send |
| 533 |
... |
| 534 |
# example of send message to registered process |
| 535 |
# {notifier,'[email protected]'} ! {example,message} |
| 536 |
|
| 537 |
$erl_atom(example) = "example"; |
| 538 |
$erl_atom(message) = "message"; |
| 539 |
|
| 540 |
$erl_tuple(M) = $erl_atom(message); |
| 541 |
$erl_tuple(M) = $erl_atom(example); |
| 542 |
|
| 543 |
erl_reg_send("notifier","$erl_tuple(M)"); |
| 544 |
... |
| 545 |
|
| 546 |
5.3. erl_send(pid, msg) |
| 547 |
|
| 548 |
This function sends an Erlang term to a process. This function can be |
| 549 |
used from ANY_ROUTE. The argument pid is the Erlang process id of the |
| 550 |
intended recipient process on remote node. The argument msg is |
| 551 |
containing the message to be sent. |
| 552 |
|
| 553 |
Example 1.17. Example of using erl_send |
| 554 |
... |
| 555 |
# example of send message to process |
| 556 |
# Pid ! {example,message} |
| 557 |
|
| 558 |
$erl_atom(notifier) = "notifier"; |
| 559 |
$erl_list(args) = $erl_atom(notifier); |
| 560 |
|
| 561 |
erl_rpc("erlang", "whereis", "$erl_list(args)", "$erl_xbuff(pid)"); |
| 562 |
|
| 563 |
$erl_atom(example) = "example"; |
| 564 |
$erl_atom(message) = "message"; |
| 565 |
|
| 566 |
$erl_tuple(M) = $erl_atom(message); |
| 567 |
$erl_tuple(M) = $erl_atom(example); |
| 568 |
|
| 569 |
erl_send("$erl_xbuff(pid)","$erl_tuple(M)"); |
| 570 |
... |
| 571 |
|
| 572 |
5.4. erl_reply(msg) |
| 573 |
|
| 574 |
Function to send message from event route (pseudo process). Function |
| 575 |
sends reply message msg to the sender process. |
| 576 |
|
| 577 |
Example 1.18. Example of use erl_reply |
| 578 |
... |
| 579 |
# event route acts as registered process |
| 580 |
event_route[erlang:greetings] { |
| 581 |
|
| 582 |
xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n"); |
| 583 |
|
| 584 |
$erl_atom(hello) = "hello"; |
| 585 |
$erl_tuple(reply) = "Erlang"; |
| 586 |
$erl_tuple(reply) = $erl_atom(hello); |
| 587 |
|
| 588 |
# reply greeting |
| 589 |
erl_reply("$erl_tuple(reply)"); |
| 590 |
} |
| 591 |
... |
| 592 |
|
| 593 |
%% in erlang shell |
| 594 |
|
| 595 |
([email protected])24> {greetings,'[email protected]'} ! {hello,"Kamailio"}. |
| 596 |
{hello,"Kamailio"} |
| 597 |
([email protected])25> flush(). |
| 598 |
Shell got {hello,"Erlang"} |
| 599 |
ok |
| 600 |
|
| 601 |
> logged info message: |
| 602 |
INFO: <script>: 951:Received message: {"hello", "Kamailio"} |
| 603 |
> |
| 604 |
|
| 605 |
6. Event routes |
| 606 |
|
| 607 |
6.1. Registered pseudo process |
| 608 |
6.2. event_route[erlang:self] |
| 609 |
|
| 610 |
To allow Kamailio C node to have similar to erlang registered processes |
| 611 |
we can use event routes. Event routes executed when asynchronous |
| 612 |
message received from erlang node. |
| 613 |
|
| 614 |
Event route receives message in $erl_xbuff(msg) and sender process in |
| 615 |
$erl_xbuff(pid). Reply message is optional and can be sent with |
| 616 |
erl_reply. |
| 617 |
|
| 618 |
6.1. Registered pseudo process |
| 619 |
|
| 620 |
To create pseudo erlang registered process in Kamailio script create |
| 621 |
event route in form of event_route[erlang:<my_process_name>]. Where |
| 622 |
<my_process_name> is the name of pseudo process. |
| 623 |
|
| 624 |
Example 1.19. Example of registered process |
| 625 |
... |
| 626 |
# event route acts as registered process |
| 627 |
event_route[erlang:handler] { |
| 628 |
|
| 629 |
xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n"); |
| 630 |
|
| 631 |
} |
| 632 |
... |
| 633 |
|
| 634 |
%% in erlang shell send message to registered process |
| 635 |
|
| 636 |
([email protected])12> {handler,'[email protected]'} ! {"hello","Kamailio"}. |
| 637 |
{"hello","Kamailio"} |
| 638 |
|
| 639 |
> logged info message: |
| 640 |
INFO: <script>: 951:Received message: {"hello", "Kamailio"} |
| 641 |
> |
| 642 |
|
| 643 |
6.2. event_route[erlang:self] |
| 644 |
|
| 645 |
The reserved pseudo process name to receive messages sent to Kamailio C |
| 646 |
node. The message are sent to non registered process. |
| 647 |
|
| 648 |
Example 1.20. Example of using default event route |
| 649 |
... |
| 650 |
# default event route from erlang |
| 651 |
event_route[erlang:self] { |
| 652 |
|
| 653 |
xlogl("L_INFO","Received message: $erl_xbuff(msg=>format)\n"); |
| 654 |
|
| 655 |
if(pv_isset("$erl_xbuff(msg[1])") && $erl_xbuff(msg[1]=>type) == "pid") |
| 656 |
{ |
| 657 |
xlogl("L_INFO","Echo reply to: $erl_xbuff(msg[1]=>format)\n"); |
| 658 |
erl_send("$erl_xbuff(msg[1])","$erl_xbuff(msg[0])"); |
| 659 |
} |
| 660 |
} |
| 661 |
... |
| 662 |
|
| 663 |
%% in erlang shell send message to registered process |
| 664 |
|
| 665 |
([email protected])12> Pid=rpc:call('[email protected]',erlang,whereis,[self]). |
| 666 |
<14808.9.0> |
| 667 |
([email protected])14> Pid ! ["hello from",self()]. |
| 668 |
["hello from",<0.247.0>] |
| 669 |
([email protected])15> flush(). |
| 670 |
Shell got "hello from" |
| 671 |
ok |
| 672 |
|
| 673 |
> logged info messages: |
| 674 |
INFO: <script>: 653:Received message: ["hello from", <[email protected]>] |
| 675 |
INFO: <script>: 656:Echo reply to: <[email protected]>] |
| 676 |
> |
| 677 |
|
| 678 |
Chapter 2. Using Kamailio from Erlang |
| 679 |
|
| 680 |
Table of Contents |
| 681 |
|
| 682 |
1. RPC calls from Erlang |
| 683 |
|
| 684 |
1. RPC calls from Erlang |
| 685 |
|
| 686 |
This module implements the erlang transport and encoding interface for |
| 687 |
Kamailio RPCs. It's allowed to call any exported RPC in Kamailio from |
| 688 |
erlang node. |
| 689 |
|
| 690 |
The string in RPC response is binary encoded to allow from erlang side |
| 691 |
conversion into appropriate encoding and further transformations. |
| 692 |
|
| 693 |
Here are some examples: |
| 694 |
|
| 695 |
Example 2.1. Example of RPC call from erlang shell with no response |
| 696 |
([email protected])26> rpc:call('[email protected]',domain,reload,[]). |
| 697 |
ok |
| 698 |
|
| 699 |
Example 2.2. Example, check is line registered |
| 700 |
([email protected])29> rpc:call('[email protected]',ul,lookup,["location","1001@ |
| 701 |
orange.voip"]). |
| 702 |
[{[{<<"Contact">>, |
| 703 |
{[{<<"Address">>, |
| 704 |
<<"sip:[email protected]:5161;transport=udp">>}, |
| 705 |
{<<"Expires">>,96}, |
| 706 |
{<<"Q">>,-1.0}, |
| 707 |
{<<"Call-ID">>,<<"[email protected]">>}, |
| 708 |
{<<"CSeq">>,10335}, |
| 709 |
{<<"User-Agent">>,<<"Grandstream GXP2000 1.2.5.3">>}, |
| 710 |
{<<"Received">>,<<"sip:198.51.100.137:62770">>}, |
| 711 |
{<<"Path">>, |
| 712 |
<<"<sip:172.16.23.130;lr;received=sip:198.51.100.137:62"...>>}, |
| 713 |
{<<"State">>,<<"CS_SYNC">>}, |
| 714 |
{<<"Flags">>,0}, |
| 715 |
{<<"CFlags">>,64}, |
| 716 |
{<<"Socket">>,<<"udp:172.16.23.130:5070">>}, |
| 717 |
{<<"Methods">>,8159}, |
| 718 |
{<<"Ruid">>,<<"uloc-5534a79b-37ea-8">>}, |
| 719 |
{<<"Instance">>,<<"[not set]">>}, |
| 720 |
{<<"Reg-Id">>,0}, |
| 721 |
{<<"Last-Keepalive">>,1429543986}, |
| 722 |
{<<"Last-Modified">>,1429543906}]}}]}] |
| 723 |
|
| 724 |
Example 2.3. Example get config variable |
| 725 |
([email protected])26> rpc:call('[email protected]',"cfg","get",["registrar","bi |
| 726 |
ndip"]). |
| 727 |
[<<"172.16.23.130">>] |
| 728 |
|
| 729 |
Example 2.4. Example get dialog statistics |
| 730 |
([email protected])26>rpc:call('[email protected]',"stats","get_statistics",["di |
| 731 |
alog:"]). |
| 732 |
[<<"dialog:active_dialogs = 3">>, |
| 733 |
<<"dialog:early_dialogs = 0">>, |
| 734 |
<<"dialog:expired_dialogs = 0">>, |
| 735 |
<<"dialog:failed_dialogs = 2">>, |
| 736 |
<<"dialog:processed_dialogs = 15">>] |
| 737 |
|
| 738 |
Chapter 3. Developer Guide |
| 739 |
|
| 740 |
Table of Contents |
| 741 |
|
| 742 |
1. Available Functions |
| 743 |
|
| 744 |
1.1. erl_load_api(erl_api) |
| 745 |
1.2. rpc(reply, module, function, args) |
| 746 |
1.3. reg_send(server, msg) |
| 747 |
1.4. send(pid, msg) |
| 748 |
1.5. reply(msg) |
| 749 |
1.6. xavp2xbuff(xbuff, xavp) |
| 750 |
1.7. xbuff2xavp(xavp, xbuff) |
| 751 |
|
| 752 |
1. Available Functions |
| 753 |
|
| 754 |
1.1. erl_load_api(erl_api) |
| 755 |
1.2. rpc(reply, module, function, args) |
| 756 |
1.3. reg_send(server, msg) |
| 757 |
1.4. send(pid, msg) |
| 758 |
1.5. reply(msg) |
| 759 |
1.6. xavp2xbuff(xbuff, xavp) |
| 760 |
1.7. xbuff2xavp(xavp, xbuff) |
| 761 |
|
| 762 |
1.1. erl_load_api(erl_api) |
| 763 |
|
| 764 |
Function to be called directly from other modules to load the API. On |
| 765 |
success return 0, on error 1. |
| 766 |
|
| 767 |
Meaning of the parameters is as follows: |
| 768 |
* erl_api_t* erl_api - API bindings structure. |
| 769 |
|
| 770 |
1.2. rpc(reply, module, function, args) |
| 771 |
|
| 772 |
This function supports calling Erlang functions on remote nodes. On |
| 773 |
success function returns 0. |
| 774 |
|
| 775 |
Meaning of parameters is as follows: |
| 776 |
* ei_x_buff* reply - dynamic ei buffer where RPC reply returns. |
| 777 |
* str *module - string containing module name. |
| 778 |
* str *function - string containing function name. |
| 779 |
* ei_x_buff *args - dynamic ei buffer with encoded arguments. |
| 780 |
|
| 781 |
1.3. reg_send(server, msg) |
| 782 |
|
| 783 |
This function sends an Erlang term to a registered process. On success |
| 784 |
return 0. |
| 785 |
|
| 786 |
Meaning of parameters is as follows: |
| 787 |
* str *server - string containing registered name of the intended |
| 788 |
recipient process on remote node. |
| 789 |
* ei_x_buff *msg - dynamic ei buffer with encoded erlang term. The |
| 790 |
msg must be encoded with version byte. |
| 791 |
|
| 792 |
1.4. send(pid, msg) |
| 793 |
|
| 794 |
This function sends an Erlang term to a process. On success return 0. |
| 795 |
|
| 796 |
Meaning of parameters is as follows: |
| 797 |
* erlang_pid *pid - pid of the intended recipient process on remote |
| 798 |
node. |
| 799 |
* ei_x_buff *msg - dynamic ei buffer with encoded erlang term. The |
| 800 |
msg must be encoded with version byte. |
| 801 |
|
| 802 |
1.5. reply(msg) |
| 803 |
|
| 804 |
Function to send reply on processed message. |
| 805 |
|
| 806 |
Meaning of parameters is as follows: |
| 807 |
* ei_x_buff *msg - dynamic ei buffer with encoded erlang term. |
| 808 |
|
| 809 |
1.6. xavp2xbuff(xbuff, xavp) |
| 810 |
|
| 811 |
Function encodes XAVP variable into ei dynamic buffer. How to create |
| 812 |
XAVP variable see source code. |
| 813 |
|
| 814 |
Meaning of parameters is as follows: |
| 815 |
* ei_x_buff *xbuff - dynamic ei buffer where XAVP variable will be |
| 816 |
encoded. |
| 817 |
* sr_xavp_t *xavp - XAVP variable to be encoded. |
| 818 |
|
| 819 |
1.7. xbuff2xavp(xavp, xbuff) |
| 820 |
|
| 821 |
Function decodes ei dynamic buffer into XAVP variable. |
| 822 |
|
| 823 |
Meaning of parameters is as follows: |
| 824 |
* sr_xavp_t **xavp - XAVP variable where ei buffer will be decoded. |
| 825 |
* ei_x_buff *xbuff - dynamic ei buffer. |
| 826 |
|
| 827 |
Example 3.1. Example of using API |
| 828 |
/* note: new without version byte */ |
| 829 |
ei_x_new(&ei_req); |
| 830 |
|
| 831 |
/* ei_x_buff <- XAVP */ |
| 832 |
if (erl_api.xavp2xbuff(&ei_req,xreq)) { |
| 833 |
LM_ERR("failed to encode\n"); |
| 834 |
ei_x_free(&ei_req); |
| 835 |
return -1; |
| 836 |
} |
| 837 |
|
| 838 |
memset((void*)&ei_rep,0,sizeof(ei_x_buff)); |
| 839 |
|
| 840 |
erl_api.rpc(&ei_rep,&module,&function,&ei_req); |
| 841 |
... |
| 842 |
|
| 843 |
/* must be XAVP */ |
| 844 |
xrepl->val.type = SR_XTYPE_XAVP; |
| 845 |
|
| 846 |
/* XAVP <- ei_x_buff */ |
| 847 |
if (erl_api.xbuff2xavp(&xrepl->val.v.xavp,&ei_rep)){ |
| 848 |
LM_ERR("failed to decode\n"); |
| 849 |
ei_x_free(&ei_req); |
| 850 |
ei_x_free(&ei_rep); |
| 851 |
return -1; |
| 852 |
} |