modules_k/perl/README
ac9ce6fb
 perl Module
 
 Bastian Friedrich
 
    Collax GmbH
 
 Edited by
 
 Bastian Friedrich
 
719e7b81
    Copyright � 2007 Collax GmbH
d77df08a
    Revision History
69ead4ab
    Revision $Revision$ $Date: 2008-08-06 13:08:33 +0300
                               (Wed, 06 Aug 2008) $
989206bd
      __________________________________________________________
ac9ce6fb
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
ac9ce6fb
 
         1.1. Overview
         1.2. Installing the module
         1.3. Using the module
         1.4. Dependencies
 
37e4f522
               1.4.1. Kamailio Modules
ac9ce6fb
               1.4.2. External Libraries or Applications
 
         1.5. Exported Parameters
 
               1.5.1. filename (string)
               1.5.2. modpath (string)
 
         1.6. Exported Functions
 
989206bd
               1.6.1. perl_exec_simple(func, [param])
               1.6.2. perl_exec(func, [param])
ac9ce6fb
 
873d51d6
    2. OpenSER Perl API
033b5989
 
873d51d6
         2.1. OpenSER
033b5989
 
               2.1.1. log(level,message)
 
873d51d6
         2.2. OpenSER::Message
033b5989
 
               2.2.1. getType()
               2.2.2. getStatus()
               2.2.3. getReason()
               2.2.4. getVersion()
               2.2.5. getRURI()
               2.2.6. getMethod()
               2.2.7. getFullHeader()
               2.2.8. getBody()
               2.2.9. getMessage()
               2.2.10. getHeader(name)
               2.2.11. getHeaderNames()
               2.2.12. moduleFunction(func,string1,string2)
               2.2.13. log(level,message) (deprecated type)
               2.2.14. rewrite_ruri(newruri)
               2.2.15. setFlag(flag)
               2.2.16. resetFlag(flag)
               2.2.17. isFlagSet(flag)
               2.2.18. pseudoVar(string)
               2.2.19. append_branch(branch,qval)
69ead4ab
               2.2.20. getParsedRURI()
033b5989
 
873d51d6
         2.3. OpenSER::URI
033b5989
 
               2.3.1. user()
               2.3.2. host()
               2.3.3. passwd()
               2.3.4. port()
               2.3.5. params()
               2.3.6. headers()
               2.3.7. transport()
               2.3.8. ttl()
               2.3.9. user_param()
               2.3.10. maddr()
               2.3.11. method()
               2.3.12. lr()
               2.3.13. r2()
               2.3.14. transport_val()
               2.3.15. ttl_val()
               2.3.16. user_param_val()
               2.3.17. maddr_val()
               2.3.18. method_val()
               2.3.19. lr_val()
               2.3.20. r2_val()
 
873d51d6
         2.4. OpenSER::AVP
033b5989
 
               2.4.1. add(name,val)
               2.4.2. get(name)
               2.4.3. destroy(name)
 
873d51d6
         2.5. OpenSER::Utils::PhoneNumbers
033b5989
 
               2.5.1.
989206bd
                       new(publicAccessPrefix,internationalPrefix,lon
                       gDistancePrefix,countryCode,areaCode,pbxCode
                       )
ac9ce6fb
 
033b5989
               2.5.2. canonicalForm( number [, context] )
               2.5.3. dialNumber( number [, context] )
ac9ce6fb
 
873d51d6
         2.6. OpenSER::LDAPUtils::LDAPConf
ac9ce6fb
 
033b5989
               2.6.1. Constructor new()
               2.6.2. Method base()
               2.6.3. Method host()
               2.6.4. Method port()
               2.6.5. Method uri()
               2.6.6. Method rootbindpw()
               2.6.7. Method rootbinddn()
               2.6.8. Method binddn()
               2.6.9. Method bindpw()
ac9ce6fb
 
873d51d6
         2.7. OpenSER::LDAPUtils::LDAPConnection
ac9ce6fb
 
033b5989
               2.7.1. Constructor new( [config, [authenticated]] )
               2.7.2. Function/Method search( conf, filter, base,
ac9ce6fb
                       [requested_attributes ...])
 
873d51d6
         2.8. OpenSER::VDB
         2.9. OpenSER::Constants
         2.10. OpenSER::VDB::Adapter::Speeddial
         2.11. OpenSER::VDB::Adapter::Alias
9125d64c
 
033b5989
               2.11.1. query(conds,retkeys,order)
9125d64c
 
873d51d6
         2.12. OpenSER::VDB::Adapter::AccountingSIPtrace
         2.13. OpenSER::VDB::Adapter::Describe
         2.14. OpenSER::VDB::Adapter::Auth
         2.15. OpenSER::VDB::ReqCond
9125d64c
 
033b5989
               2.15.1. new(key,op,type,name)
               2.15.2. op()
9125d64c
 
873d51d6
         2.16. OpenSER::VDB::Pair
9125d64c
 
033b5989
               2.16.1. new(key,type,name)
               2.16.2. key()
9125d64c
 
873d51d6
         2.17. OpenSER::VDB::VTab
9125d64c
 
033b5989
               2.17.1. new()
               2.17.2. call(op,[args])
9125d64c
 
873d51d6
         2.18. OpenSER::VDB::Value
9125d64c
 
033b5989
               2.18.1. stringification
               2.18.2. new(type,data)
               2.18.3. type()
               2.18.4. data()
9125d64c
 
873d51d6
         2.19. OpenSER::VDB::Column
9125d64c
 
033b5989
               2.19.1. Stringification
               2.19.2. new(type,name)
               2.19.3. type( )
               2.19.4. name()
873d51d6
               2.19.5. OpenSER::VDB::Result
033b5989
               2.19.6. new(coldefs,[row, row, ...])
               2.19.7. coldefs()
               2.19.8. rows()
ac9ce6fb
 
033b5989
    3. Perl samples
ac9ce6fb
 
033b5989
         3.1. sample directory
ac9ce6fb
 
033b5989
               3.1.1. Script descriptions
ac9ce6fb
 
