archived-doc-es/reference/ldap/controls.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b37727abaf0e731a05c516fd85b44e86f4bf5c75 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<chapter xml:id="ldap.controls" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Control LDAP</title>
 <para>
   Los controles son objetos especiales que pueden ser enviados
   con una petición LDAP para modificar el comportamiento del servidor LDAP
   durante la ejecución de la petición. También pueden existir
   controles enviados por el servidor con la respuesta para proporcionar
   más información, generalmente para responder a un objeto de control
   de la petición.
  <note>
   <para>
    No todos los controles son soportados por todos los servidores LDAP. Para saber
    qué controles son soportados por un servidor, debe interrogarse el DSE
    raíz leyendo un dn vacío con el filtro (objectClass=*).
   </para>
   <example>
    <title>Prueba de soporte para el control de resultados paginados</title>
    <programlisting role="php">
<![CDATA[
<?php
// $ds es un identificador de enlace válido para un servidor de directorio
$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
  die("Este servidor no soporta el control de resultados paginados");
}
?>
]]>
    </programlisting>
   </example>
  </note>
 </para>

 <para>
   Desde PHP 7.3, puede enviarse controles con la petición en todas
   las funciones de petición utilizando el parámetro <parameter>controls</parameter>. Cuando existe
   una versión extendida de una función, debe utilizarse si se desea
   acceder al objeto de respuesta completo y ser capaz de analizar
   los controles de respuesta a partir de este utilizando <function>ldap_parse_result</function>.
 </para>

 <para>
   <parameter>controls</parameter> debe ser un array que contenga un array para cada control a enviar,
   conteniendo las siguientes claves :
   <variablelist>
    <varlistentry>
     <term>
      oid
      (<type>string</type>)
     </term>
     <listitem>
      <simpara>
       El OID del control. Deben utilizarse las constantes que comienzan por
       LDAP_CONTROL_ para esto. Ver <link linkend="ldap.constants">constantes de LDAP</link>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      iscritical
      (<type>bool</type>)
     </term>
     <listitem>
      <simpara>
       Si un control está marcado como crítico, la petición fallará si el
       control no es soportado por el servidor, o si falla al ser
       aplicado. Tenga en cuenta que algunos controles deben siempre estar marcados
       como críticos como se indica en el RFC que los introduce. Por omisión a &false;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      value
      (<type>mixed</type>)
     </term>
     <listitem>
      <simpara>
       Si es aplicable, el valor del control. Lea a continuación para más información.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>

 </para>

 <para>
   La mayoría de los valores de control son enviados al servidor en BER-encodados.
   Puede BER-encodar el valor usted mismo, o puede pasar un array con las claves correctas
   para que el encodado sea realizado por usted.
   Los controles soportados para pasar como array son :
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Las claves esperadas son [size] y [cookie]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_ASSERT</constant>
     La clave esperada es [assertion]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VALUESRETURNFILTER</constant>
     La clave esperada es filter
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     La clave esperada es attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     La clave esperada es attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTREQUEST</constant>
     Espera un array de arrays con las claves attr, [oid], [reverse].
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVREQUEST</constant>
     Las claves esperadas son before, after, attrvalue|(offset, count), [context]
    </para>
   </listitem>
  </itemizedlist>
 </para>

 <para>
   Los siguientes controles no requieren valor :
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PASSWORDPOLICYREQUEST</constant>
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_MANAGEDSAIT</constant>
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_DONTUSECOPY</constant>
    </para>
   </listitem>
  </itemizedlist>
 </para>

 <para>
   El control <constant>LDAP_CONTROL_PROXY_AUTHZ</constant> es un caso especial
   ya que su valor no se espera que esté BER-encodado, por lo que puede
   utilizarse directamente una cadena para su valor.
 </para>

 <para>
   Cuando los controles son analizados por <function>ldap_parse_result</function>, los valores son
   transformados en array si son soportados.
   Esto es soportado para :
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PASSWORDPOLICYRESPONSE</constant>
     Las claves son expire, grace, [error]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Las claves son size, cookie
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     Las claves son dn y los nombres de atributos LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     Las claves son dn y los nombres de atributos LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTRESPONSE</constant>
     Las claves son errcode, [attribute]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVRESPONSE</constant>
     Las claves son target, count, errcode, context
    </para>
   </listitem>
  </itemizedlist>
 </para>
</chapter>

<!-- 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
-->