OpenSIPS: modules/perl/README

"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/perl/README" (1 Oct 2019, 41526 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README":

3.0.0_vs_3.0.1.

1 perl Module 2 __________________________________________________________ 3 4 Table of Contents 5 6 1. Admin Guide 7 8 1.1. Overview 9 1.2. Installing the module 10 1.3. Using the module 11 1.4. Dependencies 12 13 1.4.1. OpenSIPS Modules 14 1.4.2. External Libraries or Applications 15 16 1.5. Exported Parameters 17 18 1.5.1. filename (string) 19 1.5.2. modpath (string) 20 21 1.6. Exported Functions 22 23 1.6.1. perl_exec_simple(func, [param]) 24 1.6.2. perl_exec(func, [param]) 25 26 2. OpenSIPS Perl API 27 28 2.1. OpenSIPS 29 30 2.1.1. log(level,message) 31 32 2.2. OpenSIPS::Message 33 34 2.2.1. getType() 35 2.2.2. getStatus() 36 2.2.3. getReason() 37 2.2.4. getVersion() 38 2.2.5. getRURI() 39 2.2.6. getMethod() 40 2.2.7. getFullHeader() 41 2.2.8. getBody() 42 2.2.9. getMessage() 43 2.2.10. getHeader(name) 44 2.2.11. getHeaderNames() 45 2.2.12. moduleFunction(func,string1,string2) 46 2.2.13. log(level,message) (deprecated type) 47 2.2.14. rewrite_ruri(newruri) 48 2.2.15. setFlag(flag) 49 2.2.16. resetFlag(flag) 50 2.2.17. isFlagSet(flag) 51 2.2.18. pseudoVar(string) 52 2.2.19. append_branch(branch,qval) 53 2.2.20. serialize_branches(clean_before, keep_order) 54 2.2.21. next_branches() 55 2.2.22. getParsedRURI() 56 57 2.3. OpenSIPS::URI 58 59 2.3.1. user() 60 2.3.2. host() 61 2.3.3. passwd() 62 2.3.4. port() 63 2.3.5. params() 64 2.3.6. headers() 65 2.3.7. transport() 66 2.3.8. ttl() 67 2.3.9. user_param() 68 2.3.10. maddr() 69 2.3.11. method() 70 2.3.12. lr() 71 2.3.13. r2() 72 2.3.14. transport_val() 73 2.3.15. ttl_val() 74 2.3.16. user_param_val() 75 2.3.17. maddr_val() 76 2.3.18. method_val() 77 2.3.19. lr_val() 78 2.3.20. r2_val() 79 80 2.4. OpenSIPS::AVP 81 82 2.4.1. add(name,val) 83 2.4.2. get(name) 84 2.4.3. destroy(name) 85 86 2.5. OpenSIPS::Utils::PhoneNumbers 87 88 2.5.1. 89 new(publicAccessPrefix,internationalPrefix,lon 90 gDistancePrefix,countryCode,areaCode,pbxCode 91 ) 92 93 2.5.2. canonicalForm( number [, context] ) 94 2.5.3. dialNumber( number [, context] ) 95 96 2.6. OpenSIPS::LDAPUtils::LDAPConf 97 98 2.6.1. Constructor new() 99 2.6.2. Method base() 100 2.6.3. Method host() 101 2.6.4. Method port() 102 2.6.5. Method uri() 103 2.6.6. Method rootbindpw() 104 2.6.7. Method rootbinddn() 105 2.6.8. Method binddn() 106 2.6.9. Method bindpw() 107 108 2.7. OpenSIPS::LDAPUtils::LDAPConnection 109 110 2.7.1. Constructor new( [config, [authenticated]] ) 111 2.7.2. Function/Method search( conf, filter, base, 112 [requested_attributes ...]) 113 114 2.8. OpenSIPS::VDB 115 2.9. OpenSIPS::Constants 116 2.10. OpenSIPS::VDB::Adapter::Speeddial 117 2.11. OpenSIPS::VDB::Adapter::Alias 118 119 2.11.1. query(conds,retkeys,order) 120 121 2.12. OpenSIPS::VDB::Adapter::AccountingSIPtrace 122 2.13. OpenSIPS::VDB::Adapter::Describe 123 2.14. OpenSIPS::VDB::Adapter::Auth 124 2.15. OpenSIPS::VDB::ReqCond 125 126 2.15.1. new(key,op,type,name) 127 2.15.2. op() 128 129 2.16. OpenSIPS::VDB::Pair 130 131 2.16.1. new(key,type,name) 132 2.16.2. key() 133 134 2.17. OpenSIPS::VDB::VTab 135 136 2.17.1. new() 137 2.17.2. call(op,[args]) 138 139 2.18. OpenSIPS::VDB::Value 140 141 2.18.1. stringification 142 2.18.2. new(type,data) 143 2.18.3. type() 144 2.18.4. data() 145 146 2.19. OpenSIPS::VDB::Column 147 148 2.19.1. Stringification 149 2.19.2. new(type,name) 150 2.19.3. type( ) 151 2.19.4. name() 152 2.19.5. OpenSIPS::VDB::Result 153 2.19.6. new(coldefs,[row, row, ...]) 154 2.19.7. coldefs() 155 2.19.8. rows() 156 157 3. Perl samples 158 159 3.1. sample directory 160 161 3.1.1. Script descriptions 162 163 4. Frequently Asked Questions 164 5. Contributors 165 166 5.1. By Commit Statistics 167 5.2. By Commit Activity 168 169 6. Documentation 170 171 6.1. Contributors 172 173 List of Tables 174 175 5.1. Top contributors by DevScore^(1), authored commits^(2) and 176 lines added/removed^(3) 177 178 5.2. Most recently active contributors^(1) to this module 179 180 List of Examples 181 182 1.1. Set filename parameter 183 1.2. Set modpath parameter 184 1.3. perl_exec_simple() usage 185 1.4. perl_exec() usage 186 187 Chapter 1. Admin Guide 188 189 1.1. Overview 190 191 The time needed when writing a new OpenSIPS module 192 unfortunately is quite high, while the options provided by the 193 configuration file are limited to the features implemented in 194 the modules. 195 196 With this Perl module, you can easily implement your own 197 OpenSIPS extensions in Perl. This allows for simple access to 198 the full world of CPAN modules. SIP URI rewriting could be 199 implemented based on regular expressions; accessing arbitrary 200 data backends, e.g. LDAP or Berkeley DB files, is now extremely 201 simple. 202 203 1.2. Installing the module 204 205 This Perl module is loaded in opensips.cfg (just like all the 206 other modules) with loadmodule("/path/to/perl.so");. 207 208 For the Perl module to compile, you need a reasonably recent 209 version of perl (tested with 5.8.8) linked dynamically. It is 210 strongly advised to use a threaded version. The default binary 211 packages from your favorite Linux distribution should work 212 fine. 213 214 Cross compilation is supported by the Makefile. You need to set 215 the environment variables PERLLDOPTS, PERLCCOPTS and TYPEMAP to 216 values similar to the output of 217 PERLLDOPTS: perl -MExtUtils::Embed -e ldopts 218 PERLCCOPTS: perl -MExtUtils::Embed -e ccopts 219 TYPEMAP: echo "`perl -MConfig -e 'print $Config{installprivlib}'`/Ext 220 Utils/typemap" 221 222 The exact position of your (precompiled!) perl libraries 223 depends on the setup of your environment. 224 225 1.3. Using the module 226 227 The Perl module has two interfaces: The perl side, and the 228 OpenSIPS side. Once a Perl function is defined and loaded via 229 the module parameters (see below), it may be called in 230 OpenSIPS's configuration at an arbitary point. E.g., you could 231 write a function "ldap_alias" in Perl, and then execute 232 ... 233 if (perl_exec("ldap_alias")) { 234 ... 235 } 236 ... 237 238 just as you would have done with the current alias_db module. 239 240 The functions you can use are listed in the exported_functions 241 section below. 242 243 On the Perl side, there are a number of functions that let you 244 read and modify the current SIP message, such as the RURI or 245 the message flags. An introduction to the Perl interface and 246 the full reference documentation can be found below. 247 248 1.4. Dependencies 249 250 1.4.1. OpenSIPS Modules 251 252 The following modules must be loaded before this module: 253 * The "sl" module is needed for sending replies uppon fatal 254 errors. All other modules can be accessed from the Perl 255 module, though. 256 257 1.4.2. External Libraries or Applications 258 259 The following libraries or applications must be installed 260 before running OpenSIPS with this module loaded: 261 * Perl 5.8.x or later 262 263 Additionally, a number of perl modules should be installed. The 264 OpenSIPS::LDAPUtils package relies on Net::LDAP to be 265 installed. One of the sample scripts needs IPC::Shareable 266 267 This module has been developed and tested with Perl 5.8.8, but 268 should work with any 5.8.x release. Compilation is possible 269 with 5.6.x, but its behavior is unsupported. Earlier versions 270 do not work. 271 272 On current Debian systems, at least the following packages 273 should be installed: 274 * perl 275 * perl-base 276 * perl-modules 277 * libperl5.8 278 * libperl-dev 279 * libnet-ldap-perl 280 * libipc-shareable-perl 281 282 It was reported that other Debian-style distributions (such as 283 Ubuntu) need the same packages. 284 285 On SuSE systems, at least the following packages should be 286 installed: 287 * perl 288 * perl-ldap 289 * IPC::Shareable perl module from CPAN 290 291 Although SuSE delivers a lot of perl modules, others may have 292 to be fetched from CPAN. Consider using the program “cpan2rpm” 293 - which, in turn, is available on CPAN. It creates RPM files 294 from CPAN. 295 296 1.5. Exported Parameters 297 298 1.5.1. filename (string) 299 300 This is the file name of your script. This may be set once 301 only, but it may include an arbitary number of functions and 302 “use” as many Perl module as necessary. 303 304 May not be empty! 305 306 Example 1.1. Set filename parameter 307 ... 308 modparam("perl", "filename", "/home/john/opensips/myperl.pl") 309 ... 310 311 1.5.2. modpath (string) 312 313 The path to the Perl modules included (OpenSIPS.pm et.al). It 314 is not absolutely crucial to set this path, as you may install 315 the Modules in Perl's standard path, or update the “%INC” 316 variable from within your script. Using this module parameter 317 is the standard behavior, though. 318 319 Example 1.2. Set modpath parameter 320 ... 321 modparam("perl", "modpath", "/usr/local/lib/opensips/perl/") 322 ... 323 324 1.6. Exported Functions 325 326 1.6.1. perl_exec_simple(func, [param]) 327 328 Calls a perl function without passing it the current SIP 329 message. May be used for very simple simple requests that do 330 not have to fiddle with the message themselves, but rather 331 return information values about the environment. 332 333 The first parameter is the function to be called. An arbitrary 334 string may optionally be passed as a parameter. 335 336 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 337 ONREPLY_ROUTE and BRANCH_ROUTE. 338 339 Example 1.3. perl_exec_simple() usage 340 ... 341 if ($rm=="INVITE") { 342 perl_exec_simple("dosomething", "on invite messages"); 343 }; 344 ... 345 346 1.6.2. perl_exec(func, [param]) 347 348 Calls a perl function with passing it the current SIP message. 349 The SIP message is reflected by a Perl module that gives you 350 access to the information in the current SIP message 351 (OpenSIPS::Message). 352 353 The first parameter is the function to be called. An arbitrary 354 string may be passed as a parameter. 355 356 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 357 ONREPLY_ROUTE and BRANCH_ROUTE. 358 359 Example 1.4. perl_exec() usage 360 ... 361 if (perl_exec("ldapalias")) { 362 ... 363 }; 364 ... 365 366 Chapter 2. OpenSIPS Perl API 367 368 2.1. OpenSIPS 369 370 This module provides access to a limited number of OpenSIPS 371 core functions. As the most interesting functions deal with SIP 372 messages, they are located in the OpenSIPS::Message class 373 below. 374 375 2.1.1. log(level,message) 376 377 Logs the message with OpenSIPS's logging facility. The logging 378 level is one of the following: 379 * L_ALERT 380 * L_CRIT 381 * L_ERR 382 * L_WARN 383 * L_NOTICE 384 * L_INFO 385 * L_DBG 386 387 Please note that this method is NOT automatically exported, as 388 it collides with the perl function log (which calculates the 389 logarithm). Either explicitly import the function (via use 390 OpenSIPS qw ( log );), or call it with its full name: 391 OpenSIPS::log(L_INFO, "foobar"); 392 393 2.2. OpenSIPS::Message 394 395 This package provides access functions for an OpenSIPS sip_msg 396 structure and its sub-components. Through its means it is 397 possible to fully configure alternative routing decisions. 398 399 2.2.1. getType() 400 401 Returns one of the constants SIP_REQUEST, SIP_REPLY, 402 SIP_INVALID stating the type of the current message. 403 404 2.2.2. getStatus() 405 406 Returns the status code of the current Reply message. This 407 function is invalid in Request context! 408 409 2.2.3. getReason() 410 411 Returns the reason of the current Reply message. This function 412 is invalid in Request context! 413 414 2.2.4. getVersion() 415 416 Returns the version string of the current SIP message. 417 418 2.2.5. getRURI() 419 420 This function returns the recipient URI of the present SIP 421 message: 422 423 my $ruri = $m->getRURI(); 424 425 getRURI returns a string. See “getParsedRURI()” below how to 426 receive a parsed structure. 427 428 This function is valid in request messages only. 429 430 2.2.6. getMethod() 431 432 Returns the current method, such as INVITE, REGISTER, ACK and 433 so on. 434 435 my $method = $m->getMethod(); 436 437 This function is valid in request messages only. 438 439 2.2.7. getFullHeader() 440 441 Returns the full message header as present in the current 442 message. You might use this header to further work with it with 443 your favorite MIME package. 444 445 my $hdr = $m->getFullHeader(); 446 447 2.2.8. getBody() 448 449 Returns the message body. 450 451 2.2.9. getMessage() 452 453 Returns the whole message including headers and body. 454 455 2.2.10. getHeader(name) 456 457 Returns the body of the first message header with this name. 458 459 print $m->getHeader("To"); 460 461 "John" <sip:john@doe.example> 462 463 2.2.11. getHeaderNames() 464 465 Returns an array of all header names. Duplicates possible! 466 467 2.2.12. moduleFunction(func,string1,string2) 468 469 Search for an arbitrary function in module exports and call it 470 with the parameters self, string1, string2. 471 472 string1 and/or string2 may be omitted. 473 474 As this function provides access to the functions that are 475 exported to the OpenSIPS configuration file, it is autoloaded 476 for unknown functions. Instead of writing 477 $m->moduleFunction("sl_send_reply", "500", "Internal Error"); 478 $m->moduleFunction("xlog", "L_INFO", "foo"); 479 480 you may as well write 481 $m->sl_send_reply("500", "Internal Error"); 482 $m->xlog("L_INFO", "foo"); 483 484 WARNING 485 486 In OpenSIPS 1.2, only a limited subset of module functions is 487 available. This restriction will be removed in a later version. 488 489 Here is a list of functions that are expected to be working 490 (not claiming completeness): 491 * alias_db_lookup 492 * consume_credentials 493 * is_rpid_user_e164 494 * append_rpid_hf 495 * bind_auth 496 * avp_print 497 * cpl_process_register 498 * cpl_process_register_norpl 499 * load_dlg 500 * ds_next_dst 501 * ds_next_domain 502 * ds_mark_dst 503 * ds_mark_dst 504 * is_from_local 505 * is_uri_host_local 506 * dp_can_connect 507 * dp_apply_policy 508 * enum_query (without parameters) 509 * enum_fquery (without parameters) 510 * is_from_user_enum (without parameters) 511 * i_enum_query (without parameters) 512 * imc_manager 513 * jab_* (all functions from the jabber module) 514 * sdp_mangle_ip 515 * sdp_mangle_port 516 * encode_contact 517 * decode_contact 518 * decode_contact_header 519 * fix_contact 520 * use_media_proxy 521 * end_media_session 522 * m_store 523 * m_dump 524 * fix_nated_contact 525 * unforce_rtp_proxy 526 * force_rtp_proxy 527 * fix_nated_register 528 * add_rcv_param 529 * options_reply 530 * checkospheader 531 * validateospheader 532 * requestosprouting 533 * checkosproute 534 * prepareosproute 535 * prepareallosproutes 536 * checkcallingtranslation 537 * reportospusage 538 * mangle_pidf 539 * mangle_message_cpim 540 * add_path (without parameters) 541 * add_path_received (without parameters) 542 * prefix2domain 543 * allow_routing (without parameters) 544 * allow_trusted 545 * pike_check_req 546 * handle_publish 547 * handle_subscribe 548 * stored_pres_info 549 * bind_pua 550 * send_publish 551 * send_subscribe 552 * pua_set_publish 553 * loose_route 554 * record_route 555 * load_rr 556 * sip_trace 557 * sl_reply_error 558 * sms_send_msg 559 * sd_lookup 560 * sstCheckMin 561 * append_time 562 * has_body (without parameters) 563 * is_peer_verified 564 * t_newtran 565 * t_release 566 * t_relay (without parameters) 567 * t_flush_flags 568 * t_check_trans 569 * t_was_cancelled 570 * uac_restore_from 571 * uac_auth 572 * has_totag 573 * tel2sip 574 * check_to 575 * check_from 576 * radius_does_uri_exist 577 * ul_* (All functions exported by the usrloc module for user access) 578 * xmpp_send_message 579 580 2.2.13. log(level,message) (deprecated type) 581 582 Logs the message with OpenSIPS's logging facility. The logging 583 level is one of the following: 584 * L_ALERT 585 * L_CRIT 586 * L_ERR 587 * L_WARN 588 * L_NOTICE 589 * L_INFO 590 * L_DBG 591 592 The logging function should be accessed via the OpenSIPS module 593 variant. This one, located in OpenSIPS::Message, is deprecated. 594 595 2.2.14. rewrite_ruri(newruri) 596 597 Sets a new destination (recipient) URI. Useful for rerouting 598 the current message/call. 599 if ($m->getRURI() =~ m/\@somedomain.net/) { 600 $m->rewrite_ruri("sip:dispatcher\@organization.net"); 601 } 602 603 2.2.15. setFlag(flag) 604 605 Sets a message flag. The constants as known from the C API may 606 be used, when Constants.pm is included. 607 608 2.2.16. resetFlag(flag) 609 610 Resets a message flag. 611 612 2.2.17. isFlagSet(flag) 613 614 Returns whether a message flag is set or not. 615 616 2.2.18. pseudoVar(string) 617 618 Returns a new string where all pseudo variables are substituted 619 by their values. Can be used to receive the values of single 620 variables, too. 621 622 Please remember that you need to escape the '$' sign in perl 623 strings! 624 625 2.2.19. append_branch(branch,qval) 626 627 Append a branch to current message. 628 629 2.2.20. serialize_branches(clean_before, keep_order) 630 631 Serialize branches. 632 633 2.2.21. next_branches() 634 635 Next branches. 636 637 2.2.22. getParsedRURI() 638 639 Returns the current destination URI as an OpenSIPS::URI object. 640 641 2.3. OpenSIPS::URI 642 643 This package provides functions for access to sip_uri 644 structures. 645 646 2.3.1. user() 647 648 Returns the user part of this URI. 649 650 2.3.2. host() 651 652 Returns the host part of this URI. 653 654 2.3.3. passwd() 655 656 Returns the passwd part of this URI. 657 658 2.3.4. port() 659 660 Returns the port part of this URI. 661 662 2.3.5. params() 663 664 Returns the params part of this URI. 665 666 2.3.6. headers() 667 668 Returns the headers part of this URI. 669 670 2.3.7. transport() 671 672 Returns the transport part of this URI. 673 674 2.3.8. ttl() 675 676 Returns the ttl part of this URI. 677 678 2.3.9. user_param() 679 680 Returns the user_param part of this URI. 681 682 2.3.10. maddr() 683 684 Returns the maddr part of this URI. 685 686 2.3.11. method() 687 688 Returns the method part of this URI. 689 690 2.3.12. lr() 691 692 Returns the lr part of this URI. 693 694 2.3.13. r2() 695 696 Returns the r2 part of this URI. 697 698 2.3.14. transport_val() 699 700 Returns the transport_val part of this URI. 701 702 2.3.15. ttl_val() 703 704 Returns the ttl_val part of this URI. 705 706 2.3.16. user_param_val() 707 708 Returns the user_param_val part of this URI. 709 710 2.3.17. maddr_val() 711 712 Returns the maddr_val part of this URI. 713 714 2.3.18. method_val() 715 716 Returns the method_val part of this URI. 717 718 2.3.19. lr_val() 719 720 Returns the lr_val part of this URI. 721 722 2.3.20. r2_val() 723 724 Returns the r2_val part of this URI. 725 726 2.4. OpenSIPS::AVP 727 728 This package provides access functions for OpenSIPS's AVPs. 729 These variables can be created, evaluated, modified and removed 730 through this package. 731 732 Please note that these functions do NOT support the notation 733 used in the configuration file, but directly work on strings or 734 numbers. See documentation of add method below. 735 736 2.4.1. add(name,val) 737 738 Add an AVP. 739 740 Add an OpenSIPS AVP to its environment. name and val may both 741 be integers or strings; this function will try to guess what is 742 correct. Please note that 743 OpenSIPS::AVP::add("10", "10") 744 745 is something different than 746 OpenSIPS::AVP::add(10, 10) 747 748 due to this evaluation: The first will create _string_ AVPs 749 with the name 10, while the latter will create a numerical AVP. 750 751 You can modify/overwrite AVPs with this function. 752 753 2.4.2. get(name) 754 755 get an OpenSIPS AVP: 756 my $numavp = OpenSIPS::AVP::get(5); 757 my $stravp = OpenSIPS::AVP::get("foo"); 758 759 2.4.3. destroy(name) 760 761 Destroy an AVP. 762 OpenSIPS::AVP::destroy(5); 763 OpenSIPS::AVP::destroy("foo"); 764 765 2.5. OpenSIPS::Utils::PhoneNumbers 766 767 OpenSIPS::Utils::PhoneNumbers - Functions for canonical forms 768 of phone numbers. 769 use OpenSIPS::Utils::PhoneNumbers; 770 771 my $phonenumbers = new OpenSIPS::Utils::PhoneNumbers( 772 publicAccessPrefix => "0", 773 internationalPrefix => "+", 774 longDistancePrefix => "0", 775 areaCode => "761", 776 pbxCode => "456842", 777 countryCode => "49" 778 ); 779 780 $canonical = $phonenumbers->canonicalForm("07612034567"); 781 $number = $phonenumbers->dialNumber("+497612034567"); 782 783 A telphone number starting with a plus sign and containing all 784 dial prefixes is in canonical form. This is usally not the 785 number to dial at any location, so the dialing number depends 786 on the context of the user/system. 787 788 The idea to canonicalize numbers were taken from hylafax. 789 790 Example: +497614514829 is the canonical form of my phone 791 number, 829 is the number to dial at Pyramid, 4514829 is the 792 dialing number from Freiburg are and so on. 793 794 To canonicalize any number, we strip off any dial prefix we 795 find and then add the prefixes for the location. So, when the 796 user enters the number 04514829 in context pyramid, we remove 797 the publicAccessPrefix (at Pyramid this is 0) and the pbxPrefix 798 (4514 here). The result is 829. Then we add all the general 799 dial prefixes - 49 (country) 761 (area) 4514 (pbx) and 829, the 800 number itself => +497614514829 801 802 To get the dialing number from a canonical phone number, we 803 substract all general prefixes until we have something 804 805 As said before, the interpretation of a phone number depends on 806 the context of the location. For the functions in this package, 807 the context is created through the new operator. 808 809 The following fields should be set: 810 'longDistancePrefix' 811 'areaCode' 812 'pbxCode' 813 'internationalPrefix' 814 'publicAccessPrefix' 815 'countryCode' 816 817 This module exports the following functions when useed: 818 819 2.5.1. new(publicAccessPrefix,internationalPrefix,longDistancePrefix, 820 countryCode,areaCode,pbxCode) 821 822 The new operator returns an object of this type and sets its 823 locational context according to the passed parameters. See 824 OpenSIPS::Utils::PhoneNumbers above. 825 826 2.5.2. canonicalForm( number [, context] ) 827 828 Convert a phone number (given as first argument) into its 829 canonical form. When no context is passed in as the second 830 argument, the default context from the systems configuration 831 file is used. 832 833 2.5.3. dialNumber( number [, context] ) 834 835 Convert a canonical phone number (given in the first argument) 836 into a number to to dial. WHen no context is given in the 837 second argument, a default context from the systems 838 configuration is used. 839 840 2.6. OpenSIPS::LDAPUtils::LDAPConf 841 842 OpenSIPS::LDAPUtils::LDAPConf - Read openldap config from 843 standard config files. 844 use OpenSIPS::LDAPUtils::LDAPConf; 845 my $conf = new OpenSIPS::LDAPUtils::LDAPConf(); 846 847 This module may be used to retrieve the global LDAP 848 configuration as used by other LDAP software, such as 849 nsswitch.ldap and pam-ldap. The configuration is usualy stored 850 in /etc/openldap/ldap.conf 851 852 When used from an account with sufficient privilegs (e.g. 853 root), the ldap manager passwort is also retrieved. 854 855 2.6.1. Constructor new() 856 857 Returns a new, initialized OpenSIPS::LDAPUtils::LDAPConf 858 object. 859 860 2.6.2. Method base() 861 862 Returns the servers base-dn to use when doing queries. 863 864 2.6.3. Method host() 865 866 Returns the ldap host to contact. 867 868 2.6.4. Method port() 869 870 Returns the ldap servers port. 871 872 2.6.5. Method uri() 873 874 Returns an uri to contact the ldap server. When there is no 875 ldap_uri in the configuration file, an ldap: uri is constucted 876 from host and port. 877 878 2.6.6. Method rootbindpw() 879 880 Returns the ldap "root" password. 881 882 Note that the rootbindpw is only available when the current 883 account has sufficient privilegs to access 884 /etc/openldap/ldap.secret. 885 886 2.6.7. Method rootbinddn() 887 888 Returns the DN to use for "root"-access to the ldap server. 889 890 2.6.8. Method binddn() 891 892 Returns the DN to use for authentication to the ldap server. 893 When no bind dn has been specified in the configuration file, 894 returns the rootbinddn. 895 896 2.6.9. Method bindpw() 897 898 Returns the password to use for authentication to the ldap 899 server. When no bind password has been specified, returns the 900 rootbindpw if any. 901 902 2.7. OpenSIPS::LDAPUtils::LDAPConnection 903 904 OpenSIPS::LDAPUtils::LDAPConnection - Perl module to perform 905 simple LDAP queries. 906 907 OO-Style interface: 908 use OpenSIPS::LDAPUtils::LDAPConnection; 909 my $ldap = new OpenSIPS::LDAPUtils::LDAPConnection; 910 my @rows = $ldap-search("uid=andi","ou=people,ou=coreworks,ou=de"); 911 912 Procedural interface: 913 use OpenSIPS::LDAPUtils::LDAPConnection; 914 my @rows = $ldap->search( 915 new OpenSIPS::LDAPUtils::LDAPConfig(), "uid=andi","ou=people,ou=co 916 reworks,ou=de"); 917 918 This perl module offers a somewhat simplified interface to the 919 Net::LDAP functionality. It is intended for cases where just a 920 few attributes should be retrieved without the overhead of the 921 full featured Net::LDAP. 922 923 2.7.1. Constructor new( [config, [authenticated]] ) 924 925 Set up a new LDAP connection. 926 927 The first argument, when given, should be a hash reference 928 pointing to to the connection parameters, possibly an 929 OpenSIPS::LDAPUtils::LDAPConfig object. This argument may be 930 undef in which case a new (default) 931 OpenSIPS::LDAPUtils::LDAPConfig object is used. 932 933 When the optional second argument is a true value, the 934 connection will be authenticated. Otherwise an anonymous bind 935 is done. 936 937 On success, a new LDAPConnection object is returned, otherwise 938 the result is undef. 939 940 2.7.2. Function/Method search( conf, filter, base, 941 [requested_attributes ...]) 942 943 perform an ldap search, return the dn of the first matching 944 directory entry, unless a specific attribute has been 945 requested, in wich case the values(s) fot this attribute are 946 returned. 947 948 When the first argument (conf) is a 949 OpenSIPS::LDAPUtils::LDAPConnection, it will be used to perform 950 the queries. You can pass the first argument implicitly by 951 using the "method" syntax. 952 953 Otherwise the conf argument should be a reference to a hash 954 containing the connection setup parameters as contained in a 955 OpenSIPS::LDAPUtils::LDAPConf object. In this mode, the 956 OpenSIPS::LDAPUtils::LDAPConnection from previous queries will 957 be reused. 958 959 2.7.2.1. Arguments: 960 961 conf 962 configuration object, used to find host,port,suffix and 963 use_ldap_checks 964 965 filter 966 ldap search filter, eg '(mail=some@domain)' 967 968 base 969 search base for this query. If undef use default suffix, 970 concat base with default suffix if the last char is a 971 ',' 972 973 requested_attributes 974 retrieve the given attributes instead of the dn from the 975 ldap directory. 976 977 2.7.2.2. Result: 978 979 Without any specific requested_attributes, return the dn of all 980 matching entries in the LDAP directory. 981 982 When some requested_attributes are given, return an array with 983 those attibutes. When multiple entries match the query, the 984 attribute lists are concatenated. 985 986 2.8. OpenSIPS::VDB 987 988 This package is an (abstract) base class for all virtual 989 databases. Derived packages can be configured to be used by 990 OpenSIPS as a database. 991 992 The base class itself should NOT be used in this context, as it 993 does not provide any functionality. 994 995 2.9. OpenSIPS::Constants 996 997 This package provides a number of constants taken from enums 998 and defines of OpenSIPS header files. Unfortunately, there is 999 no mechanism for updating the constants automatically, so check 1000 the values if you are in doubt. 1001 1002 2.10. OpenSIPS::VDB::Adapter::Speeddial 1003 1004 This adapter can be used with the speeddial module. 1005 1006 2.11. OpenSIPS::VDB::Adapter::Alias 1007 1008 This package is intended for usage with the alias_db module. 1009 The query VTab has to take two arguments and return an array of 1010 two arguments (user name/domain). 1011 1012 2.11.1. query(conds,retkeys,order) 1013 1014 Queries the vtab with the given arguments for request 1015 conditions, keys to return and sort order column name. 1016 1017 2.12. OpenSIPS::VDB::Adapter::AccountingSIPtrace 1018 1019 This package is an Adapter for the acc and tracer modules, 1020 featuring only an insert operation. 1021 1022 2.13. OpenSIPS::VDB::Adapter::Describe 1023 1024 This package is intended for debug usage. It will print 1025 information about requested functions and operations of a 1026 client module. 1027 1028 Use this module to request schema information when creating new 1029 adapters. 1030 1031 2.14. OpenSIPS::VDB::Adapter::Auth 1032 1033 This adapter is intended for usage with the auth_db module. The 1034 VTab should take a username as an argument and return a (plain 1035 text!) password. 1036 1037 2.15. OpenSIPS::VDB::ReqCond 1038 1039 This package represents a request condition for database 1040 access, consisting of a column name, an operator (=, <, >, 1041 ...), a data type and a value. 1042 1043 This package inherits from OpenSIPS::VDB::Pair and thus 1044 includes its methods. 1045 1046 2.15.1. new(key,op,type,name) 1047 1048 Constructs a new Column object. 1049 1050 2.15.2. op() 1051 1052 Returns or sets the current operator. 1053 1054 2.16. OpenSIPS::VDB::Pair 1055 1056 This package represents database key/value pairs, consisting of 1057 a key, a value type, and the value. 1058 1059 This package inherits from OpenSIPS::VDB::Value and thus has 1060 the same methods. 1061 1062 2.16.1. new(key,type,name) 1063 1064 Constructs a new Column object. 1065 1066 2.16.2. key() 1067 1068 Returns or sets the current key. 1069 1070 2.17. OpenSIPS::VDB::VTab 1071 1072 This package handles virtual tables and is used by the 1073 OpenSIPS::VDB class to store information about valid tables. 1074 The package is not inteded for end user access. 1075 1076 2.17.1. new() 1077 1078 Constructs a new VTab object 1079 1080 2.17.2. call(op,[args]) 1081 1082 Invokes an operation on the table (insert, update, ...) with 1083 the given arguments. 1084 1085 2.18. OpenSIPS::VDB::Value 1086 1087 This package represents a database value. Additional to the 1088 data itself, information about its type is stored. 1089 1090 2.18.1. stringification 1091 1092 When accessing a OpenSIPS::VDB::Value object as a string, it 1093 simply returns its data regardless of its type. =cut 1094 1095 use strict; 1096 1097 package OpenSIPS::VDB::Value; 1098 1099 use overload '""' => \&stringify; 1100 1101 sub stringify { shift->{data} } 1102 1103 use OpenSIPS; use OpenSIPS::Constants; 1104 1105 our @ISA = qw ( OpenSIPS::Utils::Debug ); 1106 1107 2.18.2. new(type,data) 1108 1109 Constructs a new Value object. Its data type and the data are 1110 passed as parameters. 1111 1112 2.18.3. type() 1113 1114 Returns or sets the current data type. Please consider using 1115 the constants from OpenSIPS::Constants 1116 1117 2.18.4. data() 1118 1119 Returns or sets the current data. 1120 1121 2.19. OpenSIPS::VDB::Column 1122 1123 This package represents database column definition, consisting 1124 of a column name and its data type. 1125 1126 2.19.1. Stringification 1127 1128 When accessing a OpenSIPS::VDB::Column object as a string, it 1129 simply returns its column name regardless of its type. =cut 1130 1131 package OpenSIPS::VDB::Column; 1132 1133 use overload '""' => \&stringify; 1134 1135 sub stringify { shift->{name} } 1136 1137 use OpenSIPS; use OpenSIPS::Constants; 1138 1139 our @ISA = qw ( OpenSIPS::Utils::Debug ); 1140 1141 2.19.2. new(type,name) 1142 1143 Constructs a new Column object. Its type and the name are 1144 passed as parameters. 1145 1146 2.19.3. type( ) 1147 1148 Returns or sets the current type. Please consider using the 1149 constants from OpenSIPS::Constants 1150 1151 2.19.4. name() 1152 1153 Returns or sets the current column name. 1154 1155 2.19.5. OpenSIPS::VDB::Result 1156 1157 This class represents a VDB result set. It contains a column 1158 definition, plus an array of rows. Rows themselves are simply 1159 references to arrays of scalars. 1160 1161 2.19.6. new(coldefs,[row, row, ...]) 1162 1163 The constructor creates a new Result object. Its first 1164 parameter is a reference to an array of OpenSIPS::VDB::Column 1165 objects. Additional parameters may be passed to provide initial 1166 rows, which are references to arrays of scalars. 1167 1168 2.19.7. coldefs() 1169 1170 Returns or sets the column definition of the object. 1171 1172 2.19.8. rows() 1173 1174 Returns or sets the rows of the object. 1175 1176 Chapter 3. Perl samples 1177 1178 Revision History 1179 Revision $Revision: 5901 $ $Date$ 1180 1181 3.1. sample directory 1182 1183 There are a number of example scripts in the “samples/”. They 1184 are documented well. Read them, it will explain a lot to you :) 1185 1186 If you want to use any of these scripts directly in your 1187 implementation, you can use Perl's “require” mechanism to 1188 import them (just remember that you need to use quotes when 1189 require'ing .pl files). 1190 1191 3.1.1. Script descriptions 1192 1193 The included sample scripts are described below: 1194 1195 3.1.1.1. branches.pl 1196 1197 The minimal function in branches.pl demonstrates that you can 1198 access the "append_branch" function from within perl, just as 1199 you would have done from your normal configuration file. You'll 1200 find documentation on the concepts of branching in the OpenSIPS 1201 documentation. 1202 1203 3.1.1.2. firstline.pl 1204 1205 Message's first_line structure may be evaluated. Message can be 1206 either of SIP_REQUEST or SIP_REPLY. Depending on that, 1207 different information can be received. This script demonstrates 1208 these functions. 1209 1210 3.1.1.3. flags.pl 1211 1212 The perl module provides access to OpenSIPS's flagging 1213 mechanism. The flag names available for OpenSIPS modules are 1214 made available through the OpenSIPS::Constants package, so you 1215 can flag messages as "green", "magenta" etc. 1216 1217 The first function, setflag, demonstrates how the "green" flag 1218 is set. In the second function, readflag, the "green" and 1219 "magenta" flags are evaluated. 1220 1221 3.1.1.4. functions.pl 1222 1223 This sample script demonstrates different things related to 1224 calling functions from within perl, and the different types of 1225 functions you can offer for OpenSIPS access. 1226 1227 “exportedfuncs” simply demonstrates that you can use the 1228 moduleFunction method to call functions offered by other 1229 modules. The results are equivalent to calling these functions 1230 from your config file. In the demonstrated case, telephone 1231 calls with a destination number beginning with 555... are 1232 rejected with an internal server error. Other destination 1233 addresses are passed to the alias_db module. 1234 1235 Please note that the moduleFunction method is not fully 1236 available in OpenSIPS 1.2. See the method's documentation for 1237 details. 1238 1239 “paramfunc” shows that you can pass arbitrary strings to perl 1240 functions. Do with them whatever you want :) 1241 1242 “autotest” demonstrates that unknown functions in 1243 OpenSIPS::Message objects are automatically transformed into 1244 calls to module functions. 1245 1246 The “diefunc”s show that dying perl scripts - by "manual" 1247 dying, or because of script errors - are handled by the 1248 OpenSIPS package. The error message is logged through 1249 OpenSIPS's logging mechanism. Please note that this only works 1250 correctly if you do NOT overwrite the default die handler. Oh, 1251 yes, that works for warnings, too. 1252 1253 3.1.1.5. headers.pl 1254 1255 Header extraction is among the most crucial functionalities 1256 while processing SIP messages. This sample script demonstrates 1257 access to header names and values within two sample functions. 1258 1259 “headernames” extracts all header names and logs their names. 1260 1261 “someheaders” logs the contents of the two headers, “To” and 1262 “WWW-Contact”. As you can see, headers that occur more than 1263 once are retrieved as an array, which may be accessed by Perl's 1264 array accessing methods. 1265 1266 3.1.1.6. logging.pl 1267 1268 For debugging purposes, you probably want to write messages to 1269 the syslog. The “logdemo” shows three ways to access the 1270 OpenSIPS log function: it is available through the OpenSIPS 1271 class as well as through the OpenSIPS::Message class. 1272 1273 Remember that you can use exported functions from other 1274 modules. You may thus as well use the “xlog” module and it's 1275 xlog function. 1276 1277 The L_INFO, L_DBG, L_ERR, L_CRIT... constants are available 1278 through the OpenSIPS::Constants package. 1279 1280 3.1.1.7. messagedump.pl 1281 1282 This script demonstrates how to access the whole message header 1283 of the current message. Please note that modifications on the 1284 message made by earlier function calls in your configuration 1285 script may NOT be reflected in this dump. 1286 1287 3.1.1.8. persistence.pl 1288 1289 When processing SIP messages, you may want to use persistent 1290 data across multiple calls to your Perl functions. Your first 1291 option is to use global variables in your script. 1292 Unfortunately, these globals are not visible from the mulitple 1293 instances of OpenSIPS. You may want to use a mechanism such as 1294 the IPC::Shareable shared memory access package to correct 1295 this. 1296 1297 3.1.1.9. phonenumbers.pl 1298 1299 The OpenSIPS::Utils::PhoneNumbers package provides two methods 1300 for the transformation of local to canonical telephone numbers, 1301 and vice versa. This script demonstrates it's use. 1302 1303 3.1.1.10. pseudovars.pl 1304 1305 This script demonstrates the Perl module's “pseudoVar” method. 1306 It may be used to retrieve the values of current pseudo 1307 variables. 1308 1309 You might notice that there is no particular function for 1310 setting pseudo variables; you may use the exported functions 1311 from the avpops module, though. 1312 1313 Chapter 4. Frequently Asked Questions 1314 1315 4.1. 1316 1317 Are there known bugs in the Perl module? 1318 1319 The Perl module does have a few shortcomings that may be 1320 regarded as bugs. 1321 * Missing module functions. Not all functions of other 1322 modules are available for Perl access. The reason for this 1323 is a design property of OpenSIPS. Making available more 1324 functions is work in progress. 1325 * Perl and threads. Perl itself is, when compiled with the 1326 correct parameters, thread safe; unfortunately, not all 1327 Perl modules are. The DBI modules, especially (but not 1328 restricted to) DBI::ODBC are known NOT to be thread safe. 1329 Using DBI::ODBC -- and possibly other non-thread-safe Perl 1330 extensions -- may result in erroneous behavior of OpenSIPS, 1331 including (but not restricted to) server crashes and wrong 1332 routing. 1333 1334 4.2. 1335 1336 Where can I find more about OpenSIPS? 1337 1338 Take a look at http://www.opensips.org/. 1339 1340 4.3. 1341 1342 Where can I post a question about this module? 1343 1344 First at all check if your question was already answered on one 1345 of our mailing lists: 1346 * User Mailing List - 1347 http://lists.opensips.org/cgi-bin/mailman/listinfo/users 1348 * Developer Mailing List - 1349 http://lists.opensips.org/cgi-bin/mailman/listinfo/devel 1350 1351 E-mails regarding any stable OpenSIPS release should be sent to 1352 <users@lists.opensips.org> and e-mails regarding development 1353 versions should be sent to <devel@lists.opensips.org>. 1354 1355 If you want to keep the mail private, send it to 1356 <users@lists.opensips.org>. 1357 1358 4.4. 1359 1360 How can I report a bug? 1361 1362 Please follow the guidelines provided at: 1363 https://github.com/OpenSIPS/opensips/issues. 1364 1365 Chapter 5. Contributors 1366 1367 5.1. By Commit Statistics 1368 1369 Table 5.1. Top contributors by DevScore^(1), authored 1370 commits^(2) and lines added/removed^(3) 1371 Name DevScore Commits Lines ++ Lines -- 1372 1. Bastian Friedrich 112 38 8597 284 1373 2. Bogdan-Andrei Iancu (@bogdan-iancu) 47 28 702 681 1374 3. Razvan Crainea (@razvancrainea) 24 21 99 60 1375 4. Daniel-Constantin Mierla (@miconda) 19 14 164 125 1376 5. Liviu Chircu (@liviuchircu) 16 13 54 67 1377 6. Vlad Patrascu (@rvlad-patrascu) 15 6 173 348 1378 7. Julien Blache 4 1 80 64 1379 8. Edson Gellert Schubert 4 1 0 141 1380 9. Ionut Ionita (@ionutrazvanionita) 3 1 100 7 1381 10. Ancuta Onofrei 3 1 27 40 1382 1383 All remaining contributors: Konstantin Bokarius, Boris Ratner, 1384 Julián Moreno Patiño, Klaus Darilion, Peter Lemenkov 1385 (@lemenkov), Ovidiu Sas (@ovidiusas), Dan Pascu (@danpascu). 1386 1387 (1) DevScore = author_commits + author_lines_added / 1388 (project_lines_added / project_commits) + author_lines_deleted 1389 / (project_lines_deleted / project_commits) 1390 1391 (2) including any documentation-related commits, excluding 1392 merge commits. Regarding imported patches/code, we do our best 1393 to count the work on behalf of the proper owner, as per the 1394 "fix_authors" and "mod_renames" arrays in 1395 opensips/doc/build-contrib.sh. If you identify any 1396 patches/commits which do not get properly attributed to you, 1397 please submit a pull request which extends "fix_authors" and/or 1398 "mod_renames". 1399 1400 (3) ignoring whitespace edits, renamed files and auto-generated 1401 files 1402 1403 5.2. By Commit Activity 1404 1405 Table 5.2. Most recently active contributors^(1) to this module 1406 Name Commit Activity 1407 1. Razvan Crainea (@razvancrainea) Jun 2011 - Sep 2019 1408 2. Vlad Patrascu (@rvlad-patrascu) May 2017 - May 2019 1409 3. Bogdan-Andrei Iancu (@bogdan-iancu) Dec 2006 - Apr 2019 1410 4. Liviu Chircu (@liviuchircu) Mar 2014 - Nov 2018 1411 5. Peter Lemenkov (@lemenkov) Jun 2018 - Jun 2018 1412 6. Julián Moreno Patiño Feb 2016 - Feb 2016 1413 7. Ionut Ionita (@ionutrazvanionita) Oct 2015 - Oct 2015 1414 8. Boris Ratner Jan 2013 - Jan 2013 1415 9. Ovidiu Sas (@ovidiusas) Oct 2010 - Oct 2010 1416 10. Dan Pascu (@danpascu) Aug 2008 - Aug 2008 1417 1418 All remaining contributors: Klaus Darilion, Daniel-Constantin 1419 Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, 1420 Bastian Friedrich, Ancuta Onofrei, Julien Blache. 1421 1422 (1) including any documentation-related commits, excluding 1423 merge commits 1424 1425 Chapter 6. Documentation 1426 1427 6.1. Contributors 1428 1429 Last edited by: Razvan Crainea (@razvancrainea), Peter Lemenkov 1430 (@lemenkov), Liviu Chircu (@liviuchircu), Vlad Patrascu 1431 (@rvlad-patrascu), Bogdan-Andrei Iancu (@bogdan-iancu), Ovidiu 1432 Sas (@ovidiusas), Klaus Darilion, Daniel-Constantin Mierla 1433 (@miconda), Konstantin Bokarius, Edson Gellert Schubert, 1434 Bastian Friedrich. 1435 1436 Documentation Copyrights: 1437 1438 Copyright © 2007 Collax GmbH