033b5989
    4. Frequently Asked Questions
ac9ce6fb
 
    List of Examples
d77df08a
 
    1.1. Set filename parameter
    1.2. Set modpath parameter
    1.3. perl_exec_simple() usage
    1.4. perl_exec() usage
ac9ce6fb
 
9fc784c6
 Chapter 1. Admin Guide
ac9ce6fb
 
 1.1. Overview
 
873d51d6
    The time needed when writing a new Kamailio module
    unfortunately is quite high, while the options provided by the
    configuration file are limited to the features implemented in
    the modules.
ac9ce6fb
 
    With this Perl module, you can easily implement your own
ded7d208
    Kamailio extensions in Perl. This allows for simple access to
ac9ce6fb
    the full world of CPAN modules. SIP URI rewriting could be
    implemented based on regular expressions; accessing arbitrary
989206bd
    data backends, e.g. LDAP or Berkeley DB files, is now extremely
    simple.
ac9ce6fb
 
 1.2. Installing the module
 
ded7d208
    This Perl module is loaded in kamailio.cfg (just like all the
ac9ce6fb
    other modules) with loadmodule("/path/to/perl.so");.
 
    For the Perl module to compile, you need a reasonably recent
    version of perl (tested with 5.8.8) linked dynamically. It is
    strongly advised to use a threaded version. The default binary
    packages from your favorite Linux distribution should work
    fine.
f881cc19
 
989206bd
    Cross compilation is supported by the Makefile. You need to set
    the environment variables PERLLDOPTS, PERLCCOPTS and TYPEMAP to
    values similar to the output of
f881cc19
 PERLLDOPTS: perl -MExtUtils::Embed -e ldopts
 PERLCCOPTS: perl -MExtUtils::Embed -e ccopts
989206bd
 TYPEMAP:    echo "`perl -MConfig -e 'print $Config{installprivlib}'`/Ext
 Utils/typemap"
f881cc19
 
    The exact position of your (precompiled!) perl libraries
    depends on the setup of your environment.
ac9ce6fb
 
 1.3. Using the module
 
    The Perl module has two interfaces: The perl side, and the
ded7d208
    Kamailio side. Once a Perl function is defined and loaded via
ac9ce6fb
    the module parameters (see below), it may be called in
ded7d208
    Kamailio's configuration at an arbitary point. E.g., you could
ac9ce6fb
    write a function "ldap_alias" in Perl, and then execute
 ...
 if (perl_exec("ldap_alias")) {
         ...
 }
 ...
 
    just as you would have done with the current alias_db module.
 
d77df08a
    The functions you can use are listed in the "Exported
    Functions" section below.
ac9ce6fb
 
    On the Perl side, there are a number of functions that let you
    read and modify the current SIP message, such as the RURI or
    the message flags. An introduction to the Perl interface and
    the full reference documentation can be found below.
 
 1.4. Dependencies
 
37e4f522
 1.4.1. Kamailio Modules
ac9ce6fb
 
    The following modules must be loaded before this module:
      * The "sl" module is needed for sending replies uppon fatal
        errors. All other modules can be accessed from the Perl
        module, though.
 
 1.4.2. External Libraries or Applications
 
    The following libraries or applications must be installed
37e4f522
    before running Kamailio with this module loaded:
3968ae57
      * Perl 5.8.x or later
fa82deb3
 
989206bd
    Additionally, a number of perl modules should be installed. The
    Kamailio::LDAPUtils package relies on Net::LDAP to be
873d51d6
    installed. One of the sample scripts needs IPC::Shareable
fa82deb3
 
3968ae57
    This module has been developed and tested with Perl 5.8.8, but
    should work with any 5.8.x release. Compilation is possible
f881cc19
    with 5.6.x, but its behavior is unsupported. Earlier versions
3968ae57
    do not work.
 
3a37b32f
    On current Debian systems, at least the following packages
    should be installed:
fa82deb3
      * perl
      * perl-base
      * perl-modules
      * libperl5.8
      * libperl-dev
      * libnet-ldap-perl
      * libipc-shareable-perl
 
3a37b32f
    It was reported that other Debian-style distributions (such as
    Ubuntu) need the same packages.
 
fa82deb3
    On SuSE systems, at least the following packages should be
    installed:
      * perl
      * perl-ldap
      * IPC::Shareable perl module from CPAN
 
    Although SuSE delivers a lot of perl modules, others may have
    to be fetched from CPAN. Consider using the program "cpan2rpm"
    - which, in turn, is available on CPAN. It creates RPM files
    from CPAN.
ac9ce6fb
 
 1.5. Exported Parameters
 
 1.5.1. filename (string)
 
    This is the file name of your script. This may be set once
    only, but it may include an arbitary number of functions and
    "use" as many Perl module as necessary.
 
989206bd
    May not be empty!
ac9ce6fb
 
d77df08a
    Example 1.1. Set filename parameter
ac9ce6fb
 ...
b16e367d
 modparam("perl", "filename", "/home/john/openser/myperl.pl")
ac9ce6fb
 ...
 
 1.5.2. modpath (string)
 
873d51d6
    The path to the Perl modules included (Kamailio.pm et.al). It
    is not absolutely crucial to set this path, as you may install
    the Modules in Perl's standard path, or update the "%INC"
    variable from within your script. Using this module parameter
2b138a29
    is the standard behavior, though. Multiple paths may be
    specified by separating them with a ":" character. The maximum
    is 10 paths.
ac9ce6fb
 
d77df08a
    Example 1.2. Set modpath parameter
ac9ce6fb
 ...
b16e367d
 modparam("perl", "modpath", "/usr/local/lib/openser/perl/")
ac9ce6fb
 ...
 
 1.6. Exported Functions
 
d77df08a
 1.6.1.  perl_exec_simple(func, [param])
ac9ce6fb
 
    Calls a perl function without passing it the current SIP
    message. May be used for very simple simple requests that do
    not have to fiddle with the message themselves, but rather
    return information values about the environment.
 
    The first parameter is the function to be called. An arbitrary
    string may optionally be passed as a parameter.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE and BRANCH_ROUTE.
 
