modules_k/perl/doc/perl_pod.xml
33d03d8d
 <?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;
 
 ]>
a6c8d0e4
 <!--
      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>OpenSER Perl API</title>
   <section id="ID-d83a4c83b0cd455aef9602128b87c323"><title>OpenSER</title>
     <para>
       This module provides access to a limited number of OpenSER core
       functions. As the most interesting functions deal with SIP messages,
       they are located in the OpenSER::Message class below.
     </para>
     <section id="ID-3ae476990b7b1fe73d972e68eb52f93c"><title>log(level,message)</title>
       <para>
 	Logs the message with OpenSER'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 OpenSER qw ( log );]]></literal>), or call
f856be73
 	it with its full name:
a6c8d0e4
       </para>
       <screen><![CDATA[OpenSER::log(L_INFO, "foobar");]]></screen>
     </section>
   </section>
   <section id="ID-949656abaac653354242d1d0e9b418be"><title>OpenSER::Message</title>
     <para>
       This package provides access functions for an OpenSER <literal
f856be73
       role="code"><![CDATA[sip_msg]]></literal> structure and its
       sub-components. Through its means it is possible to fully configure
a6c8d0e4
       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 OpenSER 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 OpenSER 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
0b126a3e
 * t_load_contacts
 * t_next_contacts
a6c8d0e4
 * uac_restore_from
 * uac_auth
 * has_totag
 * tel2sip
 * check_to
 * check_from
 * radius_does_uri_exist
 * ul_* (All functions exported by the usrloc module for user access)
 * xmpp_send_message]]></screen>
     </section>
     <section id="ID-9fb36151aa2a86585e66dc19227b7d92"><title>log(level,message) (deprecated type)</title>
       <para>
 	Logs the message with OpenSER'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 OpenSER module
 	variant. This one, located in OpenSER::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 OpenSER::URI object.
       </para>
     </section>
   </section>
   <section id="ID-ea7b3e8a4dc6ddf7af0e02f7cec8eef1"><title>OpenSER::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>
