addes some <param> tags in description, some &return.sucess; few <note>

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@68069 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Friedhelm Betz 2002-01-18 23:22:23 +00:00
parent 1b259713dc
commit f5d2b9baa2

View file

@ -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 @@ if ($ds) {
</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 @@ if ($ds) {
</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 @@ if ($ds) {
</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 @@ if ($ds) {
<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 @@ if ($ds) {
]]>
</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 @@ if ($ds) {
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 @@ if ($ds) {
</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 @@ if ($ds) {
</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 @@ if ($ds) {
</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 @@ if ($ds) {
<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 @@ printf("%d matching entries.<br>\n", $info["count"]);
</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 @@ printf("%d matching entries.<br>\n", $info["count"]);
<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 @@ printf("%d matching entries.<br>\n", $info["count"]);
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 @@ printf("%d matching entries.<br>\n", $info["count"]);
</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 @@ printf("%d matching entries.<br>\n", $info["count"]);
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 @@ printf("%d matching entries.<br>\n", $info["count"]);
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 @@ printf("%d matching entries.<br>\n", $info["count"]);
<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 @@ printf("%d matching entries.<br>\n", $info["count"]);
</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 @@ for ($i=0; $i<$attrs["count"]; $i++)
</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 @@ for ($i=0; $i<$attrs["count"]; $i++)
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 @@ for ($i=0; $i<$attrs["count"]; $i++)
<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]["count"] = number of attributes in ith entry
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 @@ return_value[i]["attribute"][j] = jth value of attribute in ith entry
</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 @@ return_value[i]["attribute"][j] = jth value of attribute in ith entry
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 @@ for ($i=0; $i < $values["count"]; $i++)
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 @@ for ($i=0; $i<$info["count"]; $i++)
]]>
</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 @@ for ($i=0; $i<$info["count"]; $i++)
</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 @@ for ($i=0; $i<$info["count"]; $i++)
</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 @@ for ($i=0; $i<$info["count"]; $i++)
</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 @@ for ($i=0; $i<$info["count"]; $i++)
</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 @@ for ($i=0; $i<$info["count"]; $i++)
<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 @@ for ($i=0; $i<$info["count"]; $i++)
<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 @@ for ($i=0; $i<$info["count"]; $i++)
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 @@ for ($i=0; $i<$info["count"]; $i++)
<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 @@ for ($i=0; $i<$info["count"]; $i++)
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 @@ for ($i=0; $i<$info["count"]; $i++)
</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 @@ print $info["count"]." entries returned<p>";
</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 @@ print $info["count"]." entries returned<p>";
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 @@ if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2)))
</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>
@ -1915,8 +1955,6 @@ if (!ldap_set_option($ds, LDAP_OPT_SERVER_CONTROLS, array($ctrl1, $ctrl2)))
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file