d77df08a
    Example 1.3. perl_exec_simple() usage
ac9ce6fb
 ...
 if (method=="INVITE") {
         perl_exec_simple("dosomething", "on invite messages");
 };
 ...
 
d77df08a
 1.6.2.  perl_exec(func, [param])
ac9ce6fb
 
    Calls a perl function with passing it the current SIP message.
    The SIP message is reflected by a Perl module that gives you
    access to the information in the current SIP message
ded7d208
    (Kamailio::Message).
ac9ce6fb
 
    The first parameter is the function to be called. An arbitrary
    string may be passed as a parameter.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE and BRANCH_ROUTE.
 
d77df08a
    Example 1.4. perl_exec() usage
ac9ce6fb
 ...
 if (perl_exec("ldapalias")) {
         ...
 };
 ...
 
873d51d6
 Chapter 2. OpenSER Perl API
ac9ce6fb
 
873d51d6
 2.1. OpenSER
ac9ce6fb
 
989206bd
    This module provides access to a limited number of OpenSER core
    functions. As the most interesting functions deal with SIP
    messages, they are located in the OpenSER::Message class below.
ac9ce6fb
 
033b5989
 2.1.1. log(level,message)
ac9ce6fb
 
873d51d6
    Logs the message with OpenSER's logging facility. The logging
ac9ce6fb
    level is one of the following:
 * L_ALERT
 * L_CRIT
 * L_ERR
 * L_WARN
 * L_NOTICE
 * L_INFO
 * L_DBG
 
    Please note that this method is NOT automatically exported, as
    it collides with the perl function log (which calculates the
    logarithm). Either explicitly import the function (via use
873d51d6
    OpenSER qw ( log );), or call it with its full name:
 OpenSER::log(L_INFO, "foobar");
ac9ce6fb
 
873d51d6
 2.2. OpenSER::Message
ac9ce6fb
 
873d51d6
    This package provides access functions for an OpenSER sip_msg
a197aebf
    structure and its sub-components. Through its means it is
ac9ce6fb
    possible to fully configure alternative routing decisions.
 
033b5989
 2.2.1. getType()
1624884c
 
    Returns one of the constants SIP_REQUEST, SIP_REPLY,
    SIP_INVALID stating the type of the current message.
 
033b5989
 2.2.2. getStatus()
1624884c
 
    Returns the status code of the current Reply message. This
    function is invalid in Request context!
 
033b5989
 2.2.3. getReason()
1624884c
 
    Returns the reason of the current Reply message. This function
    is invalid in Request context!
 
033b5989
 2.2.4. getVersion()
1624884c
 
    Returns the version string of the current SIP message.
 
033b5989
 2.2.5. getRURI()
ac9ce6fb
 
    This function returns the recipient URI of the present SIP
    message:
 
    my $ruri = $m->getRURI();
 
    getRURI returns a string. See "getParsedRURI()" below how to
    receive a parsed structure.
1624884c
 
    This function is valid in request messages only.
ac9ce6fb
 
033b5989
 2.2.6. getMethod()
ac9ce6fb
 
    Returns the current method, such as INVITE, REGISTER, ACK and
    so on.
 
    my $method = $m->getMethod();
1624884c
 
    This function is valid in request messages only.
ac9ce6fb
 
033b5989
 2.2.7. getFullHeader()
ac9ce6fb
 
    Returns the full message header as present in the current
989206bd
    message. You might use this header to further work with it with
    your favorite MIME package.
ac9ce6fb
 
    my $hdr = $m->getFullHeader();
 
033b5989
 2.2.8. getBody()
5f7671ee
 
    Returns the message body.
 
033b5989
 2.2.9. getMessage()
18bd76e4
 
    Returns the whole message including headers and body.
 
033b5989
 2.2.10. getHeader(name)
ac9ce6fb
 
    Returns the body of the first message header with this name.
 
    print $m->getHeader("To");
 
    "John" <sip:john@doe.example>
 
033b5989
 2.2.11. getHeaderNames()
ac9ce6fb
 
    Returns an array of all header names. Duplicates possible!
 
033b5989
 2.2.12. moduleFunction(func,string1,string2)
ac9ce6fb
 
    Search for an arbitrary function in module exports and call it
    with the parameters self, string1, string2.
 
    string1 and/or string2 may be omitted.
 
    As this function provides access to the functions that are
873d51d6
    exported to the OpenSER configuration file, it is autoloaded
ac9ce6fb
    for unknown functions. Instead of writing
 $m->moduleFunction("sl_send_reply", "500", "Internal Error");
 $m->moduleFunction("xlog", "L_INFO", "foo");
 
    you may as well write
 $m->sl_send_reply("500", "Internal Error");
 $m->xlog("L_INFO", "foo");
a6c8d0e4
 
    WARNING
 
873d51d6
    In OpenSER 1.2, only a limited subset of module functions is
989206bd
    available. This restriction will be removed in a later version.
