betz Fri Jan 18 18:22:23 2002 EDT
Modified files:
/phpdoc/en/functions ldap.xml
Log:
addes some <param> tags in description, some &return.sucess; few <note>
Index: phpdoc/en/functions/ldap.xml
diff -u phpdoc/en/functions/ldap.xml:1.39 phpdoc/en/functions/ldap.xml:1.40
--- phpdoc/en/functions/ldap.xml:1.39 Mon Dec 17 15:20:36 2001
+++ phpdoc/en/functions/ldap.xml Fri Jan 18 18:22:23 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.39 $ -->
+<!-- $Revision: 1.40 $ -->
<reference id="ref.ldap">
<title>LDAP functions</title>
<titleabbrev>LDAP</titleabbrev>
@@ -220,14 +220,15 @@
</funcprototype>
</funcsynopsis>
<para>
- returns &true; on success and &false; on error.
+ &return.success;
</para><para>
The <function>ldap_add</function> function is used to add entries
in the LDAP directory. The DN of the entry to be added is
- specified by dn. Array entry specifies the information about the
- entry. The values in the entries are indexed by individual
- attributes. In case of multiple values for an attribute, they are
- indexed using integers starting with 0.
+ specified by <parameter>dn</parameter>.
+ Array <parameter>entry</parameter> specifies the information about the
+ entry. The values in the entries are indexed by individual attributes.
+ In case of multiple values for an attribute, they are indexed using
+ integers starting with 0.
</para>
<informalexample>
<literallayout>
@@ -285,11 +286,13 @@
</funcsynopsis>
<para>
Binds to the LDAP directory with specified RDN and
- password. Returns &true; on success and &false; on error.</para>
+ password. &return.success;</para>
<para>
<function>ldap_bind</function> does a bind operation on the
- directory. bind_rdn and bind_password are optional. If not
- specified, anonymous bind is attempted.</para>
+ directory. <parameter>bind_rdn</parameter> and
+ <parameter>bind_password</parameter> are optional. If not
+ specified, anonymous bind is attempted.
+ </para>
</refsect1>
</refentry>
@@ -308,7 +311,8 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns &true; on success, &false; on error.</para>
+ &return.success;
+ </para>
<para>
<function>ldap_close</function> closes the link to the LDAP
server that's associated with the specified
@@ -318,6 +322,11 @@
<function>ldap_unbind</function>. The LDAP API uses the call
<function>ldap_unbind</function>, so perhaps you should use this
in preference to <function>ldap_close</function>.</para>
+ <note>
+ <para>
+ This function is an alias of <function>ldap_unbind</function>.
+ </para>
+ </note>
</refsect1>
</refentry>
@@ -393,11 +402,11 @@
]]>
</programlisting>
</example>
- <note>
+ <warning>
<para>
<function>ldap_compare</function> can NOT be used to compare BINARY values!
</para>
- </note>
+ </warning>
<note>
<para>
This function was added in 4.0.2.
@@ -437,7 +446,12 @@
hostname. To use LDAP with SSL, compile OpenLDAP 2.x.x with SSL
support, configure PHP with SSL, and use ldaps://hostname/ as
host parameter. The port parameter is not used when using URLs.
- URL and SSL support were added in 4.0.4.</para>
+ </para>
+ <note>
+ <simpara>
+ URL and SSL support were added in 4.0.4.
+ </simpara>
+ </note>
</refsect1>
</refentry>
@@ -482,10 +496,11 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
<function>ldap_delete</function> function delete a particular
- entry in LDAP directory specified by dn.</para>
+ entry in LDAP directory specified by <parameter>dn</parameter>.
+ </para>
</refsect1>
</refentry>
@@ -504,8 +519,10 @@
</funcprototype>
</funcsynopsis>
<para>
- <function>ldap_dn2ufn</function> function is used to turn a DN
- into a more user-friendly form, stripping off type names.</para>
+ <function>ldap_dn2ufn</function> function is used to turn a DN,
+ specified by <parameter>dn</parameter>, into a more user-friendly form,
+ stripping off type names.
+ </para>
</refsect1>
</refentry>
@@ -526,12 +543,12 @@
</funcprototype>
</funcsynopsis>
<para>
- returns string error message.</para>
+ Returns string error message.</para>
<para>
This function returns the string error message explaining the
- error number errno. While LDAP errno numbers are standardized,
- different libraries return different or even localized textual
- error messages. Never check for a specific error message text,
+ error number <parameter>errno</parameter>. While LDAP errno numbers
+ are standardized, different libraries return different or even localized
+ textual error messages. Never check for a specific error message text,
but always use an error number to check.</para>
<para>
See also <function>ldap_errno</function> and
@@ -565,15 +582,16 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ldap_errno</function></funcdef>
- <paramdef>int <parameter>link_id</parameter></paramdef>
+ <paramdef>int <parameter>link_identifier</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
- return the LDAP error number of the last LDAP command for this
+ Return the LDAP error number of the last LDAP command for this
link.</para>
<para>
This function returns the standardized error number returned by
- the last LDAP command for the given link identifier. This number
+ the last LDAP command for the given
+ <parameter>link_identifier</parameter>. This number
can be converted into a textual error message using
<function>ldap_err2str</function>.</para>
<para>
@@ -604,7 +622,7 @@
</programlisting>
</example></para>
<para>
- see also <function>ldap_err2str</function> and
+ See also <function>ldap_err2str</function> and
<function>ldap_error</function>.</para>
</refsect1>
</refentry>
@@ -622,18 +640,18 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ldap_error</function></funcdef>
- <paramdef>int <parameter>link_id</parameter></paramdef>
+ <paramdef>int <parameter>link_identifier</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
- returns string error message.</para>
+ Returns string error message.</para>
<para>
This function returns the string error message explaining the
- error generated by the last LDAP command for the given link
- identifier. While LDAP errno numbers are standardized, different
- libraries return different or even localized textual error
- messages. Never check for a specific error message text, but
- always use an error number to check.</para>
+ error generated by the last LDAP command for the given
+ <parameter>link_identifier</parameter> While LDAP errno numbers
+ are standardized, different libraries return different or even
+ localized textual error messages. Never check for a specific error
+ message text, but always use an error number to check.</para>
<para>
Unless you lower your warning level in your
<filename>php.ini</filename> sufficiently or prefix your LDAP
@@ -641,7 +659,7 @@
warning output, the errors generated will also show up in your
HTML output.</para>
<para>
- see also <function>ldap_err2str</function> and
+ See also <function>ldap_err2str</function> and
<function>ldap_errno</function>.</para>
</refsect1>
</refentry>
@@ -663,9 +681,9 @@
</funcsynopsis>
<para>
<function>ldap_explode_dn</function> function is used to split
- the a DN returned by <function>ldap_get_dn</function> and breaks
+ the DN returned by <function>ldap_get_dn</function> and breaks
it up into its component parts. Each part is known as Relative
- Distinguished Name, or RDN. <function>ldap_explode_dn</function>
+ Distinguished Name, or RDN. <function>ldap_explode_dn</function>
returns an array of all those components.
<parameter>with_attrib</parameter> is used to request if the RDNs
are returned with only values or their attributes as well. To
@@ -699,7 +717,8 @@
Similar to reading entries, attributes are also read one by one
from a particular entry.
<function>ldap_first_attribute</function> returns the first
- attribute in the entry pointed by the entry identifier.
+ attribute in the entry pointed by the
+ <parameter>result_entry_identifier</parameter>.
Remaining attributes are retrieved by calling
<function>ldap_next_attribute</function> successively.
<parameter>ber_identifier</parameter> is the identifier to
@@ -709,7 +728,7 @@
that pointer.
</para>
<para>
- see also <function>ldap_get_attributes</function></para>
+ See also <function>ldap_get_attributes</function></para>
</refsect1>
</refentry>
@@ -741,7 +760,7 @@
<function>lap_next_entry</function> routine to get successive
entries from the result.</para>
<para>
- see also <function>ldap_get_entries</function>.</para>
+ See also <function>ldap_get_entries</function>.</para>
</refsect1>
</refentry>
@@ -760,7 +779,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
<function>ldap_free_result</function> frees up the memory
allocated internally to store the result and pointed by the
@@ -841,7 +860,7 @@
</example></para>
<para>
- see also <function>ldap_first_attribute</function> and
+ See also <function>ldap_first_attribute</function> and
<function>ldap_next_attribute</function></para>
</refsect1>
@@ -890,7 +909,8 @@
array on success and &false; on error.</para>
<para>
<function>ldap_get_entries</function> function is used to
- simplify reading multiple entries from the result and then
+ simplify reading multiple entries from the result, specified with
+ <parameter>result_identifier</parameter>, and then
reading the attributes and multiple values. The entire
information is returned by one function call in a
multi-dimensional array. The structure of the array is as
@@ -898,7 +918,7 @@
<para>
The attribute index is converted to lowercase. (Attributes are
case-insensitive for directory servers, but not when used as
- array indices)
+ array indices.)
<informalexample>
<literallayout>
@@ -911,13 +931,13 @@
return_value[i][j] = jth attribute in the ith entry in the result
return_value[i]["attribute"]["count"] = number of values for
- attribute in ith entry
+ attribute in ith entry
return_value[i]["attribute"][j] = jth value of attribute in ith entry
</literallayout>
</informalexample></para>
<para>
- see also <function>ldap_first_entry</function> and
+ See also <function>ldap_first_entry</function> and
<function>ldap_next_entry</function></para>
</refsect1>
</refentry>
@@ -939,8 +959,8 @@
</funcprototype>
</funcsynopsis>
<para>
- Sets <parameter>retval</parameter> to the value of the specified option,
- and returns &true; on success and &false; on error.</para>
+ Sets <parameter>retval</parameter> to the value of the specified option.
+ &return.success;</para>
<para>
The parameter <parameter>option</parameter> can be one of:
LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT,
@@ -949,9 +969,11 @@
LDAP_OPT_MATCHED_DN. These are described in
<ulink
url="&url.ldap.openldap-c-api;">draft-ietf-ldapext-ldap-c-api-xx.txt</ulink>
</para>
- <para>This function is only available when using OpenLDAP 2.x.x OR Netscape
Directory SDK x.x, and was
- added in PHP 4.0.4</para>
-
+ <note>
+ <para>This function is only available when using OpenLDAP 2.x.x OR
+ Netscape Directory SDK x.x, and was added in PHP 4.0.4
+ </para>
+ </note>
<para>
<example>
<title>Check protocol version</title>
@@ -1120,11 +1142,13 @@
Returns a search result identifier or &false; on error.</para>
<para>
<function>ldap_list</function> performs the search for a specified
- filter on the directory with the scope LDAP_SCOPE_ONELEVEL.</para>
+ <parameter>filter</parameter> on the directory with the scope
+ LDAP_SCOPE_ONELEVEL.</para>
<para>
LDAP_SCOPE_ONELEVEL means that the search should only return
- information that is at the level immediately below the base dn
- given in the call. (Equivalent to typing "ls" and getting a list
+ information that is at the level immediately below the
+ <parameter>base_dn</parameter> given in the call.
+ (Equivalent to typing "ls" and getting a list
of files and folders in the current working directory.)</para>
<para>
This call takes 5 optional parameters. See <function>ldap_search</function>
@@ -1158,10 +1182,12 @@
]]>
</programlisting>
</example></para>
- <para>
- From 4.0.5 on it's also possible to do parallel searches. See
- <function>ldap_search</function> for details.
- </para>
+ <note>
+ <para>
+ From 4.0.5 on it's also possible to do parallel searches. See
+ <function>ldap_search</function> for details.
+ </para>
+ </note>
</refsect1>
</refentry>
@@ -1182,7 +1208,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
<function>ldap_modify</function> function is used to modify the
existing entries in the LDAP directory. The structure of the
@@ -1207,12 +1233,13 @@
</funcprototype>
</funcsynopsis>
<para>
- returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
- This function adds attribute(s) to the specified dn. It
- performs the modification at the attribute level as opposed to the
- object level. Object-level additions are done by the
- <function>ldap_add</function> function.</para>
+ This function adds attribute(s) to the specified
+ <parameter>dn</parameter>. It performs the modification at the
+ attribute level as opposed to the object level. Object-level additions
+ are done by the <function>ldap_add</function> function.
+ </para>
</refsect1>
</refentry>
@@ -1232,12 +1259,13 @@
</funcprototype>
</funcsynopsis>
<para>
- returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
- This function removes attribute(s) from the specified dn. It
- performs the modification at the attribute level as opposed to the
- object level. Object-level deletions are done by the
- <function>ldap_del</function> function.</para>
+ This function removes attribute(s) from the specified
+ <parameter>dn</parameter>. It performs the modification at the
+ attribute level as opposed to the object level. Object-level
+ deletions are done by the <function>ldap_delete</function> function.
+ </para>
</refsect1>
</refentry>
@@ -1257,12 +1285,13 @@
</funcprototype>
</funcsynopsis>
<para>
- returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
- This function replaces attribute(s) from the specified dn. It
- performs the modification at the attribute level as opposed to the
- object level. Object-level modifications are done by the
- <function>ldap_modify</function> function.</para>
+ This function replaces attribute(s) from the specified
+ <parameter>dn</parameter>. It performs the modification at the attribute
+ level as opposed to the object level. Object-level modifications are done
+ by the <function>ldap_modify</function> function.
+ </para>
</refsect1>
</refentry>
@@ -1293,7 +1322,7 @@
<parameter>result_entry_identifier</parameter> returned from
<function>ldap_first_attribute</function>.</para>
<para>
- see also <function>ldap_get_attributes</function></para>
+ See also <function>ldap_get_attributes</function></para>
</refsect1>
</refentry>
@@ -1323,10 +1352,12 @@
<function>ldap_next_entry</function> return entries one by one
till there are no more entries. The first call to
<function>ldap_next_entry</function> is made after the call to
- <function>ldap_first_entry</function> with the result_identifier
- as returned from the <function>ldap_first_entry</function>.</para>
+ <function>ldap_first_entry</function> with the
+ <parameter>result_entry_identifier</parameter>
+ as returned from the <function>ldap_first_entry</function>.
+ </para>
<para>
- see also <function>ldap_get_entries</function></para>
+ See also <function>ldap_get_entries</function></para>
</refsect1>
</refentry>
@@ -1364,7 +1395,7 @@
Returns a search result identifier or &false; on error.</para>
<para>
<function>ldap_read</function> performs the search for a
- specified filter on the directory with the scope
+ specified <parameter>filter</parameter> on the directory with the scope
LDAP_SCOPE_BASE. So it is equivalent to reading an entry from the
directory.</para>
<para>
@@ -1386,10 +1417,11 @@
<parameter>deref</parameter>.
</para>
</note>
- <para>
- From 4.0.5 on it's also possible to do parallel searches. See
- <function>ldap_search</function> for details.
- </para>
+ <para>
+ From 4.0.5 on it's also possible to do parallel searches. See
+ <function>ldap_search</function> for details.
+ </para>
+
</refsect1>
</refentry>
@@ -1418,13 +1450,15 @@
by <parameter>newparent</parameter>. If the parameter
<parameter>deleteoldrdn</parameter> is &true; the old RDN value(s)
is removed, else the old RDN value(s) is retained as
- non-distinguished values of the entry. &true; is returned on
- success and &false; is returned on error.</para>
- <para>This function currently only works with LDAPv3. You may have
- to use <function>ldap_set_option()</function> prior to binding to
- use LDAPv3.</para>
- <para>This function is only available when using OpenLDAP 2.x.x OR
- Netscape Directory SDK x.x, and was added in PHP 4.0.5.</para>
+ non-distinguished values of the entry. &return.success;
+ </para>
+ <note>
+ <para>This function currently only works with LDAPv3. You may have
+ to use <function>ldap_set_option</function> prior to binding to
+ use LDAPv3. This function is only available when using OpenLDAP 2.x.x OR
+ Netscape Directory SDK x.x, and was added in PHP 4.0.5.
+ </para>
+ </note>
</refsect1>
</refentry>
@@ -1535,13 +1569,15 @@
</listitem>
</itemizedlist>
</para>
- <para>
+ <note>
+ <para>
These optional parameters were added in 4.0.2:
<parameter>attrsonly</parameter>,
<parameter>sizelimit</parameter>,
<parameter>timelimit</parameter>,
<parameter>deref</parameter>.
- </para>
+ </para>
+ </note>
<para>
The search filter can be simple or advanced, using boolean
operators in the format described in the LDAP doumentation (see
@@ -1611,7 +1647,7 @@
</funcsynopsis>
<para>
Sets the value of the specified option to be
- <parameter>newval</parameter>, and returns &true; on success and &false;
+ <parameter>newval</parameter>. &return.success;
on error.</para>
<para>
The parameter <parameter>option</parameter> can be one of:
@@ -1637,12 +1673,16 @@
elements are key <emphasis>value</emphasis> with string value
and key <emphasis>iscritical</emphasis> with boolean value.
<emphasis>iscritical</emphasis> defaults to <emphasis>&false;</emphasis>
- if not supplied. See also the second example below.</para>
- <para>
- This function is only available when using
- OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was
- added in PHP 4.0.4</para>
+ if not supplied. See also the second example below.
+ </para>
+ <note>
<para>
+ This function is only available when using
+ OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was
+ added in PHP 4.0.4.
+ </para>
+ </note>
+ <para>
<example>
<title>Set protocol version</title>
<programlisting role="php">
@@ -1691,7 +1731,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns &true; on success and &false; on error.</para>
+ &return.success;</para>
<para>
<function>ldap_unbind</function> function unbinds from the LDAP
directory.</para>
@@ -1914,8 +1954,6 @@
</para>
</refsect1>
</refentry>
-
-
</reference>
