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
