<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="fn_ldap_search">
  <refmeta>
    <refentrytitle>ldap_search</refentrytitle>
    <refmiscinfo>ldap</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>ldap_search</refname>
    <refpurpose>Search in an LDAP server.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis id="fsyn_ldap_search">
      <funcprototype id="fproto_ldap_search">
        <funcdef>any <function>ldap_search</function></funcdef>
	<paramdef>in <parameter>server_url </parameter>varchar</paramdef>
	<paramdef>in <parameter>try_tls </parameter>integer</paramdef>
	<paramdef>in <parameter>base </parameter>varchar</paramdef>
	<paramdef>in <parameter>filter </parameter>varchar</paramdef>
	<paramdef>in <parameter>username </parameter>varchar</paramdef>
	<paramdef>in <parameter>password </parameter>varchar</paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="desc_ldap_search"><title>Description</title><para>
This function performs a search in the LDAP server.  It returns control to
the Virtuoso/PL environment only after all of the search results have been sent by the server
or if the search request is timed out by the server.  The result of the search
(attributes, names of the attributes, etc.) will be returned as an array result.  Options
to the LDAP search can be passed as an array.
</para></refsect1>
  <refsect1 id="params_ldap_search"><title>Parameters</title>
    <refsect2><title>server_url</title>
      <para>The server URL has three parts, &lt;protocol&gt;://&lt;host&gt;:&lt;port&gt;.
Missing parameters will be defaulted to <programlisting>&lt;ldap://localhost:389&gt;</programlisting>.</para></refsect2>
    <refsect2><title>try_tls</title>
      <para><parameter>try_tls</parameter> is a flag that tells the client to perform a handshake
with the LDAP server using a secure connection.  This is only applicable to the ldap:// protocol and not
ldaps://.  If a secure connection cannot be made, the connection will be insecure.</para></refsect2>
    <refsect2><title>base</title>
      <para><parameter>base</parameter> is a string representing the DN base of the search.</para></refsect2>
    <refsect2><title>filter</title>
      <para>Filter is a string representation of the filter to apply in the 
	  search.  Simple filters can be specified as 
	  <computeroutput>attributetype=attributevalue</computeroutput>.  More 
	  complex filters are specified using a prefix  notation  according
       to the following BNF:</para>
<programlisting><![CDATA[
<filter> ::= '(' <filtercomp> ')'
  <filtercomp> ::= <and> | <or> | <not> | <simple>
  <and> ::= '&' <filterlist>
  <or> ::= '|' <filterlist>
  <not> ::= '!' <filter>
  <filterlist> ::= <filter> | <filter> <filterlist>
  <simple> ::= <attributetype> <filtertype> <attributevalue>
  <filtertype> ::= '=' | '~=' | '<=' | '>='
]]></programlisting>
</refsect2>
    <refsect2><title>username</title>
      <para>username authorization credential</para></refsect2>
    <refsect2><title>password</title>
      <para>password authorization credential</para></refsect2>
  </refsect1>
  <refsect1 id="ret_ldap_search"><title>Return Types</title><para>
This function returns an array consisting of the following elements:
</para>
<screen>
&lt;entry type&gt;, (&lt;attribute name&gt;, (&lt;value 1&gt;, &lt;value 2&gt; ...))
</screen>
<para>
The <parameter>entry type</parameter> can be the keyword 'entry' for search entry, 'reference' for search reference,
'extended' for extended result, or 'result' for result from search.  When
you specify 'result',
the returned array consists of 'error' and 'error message' keywords corresponding
to error codes and error descriptions.</para>
</refsect1>

  <refsect1 id="errors_ldap_search"><title>Errors</title>
    <table><title>Errors signalled by <function>ldap_search</function></title>
      <tgroup cols="4">
       <thead><row><entry>SQLState</entry><entry>Error Code</entry><entry>Error Text</entry><entry>Description</entry></row></thead>
	<tbody>
	  <row>
	    <entry><errorcode>2E000</errorcode></entry>
	    <entry><errorcode>LD020</errorcode></entry>
	    <entry><errorname>Failed to load the wldap32.dll</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>2E000</errorcode></entry>
	    <entry><errorcode>LD005</errorcode></entry>
	    <entry><errorname>Failed to initialize LDAP connection: &lt;reason&gt; (&lt;reason code&gt;)</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>2E000</errorcode></entry>
	    <entry><errorcode>LD006</errorcode></entry>
	    <entry><errorname>Failed to set LDAP version option: &lt;reason&gt; (&lt;reason code&gt;)</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>2E000</errorcode></entry>
	    <entry><errorcode>LD016</errorcode></entry>
	    <entry><errorname>Failed to start TLS: &lt;reason&gt; (&lt;reason code&gt;)</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>28000</errorcode></entry>
	    <entry><errorcode>LD007</errorcode></entry>
	    <entry><errorname>Failed to bind synchronous LDAP connection: &lt;reason&gt; (&lt;reason code&gt;)</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>42000</errorcode></entry>
	    <entry><errorcode>LD008</errorcode></entry>
	    <entry><errorname>Failed to search</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>39000</errorcode></entry>
	    <entry><errorcode>LD002</errorcode></entry>
	    <entry><errorname>Failed to parse LDAP reference response</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>39000</errorcode></entry>
	    <entry><errorcode>LD003</errorcode></entry>
	    <entry><errorname>Failed to parse LDAP extended result</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
	<tbody>
	  <row>
	    <entry><errorcode>39000</errorcode></entry>
	    <entry><errorcode>LD004</errorcode></entry>
	    <entry><errorname>Failed to parse LDAP extended partial result</errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1 id="examples_ldap_search"><title>Examples</title>
    <example id="ex_ldap_search">
<!--
<title>Using ldap_search</title>
-->
<programlisting>
....
declare result any;

-- without authentication
result := ldap_search ('ldap://localhost', 0, 'c=US', '(cn=SomeBody*)', NULL);

or

-- with authentication
result := ldap_search ('ldap://localhost', 0, 'c=US', '(cn=SomeBody*)',
  'cn=root,o=opl,c=US', 'secret');

-- the result may be following array:
-- ("entry"
     ("dn" "cn="John Atanasov",mail=hellraisor@hotmail.com,c=US,o=hotmail.com"
      "mail" ("hellraisor@hotmail.com" )
      "cn" ("John Atanasov" )
      "o" ("hotmail.com" )
      "l" ("SOFIA" )
      "givenName" ("John" )
      "surname" ("Atanasov" ))
     "result"
       ("error" "0" "error message" "Success" ))

...
</programlisting>
    </example>
  </refsect1>
  <refsect1 id="seealso_ldap_search"><title>See Also</title> <para><link
    linkend="fn_ldap_add"><function>ldap_add()</function></link>,<link
    linkend="fn_ldap_delete"><function>ldap_delete()</function></link>,<link
    linkend="fn_ldap_modify"><function>ldap_modify()</function></link></para>
  </refsect1>
</refentry>