Request for review : ldap_control_paged_result & ldap_control_paged_result_response

Hi, Could you review the attached patch adding documention to the function ldap_control_paged_result & ldap_control_paged_result_response. Regards, NB : I'm not very familiar with doc process so correct me if I'm wrong. -- Jean-Sébastien H. au-fil-du.net

Index: en/reference/ldap/functions/ldap-control-paged-result-response.xml =================================================================== --- en/reference/ldap/functions/ldap-control-paged-result-response.xml (révision 324333) +++ en/reference/ldap/functions/ldap-control-paged-result-response.xml (copie de travail) @@ -1,11 +1,11 @@ <?xml version="1.0" encoding="utf-8"?> -<!-- $Revision$ --> +<!-- $Revision$ --> <refentry xml:id='function.ldap-control-paged-result-response' xmlns="http://docbook.org/ns/docbook"> <refnamediv> <refname>ldap_control_paged_result_response</refname> - <refpurpose>Extract paged results control response</refpurpose> + <refpurpose>Retrieve the pagination cookie.</refpurpose> </refnamediv> - + <refsect1 role="description"> &reftitle.description; <methodsynopsis> @@ -15,9 +15,64 @@ <methodparam choice="opt"><type>string</type><parameter role="reference">cookie</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter role="reference">estimated</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + <para>Retrieve the pagination information send by the server.</para> </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link</parameter></term> + <listitem> + <para> + An LDAP link identifier, returned by <function>ldap_connect</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>result</parameter></term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>cookie</parameter></term> + <listitem> + <para> + An opaque structure sent by the server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>estimated</parameter></term> + <listitem> + <para> + The estimated number of entries to retrieve. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns &true; or &false; on error. + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>ldap_control_paged_result</function></member> + <member><link>http://www.ietf.org/rfc/rfc2696.txt</link></member> + </simplelist> + </para> + </refsect1> </refentry> <!-- Keep this comment at the end of the file Index: en/reference/ldap/functions/ldap-control-paged-result.xml =================================================================== --- en/reference/ldap/functions/ldap-control-paged-result.xml (révision 324333) +++ en/reference/ldap/functions/ldap-control-paged-result.xml (copie de travail) @@ -1,22 +1,147 @@ <?xml version="1.0" encoding="utf-8"?> -<!-- $Revision$ --> +<!-- $Revision$ --> <refentry xml:id='function.ldap-control-paged-result' xmlns="http://docbook.org/ns/docbook"> <refnamediv> <refname>ldap_control_paged_result</refname> - <refpurpose>Inject paged results control</refpurpose> + <refpurpose>Send LDAP pagination control</refpurpose> </refnamediv> + <refsect1 role="description"> &reftitle.description; <methodsynopsis> - <type>mixed</type><methodname>ldap_control_paged_result</methodname> + <type>bool</type><methodname>ldap_control_paged_result</methodname> <methodparam><type>resource</type><parameter>link</parameter></methodparam> <methodparam><type>int</type><parameter>pagesize</parameter></methodparam> - <methodparam choice="opt"><type>bool</type><parameter role="reference">iscritical</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter role="reference">cookie</parameter></methodparam> + <methodparam choice="opt"><type>bool</type><parameter>iscritical</parameter></methodparam> + <methodparam choice="opt"><type>string</type><parameter>cookie</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + <para>Enable LDAP pagination by sending the pagination control (page size, cookie...).</para> </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link</parameter></term> + <listitem> + <para> + An LDAP link identifier, returned by <function>ldap_connect</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>pagesize</parameter></term> + <listitem> + <para> + The number of entries by page. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>iscritical</parameter></term> + <listitem> + <para> + Indicates whether the pagination is critical of not. + If true and if the server doesn't support pagination, the search + will return no result. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>cookie</parameter></term> + <listitem> + <para> + An opaque structure sent by the server (<function>ldap_control_paged_result_response</function>). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + +<refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns true or &false; on error. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + The example below show the retrieval of the first page of a search paginated with one entry by page. + <example> + <title>LDAP pagination</title> + <programlisting role="php"> +<![CDATA[ +<?php +// $ds is a valid link identifier for a directory server +// $person is all or part of a person's name, eg "Jo" + +$dn = "o=My Company, c=US"; +$filter="(|(sn=$person*)(givenname=$person*))"; +$justthese = array("ou", "sn", "givenname", "mail"); + +// enable pagination with a page size of 1. +ldap_control_paged_result($ds, 1); + +$sr=ldap_search($ds, $dn, $filter, $justthese); + +$info = ldap_get_entries($ds, $sr); + +echo $info["count"]." entries returned\n"; + +?> +]]> + </programlisting> + </example> + </para> <para> + The example below show the retrieval of all the result paginated with 100 entries by page. + <example> + <title>LDAP pagination</title> + <programlisting role="php"> +<![CDATA[ +<?php +// $ds is a valid link identifier for a directory server +// $person is all or part of a person's name, eg "Jo" + +$dn = "o=My Company, c=US"; +$filter="(|(sn=$person*)(givenname=$person*))"; +$justthese = array("ou", "sn", "givenname", "mail"); + +// enable pagination with a page size of 100. +$pageSize = 100; + +$cookie = ''; +do { + ldap_control_paged_result($ds, $pageSize, true, $cookie); + + $result = ldap_search($ds, $dn, $filter, $justthese); + $entries = ldap_get_entries($ds, $result); + + foreach ($entries as $e) { + print $e["dn"] . PHP_EOL; + } + + ldap_control_paged_result_response($ds, $result, $cookie); + +} while($cookie !== null && $cookie != ''); +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>ldap_control_paged_result_response</function></member> + <member><link>http://www.ietf.org/rfc/rfc2696.txt</link></member> + </simplelist> + </para> + </refsect1> </refentry> <!-- Keep this comment at the end of the file