ldap-search.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: b7cbd468cb4c46d55d43a44cade0eb4590d25dea Maintainer: nobody Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: fbc6f9055f47d18f8ffb30513b772a32eda1526e Reviewer: samesch -->
<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>Sucht im LDAP-Baum</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>LDAP\Result</type><type>array</type><type>false</type></type><methodname>ldap_search</methodname>
   <methodparam><type class="union"><type>LDAP\Connection</type><type>array</type></type><parameter>ldap</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>base</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>filter</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>attributes</parameter><initializer>[]</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>attributes_only</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><constant>LDAP_DEREF_NEVER</constant></initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>controls</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Führt eine Suche für einen gegebenen Filter im Verzeichnis mit dem
   Geltungsbereichmit von <constant>LDAP_SCOPE_SUBTREE</constant> durch. Das
   ist äquivalent zu einer Suche im ganzen Verzeichnis.
  </para>
   &ldap.return-result-array-info;
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>ldap</parameter></term>
     <listitem>
      <para>
       &ldap.parameter.ldap;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>base</parameter></term>
     <listitem>
      <para>
       Der Basis-DN für das Verzeichnis.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>filter</parameter></term>
     <listitem>
      <para>
       Der Suchfilter kann einfach oder erweitert sein und boolesche
       Operatoren in dem Format verwenden, das in der LDAP-Dokumentation
       beschrieben wird (siehe das
       <link xlink:href="&url.ldap.filters;">Netscape Directory SDK</link>
       oder <link xlink:href="&url.rfc;4515">RFC4515</link> für vollständige
       Informationen zu Filtern).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>attributes</parameter></term>
     <listitem>
      <para>
       Ein Array von erforderlichen Merkmalen, &zb; <literal>array("mail",
       "sn", "cn")</literal>. Es ist zu beachten, dass der "dn" immer
       zurückgegeben wird, unabhängig davon, welche Merkmalstypen angefragt
       wurden.
      </para>
      <para>
       Die Verwendung dieses Parameters ist effizienter als die Standardaktion
       (die alle Merkmale und deren assoziierte Werte zurückgibt). Die
       Verwendung dieses Parameters sollte daher als gute Praxis eingestuft
       werden.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>attributes_only</parameter></term>
     <listitem>
      <para>
       Sollte auf 1 gesetzt werden, wenn nur Merkmalstypen erwünscht sind.
       Wird 0 übergeben, werden sowohl Merkmalstypen als auch Merkmalswerte
       abgerufen, was das Standardverhalten ist.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sizelimit</parameter></term>
     <listitem>
      <para>
       Ermöglicht die Begrenzung der Anzahl der abgerufenen Einträge. Wird
       hier 0 übergeben, besteht keine Begrenzung.
      </para>
      <note>
       <para>
        Dieser Parameter kann ein serverseitig voreingestelltes sizelimit
        NICHT überschreiben. Es kann allerdings kleiner gewählt werden.
       </para>
       <para>
        Verzeichnis-Server können so konfiguriert werden, dass sie nicht mehr
        als eine voreingestellte Anzahl von Einträgen zurückgeben. Wenn dies
        der Fall ist, dann zeigt der Server an, dass nur eine teilweise
        Ergebnismenge zurückgegeben wurde. Das geschieht ebenfalls, wenn
        dieser Parameter verwendet wird, um die Zahl der abgerufenen Einträge
        zu begrenzen.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>timelimit</parameter></term>
     <listitem>
      <para>
       Setzt die Anzahl von Sekunden, die auf die Suche verwendet wird. Die
       Übergabe von 0 bedeutet keine Begrenzung.
      </para>
      <note>
       <para>
        Dieser Parameter kann ein serverseitig voreingestelltes timelimit
        NICHT überschreiben. Es kann allerdings kleiner gewählt werden.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>deref</parameter></term>
     <listitem>
      <para>
       Gibt an, wie Aliase während der Suche behandelt werden sollen. Es kann
       einen der folgenden Werte annehmen:
       <itemizedlist>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_NEVER</constant> - (standard) Aliase werden nie
          dereferenziert.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_SEARCHING</constant> - Aliase sollen während
          der Suche dereferenziert werden, aber nicht wenn das Basis-Objekt
          der Suche lokalisiert wird.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_FINDING</constant> - Aliase sollen für die
          Lokalisierung des Basis-Objekts dereferenziert werden, aber nicht
          während der Suche.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          <constant>LDAP_DEREF_ALWAYS</constant> - Aliase sollen immer
          dereferenziert werden.
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>controls</parameter></term>
     <listitem>
      <para>
       Ein Array von <link linkend="ldap.controls">LDAP-Steuerbefehlen</link>,
       die mit der Anfrage versendet werden sollen.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &ldap.return-result-array;
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      &ldap.changelog.ldap-object;
      &ldap.changelog.return-result-object;
      &ldap.changelog.controls-nullable;
      <row>
       <entry>7.3.0</entry>
       <entry>
        Die Unterstützung für <parameter>controls</parameter> wurde
        hinzugefügt.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Das untenstehende Beispiel liefert die Organisationseinheit, den
   Familiennamen, den Vornamen und die E-Mail-Adresse aller Personen in "Meine
   Firma", deren Familien- oder Vorname die Zeichenkette
   <varname>$person</varname> enhält. In diesem Beispiel wird ein boolescher
   Filter verwendet, um den Server zu veranlassen, nach Informationen in mehr
   als einem Merkmal zu suchen.
   <example>
    <title>LDAP-Suche</title>
    <programlisting role="php">
<![CDATA[
<?php
// $ds ist eine gültige LDAP\Connection-Instanz für einen Verzeichnis-Server

// $person ist ein Teil des Namens oder der vollständige Name einer Person,
// z. B. "Jo"

$dn = "o=Meine Firma, c=DE";
$filter = "(|(sn=$person*)(vorname=$person*))";
$justthese = array("ou", "sn", "vorname", "mail");

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

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

echo $info["count"] . " Einträge gefundene\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
-->