a6c8d0e4
 
    Here is a list of functions that are expected to be working
    (not claiming completeness):
 * alias_db_lookup
 * consume_credentials
 * is_rpid_user_e164
 * append_rpid_hf
 * bind_auth
 * avp_print
 * cpl_process_register
 * cpl_process_register_norpl
 * load_dlg
 * ds_next_dst
 * ds_next_domain
 * ds_mark_dst
 * ds_mark_dst
 * is_from_local
 * is_uri_host_local
 * dp_can_connect
 * dp_apply_policy
 * enum_query (without parameters)
 * enum_fquery (without parameters)
 * is_from_user_enum (without parameters)
 * i_enum_query (without parameters)
 * imc_manager
 * jab_* (all functions from the jabber module)
 * load_gws (without parameters)
 * next_gw
 * from_gw (without parameters)
 * to_gw (without parameters)
 * load_contacts
 * next_contacts
 * sdp_mangle_ip
 * sdp_mangle_port
 * encode_contact
 * decode_contact
 * decode_contact_header
 * fix_contact
 * use_media_proxy
 * end_media_session
 * m_store
 * m_dump
 * fix_nated_contact
 * unforce_rtp_proxy
 * force_rtp_proxy
 * fix_nated_register
 * add_rcv_param
 * options_reply
 * checkospheader
 * validateospheader
 * requestosprouting
 * checkosproute
 * prepareosproute
 * prepareallosproutes
 * checkcallingtranslation
 * reportospusage
 * mangle_pidf
 * mangle_message_cpim
 * add_path (without parameters)
 * add_path_received (without parameters)
 * prefix2domain
 * allow_routing (without parameters)
 * allow_trusted
 * pike_check_req
 * handle_publish
 * handle_subscribe
 * stored_pres_info
 * bind_pua
 * send_publish
 * send_subscribe
 * pua_set_publish
 * loose_route
 * record_route
 * load_rr
 * sip_trace
 * sl_reply_error
 * sms_send_msg
 * sd_lookup
 * sstCheckMin
 * append_time
 * has_body (without parameters)
 * is_peer_verified
 * t_newtran
 * t_release
 * t_relay (without parameters)
 * t_flush_flags
 * t_check_trans
 * t_was_cancelled
69ead4ab
 * t_load_contacts
 * t_next_contacts
a6c8d0e4
 * uac_restore_from
 * uac_auth
 * has_totag
 * tel2sip
 * check_to
 * check_from
 * radius_does_uri_exist
 * ul_* (All functions exported by the usrloc module for user access)
 * xmpp_send_message
ac9ce6fb
 
033b5989
 2.2.13. log(level,message) (deprecated type)
ac9ce6fb
 
873d51d6
    Logs the message with OpenSER's logging facility. The logging
ac9ce6fb
    level is one of the following:
 * L_ALERT
 * L_CRIT
 * L_ERR
 * L_WARN
 * L_NOTICE
 * L_INFO
 * L_DBG
 
873d51d6
    The logging function should be accessed via the OpenSER module
    variant. This one, located in OpenSER::Message, is deprecated.
ac9ce6fb
 
033b5989
 2.2.14. rewrite_ruri(newruri)
ac9ce6fb
 
    Sets a new destination (recipient) URI. Useful for rerouting
    the current message/call.
 if ($m->getRURI() =~ m/\@somedomain.net/) {
   $m->rewrite_ruri("sip:dispatcher\@organization.net");
 }
 
033b5989
 2.2.15. setFlag(flag)
ac9ce6fb
 
    Sets a message flag. The constants as known from the C API may
    be used, when Constants.pm is included.
 
033b5989
 2.2.16. resetFlag(flag)
ac9ce6fb
 
    Resets a message flag.
 
033b5989
 2.2.17. isFlagSet(flag)
ac9ce6fb
 
    Returns whether a message flag is set or not.
 
033b5989
 2.2.18. pseudoVar(string)
ac9ce6fb
 
989206bd
    Returns a new string where all pseudo variables are substituted
    by their values. Can be used to receive the values of single
    variables, too.
ac9ce6fb
 
    Please remember that you need to escape the '$' sign in perl
    strings!
 
033b5989
 2.2.19. append_branch(branch,qval)
ac9ce6fb
 
    Append a branch to current message.
 
69ead4ab
 2.2.20. getParsedRURI()
ac9ce6fb
 
873d51d6
    Returns the current destination URI as an OpenSER::URI object.
ac9ce6fb
 
873d51d6
 2.3. OpenSER::URI
ac9ce6fb
 
    This package provides functions for access to sip_uri
    structures.
 
033b5989
 2.3.1. user()
ac9ce6fb
 
    Returns the user part of this URI.
 
033b5989
 2.3.2. host()
ac9ce6fb
 
    Returns the host part of this URI.
 
033b5989
 2.3.3. passwd()
ac9ce6fb
 
    Returns the passwd part of this URI.
 
033b5989
 2.3.4. port()
ac9ce6fb
 
    Returns the port part of this URI.
 
033b5989
 2.3.5. params()
ac9ce6fb
 
    Returns the params part of this URI.
 
033b5989
 2.3.6. headers()
ac9ce6fb
 
    Returns the headers part of this URI.
 
033b5989
 2.3.7. transport()
ac9ce6fb
 
    Returns the transport part of this URI.
 
033b5989
 2.3.8. ttl()
ac9ce6fb
 
    Returns the ttl part of this URI.
 
033b5989
 2.3.9. user_param()
ac9ce6fb
 
    Returns the user_param part of this URI.
 
033b5989
 2.3.10. maddr()
ac9ce6fb
 
    Returns the maddr part of this URI.
 
033b5989
 2.3.11. method()
ac9ce6fb
 
    Returns the method part of this URI.
 
033b5989
 2.3.12. lr()
ac9ce6fb
 
    Returns the lr part of this URI.
 
033b5989
 2.3.13. r2()
ac9ce6fb
 
    Returns the r2 part of this URI.
 
033b5989
 2.3.14. transport_val()
ac9ce6fb
 
    Returns the transport_val part of this URI.
 
033b5989
 2.3.15. ttl_val()
ac9ce6fb
 
    Returns the ttl_val part of this URI.
 
033b5989
 2.3.16. user_param_val()
ac9ce6fb
 
    Returns the user_param_val part of this URI.
 
033b5989
 2.3.17. maddr_val()
ac9ce6fb
 
    Returns the maddr_val part of this URI.
 
033b5989
 2.3.18. method_val()
ac9ce6fb
 
    Returns the method_val part of this URI.
 
033b5989
 2.3.19. lr_val()
ac9ce6fb
 
    Returns the lr_val part of this URI.
 
033b5989
 2.3.20. r2_val()
ac9ce6fb
 
    Returns the r2_val part of this URI.
 
873d51d6
 2.4. OpenSER::AVP
1b0f7ad6
 
873d51d6
    This package provides access functions for OpenSER's AVPs.
989206bd
    These variables can be created, evaluated, modified and removed
    through this package.
1b0f7ad6
 
    Please note that these functions do NOT support the notation
