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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: b37727abaf0e731a05c516fd85b44e86f4bf5c75 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->

<chapter xml:id="ldap.controls" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Управляющие объекты протокола LDAP</title>
 <para>
  Управляющие объекты — специальные объекты, которые, если нужно,
  передают вместе с LDAP-запросом, чтобы изменить поведение
  LDAP-сервера на время исполнения запроса. Вместе с ответом сервер
  может также отправлять управляющие объекты, обычно чтобы сообщить
  дополнительную информацию в ответ на управляющий объект из запроса.
  <note>
   <para>
    Не каждый LDAP-сервер поддерживает все управляющие объекты.
    Чтобы определить, какие управляющие объекты поддерживает сервер,
    запрашивают корневую запись DSE путём чтения пустого dn-имени
    с фильтром (objectClass=*).
   </para>
   <example>
    <title>Тестирование поддержки управления пагинацией результата</title>
    <programlisting role="php">
<![CDATA[
<?php

// $ds — допустимый идентификатор соединения с сервером каталогов

$result = ldap_read($ds, '', '(objectClass=*)', ['supportedControl']);
if (!in_array(LDAP_CONTROL_PAGEDRESULTS, ldap_get_entries($ds, $result)[0]['supportedcontrol'])) {
  die("Этот сервер не поддерживает управление пагинацией");
}

?>
]]>
    </programlisting>
   </example>
  </note>
 </para>

 <para>
  Начиная с PHP 7.3 управляющие объекты отправляют в запросе
  через параметр <parameter>controls</parameter> функций запроса. Разработчик должен работать
  с расширенной версией функции, если ext-вариант функции существует,
  если нужно получить доступ к полному объекту ответа
  и разбору функцией <function>ldap_parse_result</function>
  управляющих объектов из объекта ответа.
 </para>

 <para>
  Параметр <parameter>controls</parameter> должен содержать массив, который содержит массив
  со следующими ключами для каждого управляющего объекта, который будет отправлен:
  <variablelist>
   <varlistentry>
    <term>
     oid
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      OID-идентификатор управляющего объекта. Параметр принимает константы,
      имена которых начинаются на LDAP_CONTROL_.
      Смотрите раздел «<link linkend="ldap.constants">Константы LDAP</link>».
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     iscritical
     (<type>bool</type>)
    </term>
    <listitem>
     <simpara>
      Запрос завершится ошибкой, если управляющий объект
      пометили как критичный, а сервер не поддерживает такой
      управляющий объект, либо если объект невозможно применить.
      Обратите внимание, что отдельные объекты требуется помечать
      критичными в кажом запросе, как отмечает стандарт RFC, который представляет
      управляющий объект. Значение по умолчанию — &false;.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>
     value
     (<type>mixed</type>)
    </term>
    <listitem>
     <simpara>
      Значение управляющего объекта, если нужно. Подробнее о доступных значениях
      описание расскажет в абзаце, который идёт ниже.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>

 </para>

 <para>
  Бо́льшая часть значений управляющих объектов отсылается на сервер
  закодированными по правилам BER.
  Разработчики BER-кодируют значения сами или вместо этого передают
  массив с корректными ключами, и тогда значения закодирует PHP.
  Поддерживаемые управляющие объекты:
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Ожидаемые ключи [size] и [cookie]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_ASSERT</constant>
     Ожидаемый ключ — filter
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VALUESRETURNFILTER</constant>
     Ожидаемый ключ — filter
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     Ожидаемый ключ — attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     Ожидаемый ключ — attrs
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTREQUEST</constant>
     Ожидается массив массивов с ключами: attr, [oid], [reverse].
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVREQUEST</constant>
     Ожидаемые ключи: before, after, attrvalue|(offset, count), [context]
    </para>
   </listitem>
  </itemizedlist>
 </para>

 <para>
  Для следующих управляющих объектов значения не нужны:
  <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>
  Объект <constant>LDAP_CONTROL_PROXY_AUTHZ</constant> — уникальный случай,
  поскольку его значение не нужно кодировать по правилам BER,
  так что указывают обыкновенную строку.
 </para>

 <para>
  Функция <function>ldap_parse_result</function> преобразовывает
  значения в массив, если поддерживается, когда анализирует управляющие объекты.
  Это поддерживается для следующих элементов:
  <itemizedlist>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PASSWORDPOLICYRESPONSE</constant>
     Ключи: expire, grace, [error]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PAGEDRESULTS</constant>
     Ключи: size, cookie
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_PRE_READ</constant>
     Ключи: dn и имена атрибутов LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_POST_READ</constant>
     Ключи: dn и имена атрибутов LDAP
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_SORTRESPONSE</constant>
     Ключи: errcode, [attribute]
    </para>
   </listitem>
   <listitem>
    <para>
     <constant>LDAP_CONTROL_VLVRESPONSE</constant>
     Ключи: 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
-->