1b0f7ad6
   <section id="ID-f092a1ce520e2e575c41702289adf85e"><title>OpenSER::AVP</title>
     <para>
       This package provides access functions for OpenSER'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 OpenSER AVP to its environment. name and val may both be
 	integers or strings; this function will try to guess what is
 	correct. Please note that
       </para>
       <screen><![CDATA[OpenSER::AVP::add("10", "10")]]></screen>
       <para>
 	is something different than
       </para>
       <screen><![CDATA[OpenSER::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 OpenSER AVP:
       </para>
       <screen><![CDATA[my $numavp = OpenSER::AVP::get(5);
 my $stravp = OpenSER::AVP::get("foo");]]></screen>
     </section>
     <section id="ID-15db533161502fc4591ec9acdd990ef4"><title>destroy(name)</title>
       <para>
 	Destroy an AVP.
       </para>
       <screen><![CDATA[OpenSER::AVP::destroy(5);
 OpenSER::AVP::destroy("foo");]]></screen>
     </section>
   </section>
a6c8d0e4
   <section id="ID-b2dcbd51ac3a3e6208edd5e4f6a5ef63"><title>OpenSER::Utils::PhoneNumbers</title>
     <para>
       OpenSER::Utils::PhoneNumbers - Functions for canonical forms of phone
       numbers.
     </para>
d6b411ea
     <screen><![CDATA[use OpenSER::Utils::PhoneNumbers;
a6c8d0e4
 
d6b411ea
 my $phonenumbers = new OpenSER::Utils::PhoneNumbers(
a6c8d0e4
      publicAccessPrefix => "0",
      internationalPrefix => "+",
      longDistancePrefix => "0",
      areaCode => "761",
      pbxCode => "456842",
      countryCode => "49"
    );
 
d6b411ea
 $canonical = $phonenumbers->canonicalForm("07612034567");
 $number    = $phonenumbers->dialNumber("+497612034567");]]></screen>
a6c8d0e4
     <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>
9125d64c
 	The new operator returns an object of this type and sets its
a6c8d0e4
 	locational context according to the passed parameters. See
 	<citerefentry>
 	<refentrytitle>OpenSER::Utils::PhoneNumbers</refentrytitle>
 	</citerefentry> above.
       </para>
     </section>
     <section id="ID-aa52786fee82fe6e26ac766b30a1a4fa"><title>canonicalForm( number [, context] )</title>
       <para>
9125d64c
 	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.
a6c8d0e4
       </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>OpenSER::LDAPUtils::LDAPConf</title>
     <para>
       OpenSER::LDAPUtils::LDAPConf - Read openldap config from standard
       config files.
     </para>
     <screen><![CDATA[use OpenSER::LDAPUtils::LDAPConf;
 my $conf = new OpenSER::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[OpenSER::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>OpenSER::LDAPUtils::LDAPConnection</title>
     <para>
       OpenSER::LDAPUtils::LDAPConnection - Perl module to perform simple
       LDAP queries.
     </para>
     <para>
       OO-Style interface:
     </para>
     <screen><![CDATA[use OpenSER::LDAPUtils::LDAPConnection;
 my $ldap = new OpenSER::LDAPUtils::LDAPConnection;
 my @rows = $ldap-search("uid=andi","ou=people,ou=coreworks,ou=de");]]></screen>
     <para>
       Procedural interface:
     </para>
     <screen><![CDATA[use OpenSER::LDAPUtils::LDAPConnection;
 my @rows = $ldap->search(
       new OpenSER::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[OpenSER::LDAPUtils::LDAPConfig]]></literal>
 	object. This argument may be <literal
 	role="code"><![CDATA[undef]]></literal> in which case a new
 	(default) <literal
 	role="code"><![CDATA[OpenSER::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[OpenSER::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[OpenSER::LDAPUtils::LDAPConf]]></literal>
 	object. In this mode, the <literal
 	role="code"><![CDATA[OpenSER::LDAPUtils::LDAPConnection]]></literal>
 	from previous queries will be reused.
       </para>
       <section id="ID-fb371aca693935a2ea3467c59473c78f"><title>Arguments:</title>
         <para>
           <variablelist>
             <varlistentry>
8af86cb2
 				<term><anchor id="ID-08e27c41a71d449b64a8b443ae34bdb2"/>conf</term>
a6c8d0e4
               <listitem>
                 <para>
 		  configuration object, used to find host,port,suffix and
 		  use_ldap_checks
                 </para>
               </listitem>
             </varlistentry>
             <varlistentry>
8af86cb2
 				<term><anchor id="ID-e6b91204102eda9679a64633dadda9cb"/>filter</term>
a6c8d0e4
               <listitem>
                 <para>
 		  ldap search filter, eg '(mail=some@domain)'
                 </para>
               </listitem>
             </varlistentry>
             <varlistentry>
8af86cb2
 				<term><anchor id="ID-1067b3f87b6da6a8f5e87238609c1802"/>base</term>
a6c8d0e4
               <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>
8af86cb2
 				<term><anchor id="ID-1c7c9132da5e8bb2a9c24aec3df86e47"/>requested_attributes</term>
a6c8d0e4
               <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>
9125d64c
   <section id="ID-94fdb1e4103544a567ac38ee23c8a4d1"><title>OpenSER::VDB</title>
     <para>
       This package is an (abstract) base class for all virtual databases.
       Derived packages can be configured to be used by OpenSER 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>
a6c8d0e4
   <section id="ID-d97df315e2044f430319fc4cd9937aa5"><title>OpenSER::Constants</title>
     <para>
       This package provides a number of constants taken from enums and
       defines of OpenSER header files. Unfortunately, there is no mechanism
       for updating the constants automatically, so check the values if you
       are in doubt.
     </para>
   </section>
9125d64c
   <section id="ID-9658bbad14831f685cca13a5c9bb4335"><title>OpenSER::VDB::Adapter::Speeddial</title>
     <para>
       This adapter can be used with the speeddial module.
     </para>
   </section>
   <section id="ID-5cdb14839de18c32782e3d768e170da7"><title>OpenSER::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>OpenSER::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>OpenSER::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>OpenSER::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>OpenSER::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 OpenSER::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>OpenSER::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 OpenSER::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>OpenSER::VDB::VTab</title>
     <para>
       This package handles virtual tables and is used by the OpenSER::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>OpenSER::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 OpenSER::VDB::Value object as a string, it simply
 	returns its data regardless of its type. =cut
       </para>
       <para>
 	use strict;
       </para>
       <para>
 	package OpenSER::VDB::Value;
       </para>
       <para>
 	use overload '""' =&gt; \&amp;stringify;
       </para>
       <para>
 	sub stringify { shift-&gt;{data} }
       </para>
       <para>
 	use OpenSER; use OpenSER::Constants;
       </para>
       <para>
 	our @ISA = qw ( OpenSER::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 OpenSER::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>OpenSER::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 OpenSER::VDB::Column object as a string, it simply
 	returns its column name regardless of its type. =cut
       </para>
       <para>
 	package OpenSER::VDB::Column;
       </para>
       <para>
 	use overload '""' =&gt; \&amp;stringify;
       </para>
       <para>
 	sub stringify { shift-&gt;{name} }
       </para>
       <para>
 	use OpenSER; use OpenSER::Constants;
       </para>
       <para>
 	our @ISA = qw ( OpenSER::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 OpenSER::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>OpenSER::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 OpenSER::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>
a6c8d0e4
 </chapter>