989206bd
    used in the configuration file, but directly work on strings or
    numbers. See documentation of add method below.
1b0f7ad6
 
033b5989
 2.4.1. add(name,val)
1b0f7ad6
 
    Add an AVP.
 
989206bd
    Add an OpenSER AVP to its environment. name and val may both be
    integers or strings; this function will try to guess what is
    correct. Please note that
873d51d6
 OpenSER::AVP::add("10", "10")
1b0f7ad6
 
    is something different than
873d51d6
 OpenSER::AVP::add(10, 10)
1b0f7ad6
 
    due to this evaluation: The first will create _string_ AVPs
989206bd
    with the name 10, while the latter will create a numerical AVP.
1b0f7ad6
 
    You can modify/overwrite AVPs with this function.
 
033b5989
 2.4.2. get(name)
1b0f7ad6
 
873d51d6
    get an OpenSER AVP:
 my $numavp = OpenSER::AVP::get(5);
 my $stravp = OpenSER::AVP::get("foo");
1b0f7ad6
 
033b5989
 2.4.3. destroy(name)
1b0f7ad6
 
    Destroy an AVP.
873d51d6
 OpenSER::AVP::destroy(5);
 OpenSER::AVP::destroy("foo");
1b0f7ad6
 
873d51d6
 2.5. OpenSER::Utils::PhoneNumbers
ac9ce6fb
 
989206bd
    OpenSER::Utils::PhoneNumbers - Functions for canonical forms of
    phone numbers.
873d51d6
 use OpenSER::Utils::PhoneNumbers;
ac9ce6fb
 
873d51d6
 my $phonenumbers = new OpenSER::Utils::PhoneNumbers(
ac9ce6fb
      publicAccessPrefix => "0",
      internationalPrefix => "+",
      longDistancePrefix => "0",
      areaCode => "761",
      pbxCode => "456842",
      countryCode => "49"
    );
 
d6b411ea
 $canonical = $phonenumbers->canonicalForm("07612034567");
 $number    = $phonenumbers->dialNumber("+497612034567");
ac9ce6fb
 
    A telphone number starting with a plus sign and containing all
    dial prefixes is in canonical form. This is usally not the
    number to dial at any location, so the dialing number depends
    on the context of the user/system.
 
    The idea to canonicalize numbers were taken from hylafax.
 
    Example: +497614514829 is the canonical form of my phone
    number, 829 is the number to dial at Pyramid, 4514829 is the
    dialing number from Freiburg are and so on.
 
    To canonicalize any number, we strip off any dial prefix we
    find and then add the prefixes for the location. So, when the
    user enters the number 04514829 in context pyramid, we remove
989206bd
    the publicAccessPrefix (at Pyramid this is 0) and the pbxPrefix
    (4514 here). The result is 829. Then we add all the general
    dial prefixes - 49 (country) 761 (area) 4514 (pbx) and 829, the
    number itself => +497614514829
ac9ce6fb
 
    To get the dialing number from a canonical phone number, we
    substract all general prefixes until we have something
 
989206bd
    As said before, the interpretation of a phone number depends on
    the context of the location. For the functions in this package,
    the context is created through the new operator.
ac9ce6fb
 
    The following fields should be set:
 'longDistancePrefix'
 'areaCode'
 'pbxCode'
 'internationalPrefix'
 'publicAccessPrefix'
 'countryCode'
 
    This module exports the following functions when useed:
 
989206bd
 2.5.1. new(publicAccessPrefix,internationalPrefix,longDistancePrefix,
 countryCode,areaCode,pbxCode)
ac9ce6fb
 
9125d64c
    The new operator returns an object of this type and sets its
ac9ce6fb
    locational context according to the passed parameters. See
873d51d6
    OpenSER::Utils::PhoneNumbers above.
ac9ce6fb
 
033b5989
 2.5.2. canonicalForm( number [, context] )
ac9ce6fb
 
9125d64c
    Convert a phone number (given as first argument) into its
ac9ce6fb
    canonical form. When no context is passed in as the second
    argument, the default context from the systems configuration
    file is used.
 
033b5989
 2.5.3. dialNumber( number [, context] )
ac9ce6fb
 
    Convert a canonical phone number (given in the first argument)
    into a number to to dial. WHen no context is given in the
    second argument, a default context from the systems
    configuration is used.
 
873d51d6
 2.6. OpenSER::LDAPUtils::LDAPConf
ac9ce6fb
 
873d51d6
    OpenSER::LDAPUtils::LDAPConf - Read openldap config from
ac9ce6fb
    standard config files.
873d51d6
 use OpenSER::LDAPUtils::LDAPConf;
 my $conf = new OpenSER::LDAPUtils::LDAPConf();
ac9ce6fb
 
    This module may be used to retrieve the global LDAP
    configuration as used by other LDAP software, such as
    nsswitch.ldap and pam-ldap. The configuration is usualy stored
    in /etc/openldap/ldap.conf
 
    When used from an account with sufficient privilegs (e.g.
    root), the ldap manager passwort is also retrieved.
 
033b5989
 2.6.1. Constructor new()
ac9ce6fb
 
989206bd
    Returns a new, initialized OpenSER::LDAPUtils::LDAPConf object.
ac9ce6fb
 
033b5989
 2.6.2. Method base()
ac9ce6fb
 
    Returns the servers base-dn to use when doing queries.
 
033b5989
 2.6.3. Method host()
ac9ce6fb
 
    Returns the ldap host to contact.
 
033b5989
 2.6.4. Method port()
ac9ce6fb
 
    Returns the ldap servers port.
 
033b5989
 2.6.5. Method uri()
ac9ce6fb
 
    Returns an uri to contact the ldap server. When there is no
    ldap_uri in the configuration file, an ldap: uri is constucted
    from host and port.
 
033b5989
 2.6.6. Method rootbindpw()
ac9ce6fb
 
    Returns the ldap "root" password.
 
    Note that the rootbindpw is only available when the current
    account has sufficient privilegs to access
    /etc/openldap/ldap.secret.
 
033b5989
 2.6.7. Method rootbinddn()
