 |
 |
 |
 |
|
|
Date: 11/29/98
- Next message: drew <email protected>: "[PHP-DEV] Bug #959: Magic Quotes in Oracle (replaces bug 957)"
- Previous message: eschmid: "[PHP-DEV] CVS update: php3/doc/functions"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Date: Sunday November 29, 1998 @ 5:19
Author: eschmid
Update of /repository/php3/doc/functions
In directory asf:/u2/tmp/cvs-serv14793/functions
Modified Files:
ldap.sgml
Log Message:
More notes from the annotated manual.
Index: php3/doc/functions/ldap.sgml
diff -c php3/doc/functions/ldap.sgml:1.23 php3/doc/functions/ldap.sgml:1.24
*** php3/doc/functions/ldap.sgml:1.23 Sat Nov 28 16:14:14 1998
--- php3/doc/functions/ldap.sgml Sun Nov 29 05:19:08 1998
***************
*** 209,222 ****
<paramdef>array <parameter>entry</parameter></paramdef>
</funcsynopsis>
<para>
! returns true on success and false on error.
! </para><para>
! The ldap_add() 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.
</para>
<informalexample>
<literallayout>
--- 209,222 ----
<paramdef>array <parameter>entry</parameter></paramdef>
</funcsynopsis>
<para>
! returns true on success and false on error.
! </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.
</para>
<informalexample>
<literallayout>
***************
*** 269,280 ****
<paramdef>string <parameter>bind_password</parameter></paramdef>
</funcsynopsis>
<para>
! Binds to the LDAP directory with specified RDN and password. Returns
! true on success and false on error.
<para>
! ldap_bind() does a bind operation on the directory. bind_rdn and
! bind_password are optional. If not specified, anonymous bind is
! attempted.
</refsect1>
</refentry>
--- 269,280 ----
<paramdef>string <parameter>bind_password</parameter></paramdef>
</funcsynopsis>
<para>
! Binds to the LDAP directory with specified RDN and
! password. Returns true on success and false on error.
<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.
</refsect1>
</refentry>
***************
*** 318,331 ****
<paramdef>int <parameter>port</parameter></paramdef>
</funcsynopsis>
<para>
! Returns a positive LDAP link identifier on success, or false on error.
! <para>
! ldap_connect() establishes a connection to a LDAP server on a specified
! <parameter>hostname</parameter> and <parameter>port</parameter>.
! Both the arguments are optional. If no arguments are
! specified then the link identifier of the already opened link will be
! returned. If only <parameter>hostname</parameter> is specified, then the
! port defaults to 389.
</refsect1>
</refentry>
--- 318,333 ----
<paramdef>int <parameter>port</parameter></paramdef>
</funcsynopsis>
<para>
! Returns a positive LDAP link identifier on success, or false on
! error.
! <para>
! <function>ldap_connect</function> establishes a connection to a
! LDAP server on a specified <parameter>hostname</parameter> and
! <parameter>port</parameter>. Both the arguments are optional. If
! no arguments are specified then the link identifier of the
! already opened link will be returned. If only
! <parameter>hostname</parameter> is specified, then the port
! defaults to 389.
</refsect1>
</refentry>
***************
*** 343,353 ****
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns number of entries in the result or false on error.
<para>
! ldap_count_entries() returns the number of entries stored in the result
! of previous search operations. <parameter>result_identifier</parameter>
! identifies the internal ldap result.
</refsect1>
</refentry>
--- 345,356 ----
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns number of entries in the result or false on error.
<para>
! <function>ldap_count_entries</function> returns the number of
! entries stored in the result of previous search
! operations. <parameter>result_identifier</parameter> identifies
! the internal ldap result.
</refsect1>
</refentry>
***************
*** 365,374 ****
<paramdef>string <parameter>dn</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! ldap_delete() function delete a particular entry in LDAP directory
! specified by dn.
</refsect1>
</refentry>
--- 368,377 ----
<paramdef>string <parameter>dn</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! <function>ldap_delete</function> function delete a particular
! entry in LDAP directory specified by dn.
</refsect1>
</refentry>
***************
*** 385,392 ****
<paramdef>string <parameter>dn</parameter></paramdef>
</funcsynopsis>
<para>
! ldap_dn2ufn() function is used to turn a DN into a more user-friendly
! form, stripping off type names.
</refsect1>
</refentry>
--- 388,395 ----
<paramdef>string <parameter>dn</parameter></paramdef>
</funcsynopsis>
<para>
! <function>ldap_dn2ufn</function> function is used to turn a DN
! into a more user-friendly form, stripping off type names.
</refsect1>
</refentry>
***************
*** 404,418 ****
<paramdef>int <parameter>with_attrib</parameter></paramdef>
</funcsynopsis>
<para>
! ldap_explode_dn() function is used to split the a 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> 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 get RDNs with the attributes (i.e. in attribute=value format) set
! <parameter>with_attrib</parameter> to 1 and to get only values set it
! to 0.
</refsect1>
</refentry>
--- 407,422 ----
<paramdef>int <parameter>with_attrib</parameter></paramdef>
</funcsynopsis>
<para>
! <function>ldap_explode_dn</function> function is used to split
! the a 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>
! 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
! get RDNs with the attributes (i.e. in attribute=value format) set
! <parameter>with_attrib</parameter> to 1 and to get only values
! set it to 0.
</refsect1>
</refentry>
***************
*** 431,447 ****
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the first attribute in the entry on success and false on error.
<para>
! 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. Remaining
! attributes are retrieved by calling <function>ldap_next_attribute</function> successively.
! <parameter>ber_identifier</parameter> is the identifier to internal memory location pointer. It
! is passed by reference. The same <parameter>ber_identifier</parameter> is passed to the
! ldap_next_attribute() function, which modifies that pointer.
! <para>
! see also <function>ldap_get_attributes</function>
</refsect1>
</refentry>
--- 435,455 ----
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the first attribute in the entry on success and false on
! error.
<para>
! 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.
! Remaining attributes are retrieved by calling
! <function>ldap_next_attribute</function> successively.
! <parameter>ber_identifier</parameter> is the identifier to
! internal memory location pointer. It is passed by reference. The
! same <parameter>ber_identifier</parameter> is passed to the
! ldap_next_attribute() function, which modifies that pointer.
! <para>
! see also <function>ldap_get_attributes</function>
</refsect1>
</refentry>
***************
*** 459,474 ****
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the result entry identifier for the first entry on success and
! false on error.
<para>
! Entries in the LDAP result are read sequentially using the ldap_first_entry()
! and ldap_next_entry() functions. ldap_first_entry() returns the entry
! identifier for first entry in the result. This entry identifier is then
! supplied to <function>lap_next_entry</function> routine to get successive e
! ntries from the result.
! <para>
! see also <function>ldap_get_entries</function>.
</refsect1>
</refentry>
--- 467,485 ----
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the result entry identifier for the first entry on
! success and false on error.
<para>
! Entries in the LDAP result are read sequentially using the
! <function>ldap_first_entry</function> and
! <function>ldap_next_entry</function>
! functions. <function>ldap_first_entry</function> returns the
! entry identifier for first entry in the result. This entry
! identifier is then supplied to
! <function>lap_next_entry</function> routine to get successive
! entries from the result.
! <para>
! see also <function>ldap_get_entries</function>.
</refsect1>
</refentry>
***************
*** 485,500 ****
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
<para>
! ldap_free_result() frees up the memory allocated internally to store
! the result and pointed by the result_identifier. All result memory
! will be automatically freed when the script terminates.
! <para>
! Typically all the memory allocated for the ldap result gets freed at
! the end of the script. In case the script is making successive searches
! which return large result sets, ldap_free_result() could be called
! to keep the runtime memory usage by the script low.
</refsect1>
</refentry>
--- 496,513 ----
<paramdef>int <parameter>result_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
<para>
! <function>ldap_free_result</function> frees up the memory
! allocated internally to store the result and pointed by the
! <parameter>result_identifier</parameter>. All result memory will
! be automatically freed when the script terminates.
! <para>
! Typically all the memory allocated for the ldap result gets freed
! at the end of the script. In case the script is making successive
! searches which return large result sets,
! <function>ldap_free_result</function> could be called to keep the
! runtime memory usage by the script low.
</refsect1>
</refentry>
***************
*** 559,566 ****
</programlisting>
</example>
! see also <function>ldap_first_attribute</function> and
! <function>ldap_next_attribute</function>
</refsect1>
</refentry>
--- 572,580 ----
</programlisting>
</example>
! <para>
! see also <function>ldap_first_attribute</function> and
! <function>ldap_next_attribute</function>
</refsect1>
</refentry>
***************
*** 611,617 ****
follows.
<para>
The attribute index is converted to lowercase. (Attributes are
! case- insensitive for directory servers, but not when used as
array indices)
<informalexample>
--- 625,631 ----
follows.
<para>
The attribute index is converted to lowercase. (Attributes are
! case-insensitive for directory servers, but not when used as
array indices)
<informalexample>
***************
*** 630,637 ****
</literallayout>
</informalexample>
! see also <function>ldap_first_entry</function>
! and <function>ldap_next_entry</function>
</refsect1>
</refentry>
--- 644,652 ----
</literallayout>
</informalexample>
! <para>
! see also <function>ldap_first_entry</function> and
! <function>ldap_next_entry</function>
</refsect1>
</refentry>
***************
*** 660,665 ****
--- 675,693 ----
values can be found by indexing "count" in the resultant
array. Individual values are accessed by integer index in the
array. The first index is 0.
+ <para>
+ This call needs a <parameter>result_entry_identifier</parameter>,
+ so needs to be preceded by one of the ldap search calls and one
+ of the calls to get an individual entry.
+ <para>
+ You application will either be hard coded to look for certain
+ attributes (such as "surname" or "mail") or you will have to use
+ the <function>ldap_get_attributes</function> call to work out
+ what attributes exist for a given entry.
+ <para>
+ LDAP allows more than one entry for an attribute, so it can, for
+ example, store a number of email addresses for one person's
+ directory entry all labeled with the attribute "mail"
<informalexample>
<literallayout>
***************
*** 669,674 ****
--- 697,723 ----
</literallayout>
</informalexample>
+ <example>
+ <title>List all values of the "mail" attribute for a
+ directory entry </title>
+ <programlisting role=php>
+ // $ds is a valid link identifier for a directory server
+
+ // $sr is a valid search result from a prior call to
+ // one of the ldap directory search calls
+
+ // $entry is a valid entry identifier from a prior call to
+ // one of the calls that returns a directory entry
+
+ $values = ldap_get_values($ds, $entry,"mail");
+
+ echo $values["count"]." email addresses for this entry.<p>";
+
+ for ($i=0; $i < $values["count"]; $i++)
+ echo $values[$i]."<br>";
+ </programlisting>
+ </example>
+
</refsect1>
</refentry>
***************
*** 700,705 ****
--- 749,755 ----
This call takes an optional fourth parameter which is an array of
the attributes required. See <function>ldap_search</function>
notes.
+
<example>
<title>Produce a list of all organizational units of an organization
</title>
***************
*** 735,744 ****
<paramdef>array <parameter>entry</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! ldap_modify() function is used to modify the existing entries in the LDAP
! directory. The structure of the entry is same as in <function>ldap_add</function>.
</refsect1>
</refentry>
--- 785,795 ----
<paramdef>array <parameter>entry</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! <function>ldap_modify</function> function is used to modify the
! existing entries in the LDAP directory. The structure of the
! entry is same as in <function>ldap_add</function>.
</refsect1>
</refentry>
***************
*** 757,771 ****
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the next attribute in an entry on success and false on error.
<para>
! ldap_next_attribute() is called to retrieve the attributes in an entry.
! The internal state of the pointer is maintained by the <parameter>ber_identifier</parameter>.
! It is passed by reference to the function. The first call to
! ldap_next_attribute() is made with the <parameter>result_entry_identifier</parameter> returned
! from <function>ldap_first_attribute</function>.
! <para>
! see also <function>ldap_get_attributes</function>
</refsect1>
</refentry>
--- 808,825 ----
<paramdef>int <parameter>ber_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns the next attribute in an entry on success and false on
! error.
<para>
! <function>ldap_next_attribute</function> is called to retrieve
! the attributes in an entry. The internal state of the pointer is
! maintained by the <parameter>ber_identifier</parameter>. It is
! passed by reference to the function. The first call to
! <function>ldap_next_attribute</function> is made with the
! <parameter>result_entry_identifier</parameter> returned from
! <function>ldap_first_attribute</function>.
! <para>
! see also <function>ldap_get_attributes</function>
</refsect1>
</refentry>
***************
*** 782,799 ****
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns entry identifier for the next entry in the result whose entries
! are being read starting with ldap_first_entry(). If there are no more
! entries in the result then it returns false.
! <para>
! ldap_next_entry() function is used to retrieve the entries stored in
! the result. Successive calls to the ldap_next_entry() return entries one
! by one till there are no more entries. The first call to ldap_next_entry()
! is made after the call to <function>ldap_first_entry</function> with the
! result_identifier as returned from the ldap_first_entry().
! <para>
! see also <function>ldap_get_entries</function>
</refsect1>
</refentry>
--- 836,856 ----
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>int <parameter>result_entry_identifier</parameter></paramdef>
</funcsynopsis>
+ <para>
+ Returns entry identifier for the next entry in the result whose
+ entries are being read starting with
+ <function>ldap_first_entry</function>. If there are no more
+ entries in the result then it returns false.
+ <para>
+ <function>ldap_next_entry</function> function is used to retrieve
+ the entries stored in the result. Successive calls to the
+ <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>
! see also <function>ldap_get_entries</function>
</refsect1>
</refentry>
***************
*** 810,822 ****
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>string <parameter>base_dn</parameter></paramdef>
<paramdef>string <parameter>filter</parameter></paramdef>
</funcsynopsis>
<para>
! Returns a search result identifier or false on error.
<para>
! ldap_read() performs the search for a specified filter on the directory
! with the scope LDAP_SCOPE_BASE. So it is equivalent to reading an entry
! from the directory.
</refsect1>
</refentry>
--- 867,892 ----
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>string <parameter>base_dn</parameter></paramdef>
<paramdef>string <parameter>filter</parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>attributes</optional</parameter></paramdef>
</funcsynopsis>
<para>
! Returns a search result identifier or false on error.
<para>
! <function>ldap_read</function> performs the search for a
! specified filter on the directory with the scope
! LDAP_SCOPE_BASE. So it is equivalent to reading an entry from the
! directory.
! <para>
! An empty filter is not allowed. If you want to retrieve
! absolutely all information for this entry, use a filter of
! "objectClass=*". If you know which entry types are used on the
! directory server, you might use an appropriate filter such as
! "objectClass=inetOrgPerson".
! <para>
! This call takes an optional fourth parameter which is an array of
! the attributes required. See <function>ldap_search</function>
! notes.
</refsect1>
</refentry>
***************
*** 833,846 ****
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>string <parameter>base_dn</parameter></paramdef>
<paramdef>string <parameter>filter</parameter></paramdef>
</funcsynopsis>
<para>
! Returns a search result identifier or false on error.
<para>
! ldap_search() performs the search for a specified filter on the directory
! with the scope of LDAP_SCOPE_SUBTREE. This is equivalent to searching
! the entire directory. <parameter>base_dn</parameter> specifies the base DN
! for the directory.
</refsect1>
</refentry>
--- 903,990 ----
<paramdef>int <parameter>link_identifier</parameter></paramdef>
<paramdef>string <parameter>base_dn</parameter></paramdef>
<paramdef>string <parameter>filter</parameter></paramdef>
+ <paramdef>array
+ <parameter><optional>attributes</optional></parameter></paramdef>
</funcsynopsis>
<para>
! Returns a search result identifier or false on error.
<para>
! <function>ldap_search</function> performs the search for a
! specified filter on the directory with the scope of
! LDAP_SCOPE_SUBTREE. This is equivalent to searching the entire
! directory. <parameter>base_dn</parameter> specifies the base DN
! for the directory.
! <para>
! There is a optional fourth parameter, that can be added to
! restrict the attributes and values returned by the server to just
! those required. This is much more efficient than the default
! action (which is to return all attributes and their associated
! values). The use of the fourth parameter should therefore be
! considered good practice.
! <para>
! The fourth parameter is a standard PHP string array of the
! required attributes, eg array("mail","sn","cn") Note that the
! "dn" is always returned irrespective of which attributes types
! are requested.
! <para>
! Note too that some directory server hosts will be configured to
! return no more than a preset number of entries. If this occurs,
! the server will indicate that it has only returned a partial
! results set.
! <para>
! The search filter can be simple or advanced, using boolean
! operators in the format described in the LDAP doumentation (see
! the Netscape Directory SDK for full information on filters).
! <para>
! The example below retrieves the organizational unit, surname,
! given name and email address for all people in "My Company" where
! the surname or given name contains the substring $person. This
! example uses a boolean filter to tell the server to look for
! information in more than one attribute.
!
! <example>
! <title>LDAP search</title>
! <programlisting role=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");
!
! $sr=ldap_search($ds, $dn, $filter, $justthese);
!
! $info = ldap_get_entries($ds, $sr);
!
! print $info["count"]." entries returned<p>";
! </programlisting>
! </example>
!
! <para>
!
! When you perform a search, and too much data comes back (alot of
! entries) you will get a warning, and
! <function>ldap_get_entries</function> will fail. The trick here
! is to turn off the warnings, then check the return value.
!
! <informalexample>
! <literallayout>
! $normerr = error_reporting ();
! error_reporting (0); // turn off warnings!
! $sr = ldap_search ($ds, $dn, $searchfor);
! $normerr = error_reporting ($normerr);
! if (!$sr) {
! print "too many entries!";
! } else .....
! </literallayout>
! </informalexample>
!
! <para>
! You could try narrowing the scope, by adding an extra filter
! eg. (cn=a*), but It would be nicer to be able to grab the
! results in bits (eg. 1-100, 101-200...).
!
</refsect1>
</refentry>
***************
*** 857,865 ****
<paramdef>int <parameter>link_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! ldap_unbind() function unbinds from the LDAP directory.
</refsect1>
</refentry>
--- 1001,1010 ----
<paramdef>int <parameter>link_identifier</parameter></paramdef>
</funcsynopsis>
<para>
! Returns true on success and false on error.
! <para>
! <function>ldap_unbind</function> function unbinds from the LDAP
! directory.
</refsect1>
</refentry>
-- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe <email protected> For help: php-dev-help <email protected>
- Next message: drew <email protected>: "[PHP-DEV] Bug #959: Magic Quotes in Oracle (replaces bug 957)"
- Previous message: eschmid: "[PHP-DEV] CVS update: php3/doc/functions"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]