ldap-search.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: bd8f8383a35547d9b19cbe75c05240e6a1ce6142 Maintainer: edwincartagenah Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.ldap-search" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>ldap_search</refname>
  <refpurpose>Buscar el árbol LDAP</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>ldap_search</methodname>
   <methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
   <methodparam><type>string</type><parameter>base_dn</parameter></methodparam>
   <methodparam><type>string</type><parameter>filter</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>attributes</parameter><initializer>array("*")</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>attrsonly</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>sizelimit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>timelimit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>deref</parameter><initializer>LDAP_DEREF_NEVER</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>serverctrls</parameter><initializer>array()</initializer></methodparam>
  </methodsynopsis>
  <para>
   Realiza la búsqueda de un filtro específico sobre el directorio con el alcance
   de <constant>LDAP_SCOPE_SUBTREE</constant>. Esto es equivalente a buscar en
   el directorio completo.
  </para>
  <para>
   Desde la versión 4.0.5 en adelante, también es posible hacer búsquedas paralelas. Para hacer esto
   se utiliza un array de identificadores de enlace, en lugar de un simple identificador,
   como el primer argumento. Si no quieres el mismo DN y el mismo
   filtro para todas las búsquedas, puedes utilizar también un array de DNs
   base y/o un array de filtros. Esos arrays deben ser del mismo tamaño como
   el de el array del identificador de enlace ya que, las primeras entradas de los arrays
   son utilizadas por una búsqueda, las segundas entradas son utilizadas para otra, y
   así. Cuando se hacen búsquedas en paralelo se devuelve un array de identificadores del
   resultado de la búsqueda, exceptuando en caso de error, la entrada que corresponde
   a la búsqueda será &false;. Esto es muy parecido a los valores
   que normalmente se devuelven, excepto que un identificador de resultado siempre es
   devuelto cuando se hace una búsqueda. Hay algunos casos raros donde el resultado
   normal de la búsqueda devuelve &false; mientras que la búsqueda paralela devuelve un
   identificador.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>link_identifier</parameter></term>
     <listitem>
      <para>
       Un identificador de enlace de LDAP, devuelto por <function>ldap_connect</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>base_dn</parameter></term>
     <listitem>
      <para>
       El DN base para el directorio.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>filter</parameter></term>
     <listitem>
      <para>
       El filtro de búsqueda puede ser simple o avanzado, utilizando operadores booleanos en
       el formato descrito en la documentación de LDAP (ver el <link
       xlink:href="&url.ldap.filters;">Directorio del SDK Netscape</link> o el
       <link xlink:href="&url.rfc;4515">RFC4515</link> para la
       información completa sobre filtros).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>attributes</parameter></term>
     <listitem>
      <para>
       Un array de los atributos requeridos, por ejemplo, <literal>array("mail", "sn", "cn")</literal>.
       Nótese que el "dn" siempre es devuelto independientemente de qué tipos de atributos
       sean requeridos.
      </para>
      <para>
       Utilizando este parámetro es mucho más eficiente que la acción predeterminada
       (la cual es devolver todos los atributos y sus valores asociados). 
       El uso de este parámetro debería ser considerado una buena
       práctica.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>attrsonly</parameter></term>
     <listitem>
      <para>
       Debería ser establecido a 1 si sólo se buscan tipos de atributos. Si se establece a 0
       los valores de atributos y los tipos de atributos se muestran tal cual es el
       comportamiento predeterminado.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sizelimit</parameter></term>
     <listitem>
      <para>
       Te permite limitar la cantidad de entradas a mostrar. Al establecer esto a 0
       siginifica que no hay límite.
      </para>
      <note>
       <para>
        Este parámetro NO puede prevalecer sobre el sizelimit preestablecido en el lado del servidor. Puede aún
        establecerlo a uno más bajo.
       </para>
       <para>
        Algunos equipos de servidor de directorio serán configurados para devolver no mas que
        un número preestablecido de entradas. Si esto ocurre, el servidor indicará
        que sólo ha devuelto un conjunto de resultados parciales. Esto también ocurre si
        utiliza este parámetro para limitar el conteo de entradas devueltas.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>timelimit</parameter></term>
     <listitem>
      <para>
       Establece el número de segundos de cuánto tiempo pasa en la búsqueda. Poniendo
       esto a 0 siginifica que no hay límite.
      </para>
      <note>
       <para>
        Este parámetro NO puede prevalecer sobre el timelimit preestablecido en el lado del servidor. Puede aún
        establecerlo a uno más bajo.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>deref</parameter></term>
     <listitem>
      <para>
       Especifica cuántos alias deberían ser manejados durante la búsqueda. Este puede ser
       uno de los siguientes:
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_NEVER</constant> - (predeterminado) Los alias nunca son
          dereferenciados.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_SEARCHING</constant> - Los alias deberían ser
          dereferenciados durante la búsqueda pero no cuando se está ubicando el objeto base
          de la búsqueda.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_FINDING</constant> - Los alias deberían ser
          dereferenciados cuando se está ubicando el objeto base pero no durante la búsqueda.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_ALWAYS</constant> - Los alias siempre deberían ser dereferenciados.
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>serverctrls</parameter></term>
     <listitem>
      <para>
       Array de <link linkend="ldap.controls">Controles de LDAP</link> a enviar con la petición.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un identificador de resultado de búsqueda, o &false; en caso de error.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.3</entry>
       <entry>
        Se añadión soporte para <parameter>serverctrls</parameter>
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   En el ejemplo de abajo se devuelve la unidad organizacional, apellido,
   el nombre proporcionado y la dirección de correo electrónico para todas las personas en "My Company" donde
   el apellido o el nombre proporcionado contiene la subcadena <varname>$person</varname>. Este
   ejemplo utiliza un filtro booleano para decirle al servidor que busque
   información en más de un atributo.
   <example>
    <title>Búsqueda LDAP</title>
    <programlisting role="php">
<![CDATA[
<?php
/ $ds es un identificador de enlace válido para un servidor de directorio

/ $person es todo o parte del nobre de una persona, por ejemplo "Jo"

$dn = "o=My Company, c=US";
$filter="(|(sn=$person*)(givenname=$person*))";
$justthese = array("ou", "sn", "givenname", "mail");

$sr=ldap_search($ds, $dn, $filter, $justthese);

$info = ldap_get_entries($ds, $sr);

echo $info["count"]." entradas devueltas\n";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->