mirror of https://github.com/sipwise/kamailio.git
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.
1018 lines
35 KiB
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 => +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 (=, <, >, ...), 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 '""' => \&stringify;
|
|
</para>
|
|
<para>
|
|
sub stringify { shift->{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 '""' => \&stringify;
|
|
</para>
|
|
<para>
|
|
sub stringify { shift->{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>
|