<!--
     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
	it with its full name:
      </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
      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 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
* 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-bff5c83f8c28e72abf1d8a5204310202"><title>serialize_branches(clean_before)</title>
      <para>
	Serialize branches.
      </para>
    </section>
    <section id="ID-db3ce723c8e1880caf5fc0cb9ed7aa4d"><title>next_branches()</title>
      <para>
	Next branches.
      </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>
  <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>
  <section id="ID-b2dcbd51ac3a3e6208edd5e4f6a5ef63"><title>OpenSER::Utils::PhoneNumbers</title>
    <para>
      OpenSER::Utils::PhoneNumbers - Functions for canonical forms of phone
      numbers.
    </para>
    <screen><![CDATA[use OpenSER::Utils::PhoneNumber

my $phonenumber = new OpenSER::Utils::PhoneNumber(
     publicAccessPrefix => "0",
     internationalPrefix => "+",
     longDistancePrefix => "0",
     areaCode => "761",
     pbxCode => "456842",
     countryCode => "49"
   );

$canonical = canonicalForm("07612034567");
$number    = 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 it's
	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>
	Convert a phone number (given as first argument) into it's
	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>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>
              <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-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>
</chapter>