ac9ce6fb
 
    Returns the DN to use for "root"-access to the ldap server.
 
033b5989
 2.6.8. Method binddn()
ac9ce6fb
 
    Returns the DN to use for authentication to the ldap server.
    When no bind dn has been specified in the configuration file,
    returns the rootbinddn.
 
033b5989
 2.6.9. Method bindpw()
ac9ce6fb
 
    Returns the password to use for authentication to the ldap
    server. When no bind password has been specified, returns the
    rootbindpw if any.
 
873d51d6
 2.7. OpenSER::LDAPUtils::LDAPConnection
ac9ce6fb
 
873d51d6
    OpenSER::LDAPUtils::LDAPConnection - Perl module to perform
ac9ce6fb
    simple LDAP queries.
 
    OO-Style interface:
873d51d6
 use OpenSER::LDAPUtils::LDAPConnection;
 my $ldap = new OpenSER::LDAPUtils::LDAPConnection;
ac9ce6fb
 my @rows = $ldap-search("uid=andi","ou=people,ou=coreworks,ou=de");
 
    Procedural interface:
873d51d6
 use OpenSER::LDAPUtils::LDAPConnection;
ac9ce6fb
 my @rows = $ldap->search(
989206bd
       new OpenSER::LDAPUtils::LDAPConfig(), "uid=andi","ou=people,ou=cor
 eworks,ou=de");
ac9ce6fb
 
    This perl module offers a somewhat simplified interface to the
    Net::LDAP functionality. It is intended for cases where just a
    few attributes should be retrieved without the overhead of the
    full featured Net::LDAP.
 
033b5989
 2.7.1. Constructor new( [config, [authenticated]] )
ac9ce6fb
 
    Set up a new LDAP connection.
 
    The first argument, when given, should be a hash reference
    pointing to to the connection parameters, possibly an
873d51d6
    OpenSER::LDAPUtils::LDAPConfig object. This argument may be
ac9ce6fb
    undef in which case a new (default)
873d51d6
    OpenSER::LDAPUtils::LDAPConfig object is used.
ac9ce6fb
 
    When the optional second argument is a true value, the
    connection will be authenticated. Otherwise an anonymous bind
    is done.
 
    On success, a new LDAPConnection object is returned, otherwise
    the result is undef.
 
033b5989
 2.7.2. Function/Method search( conf, filter, base,
ac9ce6fb
 [requested_attributes ...])
 
    perform an ldap search, return the dn of the first matching
    directory entry, unless a specific attribute has been
    requested, in wich case the values(s) fot this attribute are
    returned.
 
    When the first argument (conf) is a
873d51d6
    OpenSER::LDAPUtils::LDAPConnection, it will be used to perform
ac9ce6fb
    the queries. You can pass the first argument implicitly by
    using the "method" syntax.
 
    Otherwise the conf argument should be a reference to a hash
    containing the connection setup parameters as contained in a
873d51d6
    OpenSER::LDAPUtils::LDAPConf object. In this mode, the
    OpenSER::LDAPUtils::LDAPConnection from previous queries will
ac9ce6fb
    be reused.
 
033b5989
 2.7.2.1. Arguments:
ac9ce6fb
 
    conf
           configuration object, used to find host,port,suffix and
           use_ldap_checks
 
    filter
           ldap search filter, eg '(mail=some@domain)'
 
    base
989206bd
           search base for this query. If undef use default suffix,
           concat base with default suffix if the last char is a
           ','
ac9ce6fb
 
    requested_attributes
989206bd
           retrieve the given attributes instead of the dn from the
           ldap directory.
ac9ce6fb
 
033b5989
 2.7.2.2. Result:
ac9ce6fb
 
989206bd
    Without any specific requested_attributes, return the dn of all
    matching entries in the LDAP directory.
ac9ce6fb
 
    When some requested_attributes are given, return an array with
    those attibutes. When multiple entries match the query, the
    attribute lists are concatenated.
 
873d51d6
 2.8. OpenSER::VDB
9125d64c
 
    This package is an (abstract) base class for all virtual
    databases. Derived packages can be configured to be used by
873d51d6
    OpenSER as a database.
9125d64c
 
989206bd
    The base class itself should NOT be used in this context, as it
    does not provide any functionality.
9125d64c
 
873d51d6
 2.9. OpenSER::Constants
ac9ce6fb
 
    This package provides a number of constants taken from enums
989206bd
    and defines of OpenSER header files. Unfortunately, there is no
    mechanism for updating the constants automatically, so check
    the values if you are in doubt.
9125d64c
 
873d51d6
 2.10. OpenSER::VDB::Adapter::Speeddial
9125d64c
 
    This adapter can be used with the speeddial module.
 
873d51d6
 2.11. OpenSER::VDB::Adapter::Alias
9125d64c
 
    This package is intended for usage with the alias_db module.
989206bd
    The query VTab has to take two arguments and return an array of
    two arguments (user name/domain).
9125d64c
 
033b5989
 2.11.1. query(conds,retkeys,order)
9125d64c
 
    Queries the vtab with the given arguments for request
    conditions, keys to return and sort order column name.
 
873d51d6
 2.12. OpenSER::VDB::Adapter::AccountingSIPtrace
9125d64c
 
    This package is an Adapter for the acc and siptrace modules,
    featuring only an insert operation.
 
873d51d6
 2.13. OpenSER::VDB::Adapter::Describe
9125d64c
 
    This package is intended for debug usage. It will print
    information about requested functions and operations of a
    client module.
 
989206bd
    Use this module to request schema information when creating new
    adapters.
9125d64c
 
873d51d6
 2.14. OpenSER::VDB::Adapter::Auth
9125d64c
 
989206bd
    This adapter is intended for usage with the auth_db module. The
    VTab should take a username as an argument and return a (plain
    text!) password.
9125d64c
 
873d51d6
 2.15. OpenSER::VDB::ReqCond
9125d64c
 
    This package represents a request condition for database
    access, consisting of a column name, an operator (=, <, >,
    ...), a data type and a value.
 
989206bd
    This package inherits from OpenSER::VDB::Pair and thus includes
    its methods.
9125d64c
 
033b5989
 2.15.1. new(key,op,type,name)
9125d64c
 
    Constructs a new Column object.
 
033b5989
 2.15.2. op()
9125d64c
 
    Returns or sets the current operator.
 
873d51d6
 2.16. OpenSER::VDB::Pair
9125d64c
 
989206bd
    This package represents database key/value pairs, consisting of
    a key, a value type, and the value.
9125d64c
 
989206bd
    This package inherits from OpenSER::VDB::Value and thus has the
    same methods.
9125d64c
 
033b5989
 2.16.1. new(key,type,name)
9125d64c
 
    Constructs a new Column object.
 
033b5989
 2.16.2. key()
9125d64c
 
    Returns or sets the current key.
 
873d51d6
 2.17. OpenSER::VDB::VTab
9125d64c
 
    This package handles virtual tables and is used by the
989206bd
    OpenSER::VDB class to store information about valid tables. The
    package is not inteded for end user access.
9125d64c
 
033b5989
 2.17.1. new()
9125d64c
 
 Constructs a new VTab object
 
033b5989
 2.17.2. call(op,[args])
9125d64c
 
    Invokes an operation on the table (insert, update, ...) with
    the given arguments.
 
873d51d6
 2.18. OpenSER::VDB::Value
9125d64c
 
    This package represents a database value. Additional to the
    data itself, information about its type is stored.
 
033b5989
 2.18.1. stringification
9125d64c
 
873d51d6
    When accessing a OpenSER::VDB::Value object as a string, it
9125d64c
    simply returns its data regardless of its type. =cut
 
    use strict;
 
873d51d6
    package OpenSER::VDB::Value;
9125d64c
 
    use overload '""' => \&stringify;
 
    sub stringify { shift->{data} }
 
873d51d6
    use OpenSER; use OpenSER::Constants;
9125d64c
 
873d51d6
    our @ISA = qw ( OpenSER::Utils::Debug );
9125d64c
 
033b5989
 2.18.2. new(type,data)
9125d64c
 
    Constructs a new Value object. Its data type and the data are
    passed as parameters.
 
033b5989
 2.18.3. type()
9125d64c
 
    Returns or sets the current data type. Please consider using
873d51d6
    the constants from OpenSER::Constants
9125d64c
 
033b5989
 2.18.4. data()
9125d64c
 
    Returns or sets the current data.
 
873d51d6
 2.19. OpenSER::VDB::Column
9125d64c
 
    This package represents database column definition, consisting
    of a column name and its data type.
 
033b5989
 2.19.1. Stringification
9125d64c
 
873d51d6
    When accessing a OpenSER::VDB::Column object as a string, it
9125d64c
    simply returns its column name regardless of its type. =cut
 
873d51d6
    package OpenSER::VDB::Column;
9125d64c
 
    use overload '""' => \&stringify;
 
    sub stringify { shift->{name} }
 
873d51d6
    use OpenSER; use OpenSER::Constants;
9125d64c
 
873d51d6
    our @ISA = qw ( OpenSER::Utils::Debug );
9125d64c
 
033b5989
 2.19.2. new(type,name)
9125d64c
 
    Constructs a new Column object. Its type and the name are
    passed as parameters.
 
033b5989
 2.19.3. type( )
9125d64c
 
    Returns or sets the current type. Please consider using the
873d51d6
    constants from OpenSER::Constants
9125d64c
 
033b5989
 2.19.4. name()
9125d64c
 
    Returns or sets the current column name.
 
873d51d6
 2.19.5. OpenSER::VDB::Result
9125d64c
 
    This class represents a VDB result set. It contains a column
    definition, plus an array of rows. Rows themselves are simply
    references to arrays of scalars.
 
033b5989
 2.19.6. new(coldefs,[row, row, ...])
9125d64c
 
    The constructor creates a new Result object. Its first
873d51d6
    parameter is a reference to an array of OpenSER::VDB::Column
989206bd
    objects. Additional parameters may be passed to provide initial
    rows, which are references to arrays of scalars.
9125d64c
 
033b5989
 2.19.7. coldefs()
9125d64c
 
 Returns or sets the column definition of the object.
 
033b5989
 2.19.8. rows()
9125d64c
 
 Returns or sets the rows of the object.
ac9ce6fb
 
033b5989
 Chapter 3. Perl samples
ac9ce6fb
 
d77df08a
    Revision History
69ead4ab
    Revision $Revision$ $Date: 2008-03-07 22:09:16 +0200
                               (Fri, 07 Mar 2008) $
d77df08a
 
033b5989
 3.1. sample directory
ac9ce6fb
 
    There are a number of example scripts in the "samples/". They
989206bd
    are documented well. Read them, it will explain a lot to you :)
