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

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

<chapter xml:id="ldap.controls" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>LDAP コントロール</title>
 <para>
   コントロールは、リクエストを処理中にサーバーの振る舞いを変更するために
   LDAP リクエストと一緒に送られる特別なオブジェクトです。
   サーバーがレスポンスと一緒に送ってくる、
   追加の情報を提供するためのコントロールも存在します。
   これは通常、リクエストに付けて送られたコントロールオブジェクトへの返答になります。
  <note>
   <para>
    全てのコントロールが、全てのLDAPサーバーによってサポートされているとは限りません。
    どのコントロールをサーバーがサポートしているのかを知るには、
    フィルタ (objectClass=*) を付けて空の dn を読むことで、
    root DSE に問い合わせる必要があります。
   </para>
   <example>
    <title>ページ分けされた結果コントロールがサポートされているかをテストする</title>
    <programlisting role="php">
<![CDATA[
<?php

// $ds is a valid link identifier for a directory server

$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>
   PHP 7.3 以降では、全てのリクエスト関数で <parameter>controls</parameter> パラメータを使って
   コントロールを送信することができます。関数の拡張バージョンが存在する場合、
   完全なレスポンスオブジェクトを取得したい場合は、それを使うべきです。
   そうすれば、<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エンコードするか、
   配列に正しいキーを渡すことでBERエンコードを行わせることができます。
   配列で渡すことをサポートしているコントロールは以下のとおりです:
  <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
-->