kamailio/modules/app_perl/doc/app_perl_pod.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!--
     Generated by Pod::DocBook v1.2, using:
       Digest::MD5 v2.36
       Pod::Parser v1.32
       Pod::ParseLink v1.06
       Text::ParseWords v3.24
       Text::Wrap v2005.082401
-->
<chapter><title>Kamailio Perl API</title>
  <section id="ID-d83a4c83b0cd455aef9602128b87c323"><title>Kamailio</title>
    <para>
      This module provides access to a limited number of Kamailio core
      functions. As the most interesting functions deal with SIP messages,
      they are located in the Kamailio::Message class below.
    </para>
    <section id="ID-3ae476990b7b1fe73d972e68eb52f93c"><title>log(level,message)</title>
      <para>
	Logs the message with Kamailio's logging facility. The logging level
	is one of the following:
      </para>
      <screen><![CDATA[* L_ALERT
* L_CRIT
* L_ERR
* L_WARN
* L_NOTICE
* L_INFO
* L_DBG]]></screen>
      <para>
	Please note that this method is <emphasis
	role="italic">NOT</emphasis> automatically exported, as it collides
	with the perl function log (which calculates the logarithm). Either
	explicitly import the function (via <literal
	role="code"><![CDATA[use Kamailio qw ( log );]]></literal>), or call
	it with its full name:
      </para>
      <screen><![CDATA[Kamailio::log(L_INFO, "foobar");]]></screen>
    </section>
  </section>
  <section id="ID-949656abaac653354242d1d0e9b418be"><title>Kamailio::Message</title>
    <para>
      This package provides access functions for an Kamailio <literal
      role="code"><![CDATA[sip_msg]]></literal> structure and its
      sub-components. Through its means it is possible to fully configure
      alternative routing decisions.
    </para>
    <section id="ID-4462b43922a45955436db6a77eff1274"><title>getType()</title>
      <para>
	Returns one of the constants SIP_REQUEST, SIP_REPLY, SIP_INVALID
	stating the type of the current message.
      </para>
    </section>
    <section id="ID-48eb6f3897940320d3dca81eee99e60f"><title>getStatus()</title>
      <para>
	Returns the status code of the current Reply message. This function
	is invalid in Request context!
      </para>
    </section>
    <section id="ID-06ad673da0ada52b0d53a16dc5edf3c7"><title>getReason()</title>
      <para>
	Returns the reason of the current Reply message. This function is
	invalid in Request context!
      </para>
    </section>
    <section id="ID-defa3c4593f2232a246f800880c3db8d"><title>getVersion()</title>
      <para>
	Returns the version string of the current SIP message.
      </para>
    </section>
    <section id="ID-40655f47473dfd0b09ab79f021379661"><title>getRURI()</title>
      <para>
	This function returns the recipient URI of the present SIP message:
      </para>
      <para>
	<literal role="code"><![CDATA[my $ruri =
	$m->getRURI();]]></literal>
      </para>
      <para>
	getRURI returns a string. See <link
	linkend="ID-f20c57aaa92a757d7152aa0479ee1fc0"><quote>getParsedRURI()</quote></link>
	below how to receive a parsed structure.
      </para>
      <para>
	This function is valid in request messages only.
      </para>
    </section>
    <section id="ID-09d760cb43aa35ee3338a63959e1ad52"><title>getMethod()</title>
      <para>
	Returns the current method, such as <literal
	role="code"><![CDATA[INVITE]]></literal>, <literal
	role="code"><![CDATA[REGISTER]]></literal>, <literal
	role="code"><![CDATA[ACK]]></literal> and so on.
      </para>
      <para>
	<literal role="code"><![CDATA[my $method =
	$m->getMethod();]]></literal>
      </para>
      <para>
	This function is valid in request messages only.
      </para>
    </section>
    <section id="ID-29a7bfa2b533d46b900690c15e89dac0"><title>getFullHeader()</title>
      <para>
	Returns the full message header as present in the current message.
	You might use this header to further work with it with your
	favorite MIME package.
      </para>
      <para>
	<literal role="code"><![CDATA[my $hdr =
	$m->getFullHeader();]]></literal>
      </para>
    </section>
    <section id="ID-d4227612556f15885224f8d7c9baa63d"><title>getBody()</title>
      <para>
	Returns the message body.
      </para>
    </section>
    <section id="ID-5c55b75dca8e197bf8d4e9195f3fc78b"><title>getMessage()</title>
      <para>
	Returns the whole message including headers and body.
      </para>
    </section>
    <section id="ID-2cd2368ec9da09ded819e54da7ed7e56"><title>getHeader(name)</title>
      <para>
	Returns the body of the first message header with this name.
      </para>
      <para>
	<literal role="code"><![CDATA[print
	$m->getHeader("To");]]></literal>
      </para>
      <para>
	<emphasis role="bold"><literal role="code"><![CDATA["John"
	<sip:[email protected]>]]></literal></emphasis>
      </para>
    </section>
    <section id="ID-e6f4b718fa39a84855f41d5048abfd17"><title>getHeaderNames()</title>
      <para>
	Returns an array of all header names. Duplicates possible!
      </para>
    </section>
    <section id="ID-7b0efd72c8ec89bc43dad940590b40c6"><title>moduleFunction(func,string1,string2)</title>
      <para>
	Search for an arbitrary function in module exports and call it with
	the parameters self, string1, string2.
      </para>
      <para>
	<literal role="code"><![CDATA[string1]]></literal> and/or <literal
	role="code"><![CDATA[string2]]></literal> may be omitted.
      </para>
      <para>
	As this function provides access to the functions that are exported
	to the Kamailio configuration file, it is autoloaded for unknown
	functions. Instead of writing
      </para>
      <screen><![CDATA[$m->moduleFunction("sl_send_reply", "500", "Internal Error");
$m->moduleFunction("xlog", "L_INFO", "foo");]]></screen>
      <para>
	you may as well write
      </para>
      <screen><![CDATA[$m->sl_send_reply("500", "Internal Error");
$m->xlog("L_INFO", "foo");]]></screen>
      <para>
	WARNING
      </para>
      <para>
	In Kamailio 1.2, only a limited subset of module functions is
	available. This restriction will be removed in a later version.
      </para>
      <para>
	Here is a list of functions that are expected to be working (not
	claiming completeness):
      </para>
      <screen><![CDATA[* 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
* t_load_contacts
* t_next_contacts
* 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]]></screen>
    </section>
    <section id="ID-9fb36151aa2a86585e66dc19227b7d92"><title>log(level,message) (deprecated type)</title>
      <para>
	Logs the message with Kamailio's logging facility. The logging level
	is one of the following:
      </para>
      <screen><![CDATA[* L_ALERT
* L_CRIT
* L_ERR
* L_WARN
* L_NOTICE
* L_INFO
* L_DBG]]></screen>
      <para>
	The logging function should be accessed via the Kamailio module
	variant. This one, located in Kamailio::Message, is deprecated.
      </para>
    </section>
    <section id="ID-b6b5403d6a2b667316e7ce7ddd0937d0"><title>rewrite_ruri(newruri)</title>
      <para>
	Sets a new destination (recipient) URI. Useful for rerouting the
	current message/call.
      </para>
      <screen><![CDATA[if ($m->getRURI() =~ m/\@somedomain.net/) {
  $m->rewrite_ruri("sip:dispatcher\@organization.net");
}]]></screen>
    </section>
    <section id="ID-43bdd45f2267be3165993d728ae6ac58"><title>setFlag(flag)</title>
      <para>
	Sets a message flag. The constants as known from the C API may be
	used, when Constants.pm is included.
      </para>
    </section>
    <section id="ID-d3f836fca6d5be320332751cb544a50b"><title>resetFlag(flag)</title>
      <para>
	Resets a message flag.
      </para>
    </section>
    <section id="ID-9df30424b7e93814c7928cf5899a12cc"><title>isFlagSet(flag)</title>
      <para>
	Returns whether a message flag is set or not.
      </para>
    </section>
    <section id="ID-cfb8c8675a6620394b21ab786379acfa"><title>pseudoVar(string)</title>
      <para>
	Returns a new string where all pseudo variables are substituted by
	their values. Can be used to receive the values of single
	variables, too.
      </para>
      <para>
	<emphasis role="bold">Please remember that you need to escape the
	'$' sign in perl strings!</emphasis>
      </para>
    </section>
    <section id="ID-098e67bc760ef445343eb9e8f93ece8b"><title>append_branch(branch,qval)</title>
      <para>
	Append a branch to current message.
      </para>
    </section>
    <section id="ID-f20c57aaa92a757d7152aa0479ee1fc0"><title>getParsedRURI()</title>
      <para>
	Returns the current destination URI as an Kamailio::URI object.
      </para>
    </section>
  </section>
  <section id="ID-ea7b3e8a4dc6ddf7af0e02f7cec8eef1"><title>Kamailio::URI</title>
    <para>
      This package provides functions for access to sip_uri structures.
    </para>
    <section id="ID-f0b0fe573c97823c7db7e6d2f763eecd"><title>user()</title>
      <para>
	Returns the user part of this URI.
      </para>
    </section>
    <section id="ID-13f823f4d5d264262256ce6c13ebda7f"><title>host()</title>
      <para>
	Returns the host part of this URI.
      </para>
    </section>
    <section id="ID-f16f4d3590aeadbb89be6381c63d31ba"><title>passwd()</title>
      <para>
	Returns the passwd part of this URI.
      </para>
    </section>
    <section id="ID-0e78ab3771467ade60bb813acff96e1f"><title>port()</title>
      <para>
	Returns the port part of this URI.
      </para>
    </section>
    <section id="ID-f09a07f5c225a4cdc0c8cf1b562feca5"><title>params()</title>
      <para>
	Returns the params part of this URI.
      </para>
    </section>
    <section id="ID-6ac4960ecbb77b9b208182e39c3fced6"><title>headers()</title>
      <para>
	Returns the headers part of this URI.
      </para>
    </section>
    <section id="ID-edbeee75601887c5522ec606864fcf06"><title>transport()</title>
      <para>
	Returns the transport part of this URI.
      </para>
    </section>
    <section id="ID-9b062529593a90fa98b8fdaf147d9625"><title>ttl()</title>
      <para>
	Returns the ttl part of this URI.
      </para>
    </section>
    <section id="ID-af281c7d5fa29dfa3d059c93e2ece82f"><title>user_param()</title>
      <para>
	Returns the user_param part of this URI.
      </para>
    </section>
    <section id="ID-cc3ad600892aefceee9bb7f7d083b9eb"><title>maddr()</title>
      <para>
	Returns the maddr part of this URI.
      </para>
    </section>
    <section id="ID-bcde93cc9055b03c23ac61f4f7aba922"><title>method()</title>
      <para>
	Returns the method part of this URI.
      </para>
    </section>
    <section id="ID-ffda2446aa820304039c53eaca5c1383"><title>lr()</title>
      <para>
	Returns the lr part of this URI.
      </para>
    </section>
    <section id="ID-e07722a580a9e670d428835b7efacfaf"><title>r2()</title>
      <para>
	Returns the r2 part of this URI.
      </para>
    </section>
    <section id="ID-20d6cdc41465025baceba8056215ac58"><title>transport_val()</title>
      <para>
	Returns the transport_val part of this URI.
      </para>
    </section>
    <section id="ID-6643223dbdb425407fe9801fd4d2fa5b"><title>ttl_val()</title>
      <para>
	Returns the ttl_val part of this URI.
      </para>
    </section>
    <section id="ID-aa87e27dd0cce4de62a0f32a7ecb7a33"><title>user_param_val()</title>
      <para>
	Returns the user_param_val part of this URI.
      </para>
    </section>
    <section id="ID-85b278e13c1c6169d612921b32a42c3a"><title>maddr_val()</title>
      <para>
	Returns the maddr_val part of this URI.
      </para>
    </section>
    <section id="ID-64d75002d2db35d7a66847e0c92f37a9"><title>method_val()</title>
      <para>
	Returns the method_val part of this URI.
      </para>
    </section>
    <section id="ID-cdb1f6d4201cd9b6ee19e6f58236a900"><title>lr_val()</title>
      <para>
	Returns the lr_val part of this URI.
      </para>
    </section>
    <section id="ID-af30e585b8decaf3e377375210e977b6"><title>r2_val()</title>
      <para>
	Returns the r2_val part of this URI.
      </para>
    </section>
  </section>
  <section id="ID-f092a1ce520e2e575c41702289adf85e"><title>Kamailio::AVP</title>
    <para>
      This package provides access functions for Kamailio's AVPs. These
      variables can be created, evaluated, modified and removed through
      this package.
    </para>
    <para>
      Please note that these functions do NOT support the notation used in
      the configuration file, but directly work on strings or numbers. See
      documentation of add method below.
    </para>
    <section id="ID-d4453222c49e08dc556c25a6586a00bc"><title>add(name,val)</title>
      <para>
	Add an AVP.
      </para>
      <para>
	Add an Kamailio 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
      </para>
      <screen><![CDATA[Kamailio::AVP::add("10", "10")]]></screen>
      <para>
	is something different than
      </para>
      <screen><![CDATA[Kamailio::AVP::add(10, 10)]]></screen>
      <para>
	due to this evaluation: The first will create _string_ AVPs with
	the name 10, while the latter will create a numerical AVP.
      </para>
      <para>
	You can modify/overwrite AVPs with this function.
      </para>
    </section>
    <section id="ID-ad3f402b1c78426a3a1de4d0c1d9ad6c"><title>get(name)</title>
      <para>
	get an Kamailio AVP:
      </para>
      <screen><![CDATA[my $numavp = Kamailio::AVP::get(5);
my $stravp = Kamailio::AVP::get("foo");]]></screen>
    </section>
    <section id="ID-15db533161502fc4591ec9acdd990ef4"><title>destroy(name)</title>
      <para>
	Destroy an AVP.
      </para>
      <screen><![CDATA[Kamailio::AVP::destroy(5);
Kamailio::AVP::destroy("foo");]]></screen>
    </section>
  </section>
  <section id="ID-b2dcbd51ac3a3e6208edd5e4f6a5ef63"><title>Kamailio::Utils::PhoneNumbers</title>
    <para>
      Kamailio::Utils::PhoneNumbers - Functions for canonical forms of phone
      numbers.
    </para>
    <screen><![CDATA[use Kamailio::Utils::PhoneNumbers;

my $phonenumbers = new Kamailio::Utils::PhoneNumbers(
     publicAccessPrefix => "0",
     internationalPrefix => "+",
     longDistancePrefix => "0",
     areaCode => "761",
     pbxCode => "456842",
     countryCode => "49"
   );

$canonical = $phonenumbers->canonicalForm("07612034567");
$number    = $phonenumbers->dialNumber("+497612034567");]]></screen>
    <para>
      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.
    </para>
    <para>
      The idea to canonicalize numbers were taken from hylafax.
    </para>
    <para>
      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.
    </para>
    <para>
      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 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 =&gt; +497614514829
    </para>
    <para>
      To get the dialing number from a canonical phone number, we substract
      all general prefixes until we have something
    </para>
    <para>
      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 <literal
      role="code"><![CDATA[new]]></literal> operator.
    </para>
    <para>
      The following fields should be set:
    </para>
    <screen><![CDATA['longDistancePrefix' 
'areaCode'
'pbxCode' 
'internationalPrefix'
'publicAccessPrefix'
'countryCode']]></screen>
    <para>
      This module exports the following functions when <literal
      role="code"><![CDATA[use]]></literal>ed:
    </para>
    <section id="ID-bd49dfdfc2284e87abd95fbce2d63cbd"><title>new(publicAccessPrefix,internationalPrefix,longDistancePrefix,countryCode,areaCode,pbxCode)</title>
      <para>
	The new operator returns an object of this type and sets its
	locational context according to the passed parameters. See
	<citerefentry>
	<refentrytitle>Kamailio::Utils::PhoneNumbers</refentrytitle>
	</citerefentry> above.
      </para>
    </section>
    <section id="ID-aa52786fee82fe6e26ac766b30a1a4fa"><title>canonicalForm( number [, context] )</title>
      <para>
	Convert a phone number (given as first argument) into its canonical
	form. When no context is passed in as the second argument, the
	default context from the systems configuration file is used.
      </para>
    </section>
    <section id="ID-31479dee3ae037c27cd7a84aa7358bd2"><title>dialNumber( number [, context] )</title>
      <para>
	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.
      </para>
    </section>
  </section>
  <section id="ID-05a2ba8f92ec3fe3d26bcb69d169a1b1"><title>Kamailio::LDAPUtils::LDAPConf</title>
    <para>
      Kamailio::LDAPUtils::LDAPConf - Read openldap config from standard
      config files.
    </para>
    <screen><![CDATA[use Kamailio::LDAPUtils::LDAPConf;
my $conf = new Kamailio::LDAPUtils::LDAPConf();]]></screen>
    <para>
      This module may be used to retrieve the global LDAP configuration as
      used by other LDAP software, such as <literal
      role="code"><![CDATA[nsswitch.ldap]]></literal> and <literal
      role="code"><![CDATA[pam-ldap]]></literal>. The configuration is
      usualy stored in <literal
      role="code"><![CDATA[/etc/openldap/ldap.conf]]></literal>
    </para>
    <para>
      When used from an account with sufficient privilegs (e.g. root), the
      ldap manager passwort is also retrieved.
    </para>
    <section id="ID-77bbb24cd07a34db564171c3072c9f8c"><title>Constructor new()</title>
      <para>
	Returns a new, initialized <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConf]]></literal>
	object.
      </para>
    </section>
    <section id="ID-09b3942c6aa316dd4659cc1d84cfab21"><title>Method base()</title>
      <para>
	Returns the servers base-dn to use when doing queries.
      </para>
    </section>
    <section id="ID-cabd9882c784cf96cf68ca988c1dae0f"><title>Method host()</title>
      <para>
	Returns the ldap host to contact.
      </para>
    </section>
    <section id="ID-467ec702bbcdb63e337bbff9e3a5bf01"><title>Method port()</title>
      <para>
	Returns the ldap servers port.
      </para>
    </section>
    <section id="ID-1a047746515766cf720b5cc0f154c783"><title>Method uri()</title>
      <para>
	Returns an uri to contact the ldap server. When there is no
	ldap_uri in the configuration file, an <literal
	role="code"><![CDATA[ldap:]]></literal> uri is constucted from host
	and port.
      </para>
    </section>
    <section id="ID-35ebbd3612d026b4176d2eb8eae428b0"><title>Method rootbindpw()</title>
      <para>
	Returns the ldap "root" password.
      </para>
      <para>
	Note that the <literal role="code"><![CDATA[rootbindpw]]></literal>
	is only available when the current account has sufficient privilegs
	to access <literal
	role="code"><![CDATA[/etc/openldap/ldap.secret]]></literal>.
      </para>
    </section>
    <section id="ID-5e0c4c1de34f9247439d8d10d6734b9e"><title>Method rootbinddn()</title>
      <para>
	Returns the DN to use for "root"-access to the ldap server.
      </para>
    </section>
    <section id="ID-cdb5e3ce4599d0613db43f1f387f7ea6"><title>Method binddn()</title>
      <para>
	Returns the DN to use for authentication to the ldap server. When
	no bind dn has been specified in the configuration file, returns
	the <literal role="code"><![CDATA[rootbinddn]]></literal>.
      </para>
    </section>
    <section id="ID-3c51d4eeaae6feb7498a2f562b176df3"><title>Method bindpw()</title>
      <para>
	Returns the password to use for authentication to the ldap server.
	When no bind password has been specified, returns the <literal
	role="code"><![CDATA[rootbindpw]]></literal> if any.
      </para>
    </section>
  </section>
  <section id="ID-10d643239760bcd4a2286051808d077e"><title>Kamailio::LDAPUtils::LDAPConnection</title>
    <para>
      Kamailio::LDAPUtils::LDAPConnection - Perl module to perform simple
      LDAP queries.
    </para>
    <para>
      OO-Style interface:
    </para>
    <screen><![CDATA[use Kamailio::LDAPUtils::LDAPConnection;
my $ldap = new Kamailio::LDAPUtils::LDAPConnection;
my @rows = $ldap-search("uid=andi","ou=people,ou=coreworks,ou=de");]]></screen>
    <para>
      Procedural interface:
    </para>
    <screen><![CDATA[use Kamailio::LDAPUtils::LDAPConnection;
my @rows = $ldap->search(
      new Kamailio::LDAPUtils::LDAPConfig(), "uid=andi","ou=people,ou=coreworks,ou=de");]]></screen>
    <para>
      This perl module offers a somewhat simplified interface to the
      <literal role="code"><![CDATA[Net::LDAP]]></literal> functionality.
      It is intended for cases where just a few attributes should be
      retrieved without the overhead of the full featured <literal
      role="code"><![CDATA[Net::LDAP]]></literal>.
    </para>
    <section id="ID-58e29437b48125a88033370afe8fa32b"><title>Constructor new( [config, [authenticated]] )</title>
      <para>
	Set up a new LDAP connection.
      </para>
      <para>
	The first argument, when given, should be a hash reference pointing
	to to the connection parameters, possibly an <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConfig]]></literal>
	object. This argument may be <literal
	role="code"><![CDATA[undef]]></literal> in which case a new
	(default) <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConfig]]></literal>
	object is used.
      </para>
      <para>
	When the optional second argument is a true value, the connection
	will be authenticated. Otherwise an anonymous bind is done.
      </para>
      <para>
	On success, a new <literal
	role="code"><![CDATA[LDAPConnection]]></literal> object is
	returned, otherwise the result is <literal
	role="code"><![CDATA[undef]]></literal>.
      </para>
    </section>
    <section id="ID-129bd2634f1c36a401321f2fa34be026"><title>Function/Method search( conf, filter, base, [requested_attributes ...])</title>
      <para>
	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.
      </para>
      <para>
	When the first argument (conf) is a <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConnection]]></literal>,
	it will be used to perform the queries. You can pass the first
	argument implicitly by using the "method" syntax.
      </para>
      <para>
	Otherwise the <literal role="code"><![CDATA[conf]]></literal>
	argument should be a reference to a hash containing the connection
	setup parameters as contained in a <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConf]]></literal>
	object. In this mode, the <literal
	role="code"><![CDATA[Kamailio::LDAPUtils::LDAPConnection]]></literal>
	from previous queries will be reused.
      </para>
      <section id="ID-fb371aca693935a2ea3467c59473c78f"><title>Arguments:</title>
        <para>
          <variablelist>
            <varlistentry>
				<term><anchor id="ID-08e27c41a71d449b64a8b443ae34bdb2"/>conf</term>
              <listitem>
                <para>
		  configuration object, used to find host,port,suffix and
		  use_ldap_checks
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
				<term><anchor id="ID-e6b91204102eda9679a64633dadda9cb"/>filter</term>
              <listitem>
                <para>
		  ldap search filter, eg '(mail=some@domain)'
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
				<term><anchor id="ID-1067b3f87b6da6a8f5e87238609c1802"/>base</term>
              <listitem>
                <para>
		  search base for this query. If undef use default suffix,
		  concat base with default suffix if the last char is a ','
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
				<term><anchor id="ID-1c7c9132da5e8bb2a9c24aec3df86e47"/>requested_attributes</term>
              <listitem>
                <para>
		  retrieve the given attributes instead of the dn from the
		  ldap directory.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>
      </section>
      <section id="ID-5c0875c73d1d44335ab71b50d8930584"><title>Result:</title>
        <para>
	  Without any specific <literal
	  role="code"><![CDATA[requested_attributes]]></literal>, return
	  the dn of all matching entries in the LDAP directory.
        </para>
        <para>
	  When some <literal
	  role="code"><![CDATA[requested_attributes]]></literal> are given,
	  return an array with those attibutes. When multiple entries match
	  the query, the attribute lists are concatenated.
        </para>
      </section>
    </section>
  </section>
  <section id="ID-94fdb1e4103544a567ac38ee23c8a4d1"><title>Kamailio::VDB</title>
    <para>
      This package is an (abstract) base class for all virtual databases.
      Derived packages can be configured to be used by Kamailio as a
      database.
    </para>
    <para>
      The base class itself should NOT be used in this context, as it does
      not provide any functionality.
    </para>
  </section>
  <section id="ID-d97df315e2044f430319fc4cd9937aa5"><title>Kamailio::Constants</title>
    <para>
      This package provides a number of constants taken from enums and
      defines of Kamailio header files. Unfortunately, there is no mechanism
      for updating the constants automatically, so check the values if you
      are in doubt.
    </para>
  </section>
  <section id="ID-9658bbad14831f685cca13a5c9bb4335"><title>Kamailio::VDB::Adapter::Speeddial</title>
    <para>
      This adapter can be used with the speeddial module.
    </para>
  </section>
  <section id="ID-5cdb14839de18c32782e3d768e170da7"><title>Kamailio::VDB::Adapter::Alias</title>
    <para>
      This package is intended for usage with the alias_db module. The
      query VTab has to take two arguments and return an array of two
      arguments (user name/domain).
    </para>
    <section id="ID-748da8d11c20576948ef68d62753a06a"><title>query(conds,retkeys,order)</title>
      <para>
	Queries the vtab with the given arguments for request conditions,
	keys to return and sort order column name.
      </para>
    </section>
  </section>
  <section id="ID-8165ac0b808b36ff72ee4032e0f62881"><title>Kamailio::VDB::Adapter::AccountingSIPtrace</title>
    <para>
      This package is an Adapter for the acc and siptrace modules,
      featuring only an insert operation.
    </para>
  </section>
  <section id="ID-048913e15394a9675cfe02af5c340528"><title>Kamailio::VDB::Adapter::Describe</title>
    <para>
      This package is intended for debug usage. It will print information
      about requested functions and operations of a client module.
    </para>
    <para>
      Use this module to request schema information when creating new
      adapters.
    </para>
  </section>
  <section id="ID-682dd320dd536e7fb0de4a24e9d1e46e"><title>Kamailio::VDB::Adapter::Auth</title>
    <para>
      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.
    </para>
  </section>
  <section id="ID-f245c032bf4b4837415c871537a63e3b"><title>Kamailio::VDB::ReqCond</title>
    <para>
      This package represents a request condition for database access,
      consisting of a column name, an operator (=, &lt;, &gt;, ...), a data
      type and a value.
    </para>
    <para>
      This package inherits from Kamailio::VDB::Pair and thus includes its
      methods.
    </para>
    <section id="ID-c50f7cee51ceffdb7253101a36d6b7b3"><title>new(key,op,type,name)</title>
      <para>
	Constructs a new Column object.
      </para>
    </section>
    <section id="ID-cb5f02a3144f3af620484048b11472af"><title>op()</title>
      <para>
	Returns or sets the current operator.
      </para>
    </section>
  </section>
  <section id="ID-4be9a5fa03b11c2c2dad3594fc3b585d"><title>Kamailio::VDB::Pair</title>
    <para>
      This package represents database key/value pairs, consisting of a
      key, a value type, and the value.
    </para>
    <para>
      This package inherits from Kamailio::VDB::Value and thus has the same
      methods.
    </para>
    <section id="ID-e6cc5b1a997ea8e29d2a00b986784dc0"><title>new(key,type,name)</title>
      <para>
	Constructs a new Column object.
      </para>
    </section>
    <section id="ID-9c70856322a870405521ad299a6785d6"><title>key()</title>
      <para>
	Returns or sets the current key.
      </para>
    </section>
  </section>
  <section id="ID-41cd8a9b5b94c05139d2a7f62d5a967b"><title>Kamailio::VDB::VTab</title>
    <para>
      This package handles virtual tables and is used by the Kamailio::VDB
      class to store information about valid tables. The package is not
      inteded for end user access.
    </para>
    <section id="ID-a42ddb87d67983028cf8d1b7d6f46baa"><title>new()</title>
      <screen><![CDATA[Constructs a new VTab object]]></screen>
    </section>
    <section id="ID-c00e2c0b9abc7cd56be59f2b051a538c"><title>call(op,[args])</title>
      <para>
	Invokes an operation on the table (insert, update, ...) with the
	given arguments.
      </para>
    </section>
  </section>
  <section id="ID-dd87abbf6c21bba656e60f50bf1db81b"><title>Kamailio::VDB::Value</title>
    <para>
      This package represents a database value. Additional to the data
      itself, information about its type is stored.
    </para>
    <section id="ID-f8210a055e2dc48b7cd31acfbe483ef9"><title>stringification</title>
      <para>
	When accessing a Kamailio::VDB::Value object as a string, it simply
	returns its data regardless of its type. =cut
      </para>
      <para>
	use strict;
      </para>
      <para>
	package Kamailio::VDB::Value;
      </para>
      <para>
	use overload '""' =&gt; \&amp;stringify;
      </para>
      <para>
	sub stringify { shift-&gt;{data} }
      </para>
      <para>
	use Kamailio; use Kamailio::Constants;
      </para>
      <para>
	our @ISA = qw ( Kamailio::Utils::Debug );
      </para>
    </section>
    <section id="ID-246aa300bb8cb062e3126e6eddd094c4"><title>new(type,data)</title>
      <para>
	Constructs a new Value object. Its data type and the data are
	passed as parameters.
      </para>
    </section>
    <section id="ID-1b24f490feaba7e8ffde5919a34a3ea5"><title>type()</title>
      <para>
	Returns or sets the current data type. Please consider using the
	constants from Kamailio::Constants
      </para>
    </section>
    <section id="ID-8ed1b290ce747e1e6fc97d5c253d67eb"><title>data()</title>
      <para>
	Returns or sets the current data.
      </para>
    </section>
  </section>
  <section id="ID-01b04d0ae14c862d7543534782702100"><title>Kamailio::VDB::Column</title>
    <para>
      This package represents database column definition, consisting of a
      column name and its data type.
    </para>
    <section id="ID-c1f63ab2d499e0ffb0eff65d3d1bcaa3"><title>Stringification</title>
      <para>
	When accessing a Kamailio::VDB::Column object as a string, it simply
	returns its column name regardless of its type. =cut
      </para>
      <para>
	package Kamailio::VDB::Column;
      </para>
      <para>
	use overload '""' =&gt; \&amp;stringify;
      </para>
      <para>
	sub stringify { shift-&gt;{name} }
      </para>
      <para>
	use Kamailio; use Kamailio::Constants;
      </para>
      <para>
	our @ISA = qw ( Kamailio::Utils::Debug );
      </para>
    </section>
    <section id="ID-9be0a542b4be1d36c09e57a0a7785b8b"><title>new(type,name)</title>
      <para>
	Constructs a new Column object. Its type and the name are passed as
	parameters.
      </para>
    </section>
    <section id="ID-9e27faa58b7b4659e2d511fd4ed58ccd"><title>type( )</title>
      <para>
	Returns or sets the current type. Please consider using the
	constants from Kamailio::Constants
      </para>
    </section>
    <section id="ID-e3219d620b6d1b4f5656ee466ef3cf22"><title>name()</title>
      <para>
	Returns or sets the current column name.
      </para>
    </section>
    <section id="ID-07e232dc068e186782a8d0c0bbae91d3"><title>Kamailio::VDB::Result</title>
      <para>
	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.
      </para>
    </section>
    <section id="ID-54e80aeec6aaaa66afb9548d25388dea"><title>new(coldefs,[row, row, ...])</title>
      <para>
	The constructor creates a new Result object. Its first parameter is
	a reference to an array of Kamailio::VDB::Column objects. Additional
	parameters may be passed to provide initial rows, which are
	references to arrays of scalars.
      </para>
    </section>
    <section id="ID-c77fe41ba24f3f04c12254c9f001bb27"><title>coldefs()</title>
      <screen><![CDATA[Returns or sets the column definition of the object.]]></screen>
    </section>
    <section id="ID-a20f0baefcdf46a3e923bb02203b3792"><title>rows()</title>
      <screen><![CDATA[Returns or sets the rows of the object.]]></screen>
    </section>
  </section>
</chapter>