ac9ce6fb
 
    If you want to use any of these scripts directly in your
    implementation, you can use Perl's "require" mechanism to
    import them (just remember that you need to use quotes when
    require'ing .pl files).
 
033b5989
 3.1.1. Script descriptions
ac9ce6fb
 
    The included sample scripts are described below:
 
033b5989
 3.1.1.1. branches.pl
ac9ce6fb
 
    The minimal function in branches.pl demonstrates that you can
    access the "append_branch" function from within perl, just as
989206bd
    you would have done from your normal configuration file. You'll
    find documentation on the concepts of branching in the OpenSER
    documentation.
ac9ce6fb
 
033b5989
 3.1.1.2. firstline.pl
1624884c
 
989206bd
    Message's first_line structure may be evaluated. Message can be
    either of SIP_REQUEST or SIP_REPLY. Depending on that,
    different information can be received. This script demonstrates
    these functions.
1624884c
 
033b5989
 3.1.1.3. flags.pl
ac9ce6fb
 
873d51d6
    The perl module provides access to OpenSER's flagging
    mechanism. The flag names available for OpenSER modules are
    made available through the OpenSER::Constants package, so you
ac9ce6fb
    can flag messages as "green", "magenta" etc.
 
    The first function, setflag, demonstrates how the "green" flag
    is set. In the second function, readflag, the "green" and
    "magenta" flags are evaluated.
 
033b5989
 3.1.1.4. functions.pl
ac9ce6fb
 
    This sample script demonstrates different things related to
    calling functions from within perl, and the different types of
873d51d6
    functions you can offer for OpenSER access.
ac9ce6fb
 
    "exportedfuncs" simply demonstrates that you can use the
    moduleFunction method to call functions offered by other
    modules. The results are equivalent to calling these functions
    from your config file. In the demonstrated case, telephone
    calls with a destination number beginning with 555... are
    rejected with an internal server error. Other destination
    addresses are passed to the alias_db module.
 
a6c8d0e4
    Please note that the moduleFunction method is not fully
873d51d6
    available in OpenSER 1.2. See the method's documentation for
a6c8d0e4
    details.
 
ac9ce6fb
    "paramfunc" shows that you can pass arbitrary strings to perl
    functions. Do with them whatever you want :)
 
    "autotest" demonstrates that unknown functions in
