You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
kamailio/modules/app_perl/doc/app_perl_pod.xml

1018 lines
35 KiB

<?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:john@doe.example>]]></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>