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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b37727abaf0e731a05c516fd85b44e86f4bf5c75 Maintainer: Fan2Shrek Status: ready -->
<!-- Reviewed: yes -->
<chapter xml:id="ldap.controls" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Contrôle LDAP</title>
 <para>
   Les contrôles sont des objets spéciaux qui peuvent être envoyés
   avec une requête LDAP pour modifier le comportement du serveur LDAP
   lors de l'exécution de la requête. Il peut également y avoir des
   contrôles envoyés par le serveur avec la réponse pour fournir
   plus d'informations, généralement pour répondre à un objet de contrôle
   de la requête.
  <note>
   <para>
    Tous les contrôles ne sont pas supportés par tous les serveurs LDAP. Pour savoir
    quels contrôles sont supportés par un serveur, il faut interroger le DSE
    racine en lisant un dn vide avec le filtre (objectClass=*).
   </para>
   <example>
    <title>Testing support for paged result control</title>
    <programlisting role="php">
<![CDATA[
<?php
// $ds est un identifiant de lien valide pour un serveur de répertoire
$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
  die("This server does not support paged result control");
}
?>
]]>
    </programlisting>
   </example>
  </note>
 </para>

 <para>
   À partir de PHP 7.3, il est possible d'envoyer des contrôles avec la requête dans toutes
   les fonctions de requête en utilisant le paramètre <parameter>controls</parameter>. Lorsqu'une version
   étendue d'une fonction existe, il est recommandé de l'utiliser si on veut
   accéder à l'objet de réponse complet et être capable de parser
   les contrôles de réponse à partir de celui-ci en utilisant <function>ldap_parse_result</function>.
 </para>

 <para>
   <parameter>controls</parameter> doit être un tableau contenant un tableau pour chaque contrôle à envoyer,
   contenant les clés suivantes :
   <variablelist>
    <varlistentry>
     <term>
      oid
      (<type>string</type>)
     </term>
     <listitem>
      <simpara>
       L'OID du contrôle. Il est recommandé d'utiliser les constantes commençant par
       LDAP_CONTROL_ pour cela. Voir <link linkend="ldap.constants">constantes de LDAP</link>.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      iscritical
      (<type>bool</type>)
     </term>
     <listitem>
      <simpara>
       Si un contrôle est marqué comme critique, la requête échouera si le
       contrôle n'est pas supporté par le serveur, ou s'il échoue à être
       appliqué. À noter que certains contrôles devraient toujours être marqués
       comme critiques comme noté dans le RFC les introduisant. Par défaut à &false;.
      </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>
      value
      (<type>mixed</type>)
     </term>
     <listitem>
      <simpara>
       Si applicable, la valeur du contrôle. Consulter ci-dessous pour plus d'informations.
      </simpara>
     </listitem>
    </varlistentry>
   </variablelist>

 </para>

 <para>
   La plupart des valeurs de contrôle sont envoyées au serveur en BER-encodé.
   Il est possible de soit BER-encoder la valeur soi-même, ou il est possible de plutôt
   passer un tableau avec les clés correctes pour que l'encodage soit fait
   automatiquement.
   Les contrôles supportés pour le passage en tant que tableau sont :
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Les clés attendues sont [size] et [cookie]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_ASSERT</constant>
     La clé attendue est [assertion]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VALUESRETURNFILTER</constant>
     La clé attendue est filter
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     La clé attendue est attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     La clé attendue est attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTREQUEST</constant>
     Attend un tableau de tableaux avec les clés attr, [oid], [reverse].
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVREQUEST</constant>
     Les clés attendues sont before, after, attrvalue|(offset, count), [context]
    </para>
   </listitem>
  </itemizedlist>
 </para>

 <para>
   Les contrôles suivants n'ont pas besoin de valeur :
  <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>
   Le contrôle <constant>LDAP_CONTROL_PROXY_AUTHZ</constant> est un cas spécial
   car sa valeur n'est pas censée être BER-encodée, il est donc possible
   d'utiliser directement une chaîne pour sa valeur.
 </para>

 <para>
   Lorsque les contrôles sont parsés par <function>ldap_parse_result</function>, les valeurs sont
   transformées en tableau si supportées.
   Ceci est supporté pour :
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PASSWORDPOLICYRESPONSE</constant>
     Les clés sont expire, grace, [error]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Les clés sont size, cookie
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     Les clés sont dn et les noms d'attributs LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     Les clés sont dn et les noms d'attributs LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTRESPONSE</constant>
     Les clés sont errcode, [attribute]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVRESPONSE</constant>
     Les clés sont 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
-->