873d51d6
    OpenSER::Message objects are automatically transformed into
ac9ce6fb
    calls to module functions.
 
    The "diefunc"s show that dying perl scripts - by "manual"
989206bd
    dying, or because of script errors - are handled by the OpenSER
    package. The error message is logged through OpenSER's logging
    mechanism. Please note that this only works correctly if you do
    NOT overwrite the default die handler. Oh, yes, that works for
    warnings, too.
ac9ce6fb
 
033b5989
 3.1.1.5. headers.pl
ac9ce6fb
 
eab554f7
    Header extraction is among the most crucial functionalities
    while processing SIP messages. This sample script demonstrates
    access to header names and values within two sample functions.
ac9ce6fb
 
eab554f7
    "headernames" extracts all header names and logs their names.
ac9ce6fb
 
eab554f7
    "someheaders" logs the contents of the two headers, "To" and
    "WWW-Contact". As you can see, headers that occur more than
989206bd
    once are retrieved as an array, which may be accessed by Perl's
    array accessing methods.
ac9ce6fb
 
033b5989
 3.1.1.6. logging.pl
eab554f7
 
    For debugging purposes, you probably want to write messages to
    the syslog. The "logdemo" shows three ways to access the
989206bd
    OpenSER log function: it is available through the OpenSER class
    as well as through the OpenSER::Message class.
ac9ce6fb
 
eab554f7
    Remember that you can use exported functions from other
    modules. You may thus as well use the "xlog" module and it's
    xlog function.
 
    The L_INFO, L_DBG, L_ERR, L_CRIT... constants are available
873d51d6
    through the OpenSER::Constants package.
ac9ce6fb
 
033b5989
 3.1.1.7. messagedump.pl
ac9ce6fb
 
989206bd
    This script demonstrates how to access the whole message header
    of the current message. Please note that modifications on the
    message made by earlier function calls in your configuration
    script may NOT be reflected in this dump.
ac9ce6fb
 
033b5989
 3.1.1.8. persistence.pl
ac9ce6fb
 
eab554f7
    When processing SIP messages, you may want to use persistent
    data across multiple calls to your Perl functions. Your first
    option is to use global variables in your script.
    Unfortunately, these globals are not visible from the mulitple
873d51d6
    instances of OpenSER. You may want to use a mechanism such as
eab554f7
    the IPC::Shareable shared memory access package to correct
    this.
ac9ce6fb
 
033b5989
 3.1.1.9. phonenumbers.pl
ac9ce6fb
 
873d51d6
    The OpenSER::Utils::PhoneNumbers package provides two methods
989206bd
    for the transformation of local to canonical telephone numbers,
    and vice versa. This script demonstrates it's use.
ac9ce6fb
 
033b5989
 3.1.1.10. pseudovars.pl
eab554f7
 
    This script demonstrates the Perl module's "pseudoVar" method.
    It may be used to retrieve the values of current pseudo
    variables.
ac9ce6fb
 
eab554f7
    You might notice that there is no particular function for
    setting pseudo variables; you may use the exported functions
    from the avpops module, though.
ac9ce6fb
 
033b5989
 Chapter 4. Frequently Asked Questions
ac9ce6fb
 
d77df08a
    4.1.
 
989206bd
        Are there known bugs in the Perl module?
 
        The Perl module does have a few shortcomings that may be
        regarded as bugs.
          * Missing module functions. Not all functions of other
            modules are available for Perl access. The reason for this
            is a design property of OpenSER. Making available more
            functions is work in progress.
          * Perl and threads. Perl itself is, when compiled with the
            correct parameters, thread safe; unfortunately, not all
            Perl modules are. The DBI modules, especially (but not
            restricted to) DBI::ODBC are known NOT to be thread safe.
            Using DBI::ODBC -- and possibly other non-thread-safe Perl
            extensions -- may result in erroneous behavior of OpenSER,
            including (but not restricted to) server crashes and wrong
            routing.
3756d255
 
d77df08a
    4.2.
3756d255
 
989206bd
        Where can I find more about Kamailio?
 
        Take a look at http://www.kamailio.org/.
ac9ce6fb
 
d77df08a
    4.3.
ac9ce6fb
 
989206bd
        Where can I post a question about this module?
 
        First at all check if your question was already answered on one
        of our mailing lists:
          * User Mailing List -
            http://lists.kamailio.org/cgi-bin/mailman/listinfo/users
          * Developer Mailing List -
            http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel
ac9ce6fb
 
989206bd
        E-mails regarding any stable Kamailio release should be sent to
        <users@lists.kamailio.org> and e-mails regarding development
        versions should be sent to <devel@lists.kamailio.org>.
ac9ce6fb
 
989206bd
        If you want to keep the mail private, send it to
        <team@lists.kamailio.org>.
ac9ce6fb
 
d77df08a
    4.4.
ac9ce6fb
 
989206bd
        How can I report a bug?
ac9ce6fb
 
989206bd
        Please follow the guidelines provided at:
        http://sourceforge.net/tracker/?group_id=139143.