Search Functions (Cont.) - Page 12

int ldap_first_entry(int link_identifier, int result_identifier)

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 lap_next_entry() to get successive entries from the result. It returns the result entry identifier for the first entry on success or false on error.

ldap_free_result()

boolean ldap_free_result(int result_identifier)

ldap_free_result() frees up the memory allocated internally to store the result of a previous search operation and pointed to by the result_identifier. Typically, all the memory allocated for the search result gets freed at the end of the script. In case the script is making successive searches that return large resultsets, ldap_free_result() could be called to keep the runtime memory usage by the script low. It returns true on success and false on error.

ldap_get_attributes()

array ldap_get_attributes(int link_identifier,
 int result_entry_identifier)

ldap_get_attributes() is used to simplify reading the attributes and values from an entry in the search result. The return value is a multi-dimensional array of attributes and values. Having located a specific entry in the directory, we can find out what information is held for that entry by using this call. We would use this call for an application that browses directory entries and/or where you do not know the structure of the directory entries. In many applications you will be searching for a specific attribute such as an e-mail address or a surname, and won't care what other data is held. It returns a complete entry information in a multi-dimensional array on success, and false on error.

ldap_get_dn()

string ldap_get_dn(int link_identifier, int result_entry_identifier)

ldap_get_dn() is used to find out the DN of an entry in the result. It returns false on error.

ldap_get_entries()

array ldap_get_entries(int link_identifier, int result_identifier)

ldap_get_entries() is used to simplify reading multiple entries from the result and then reading the attributes and multiple values. The entire information is returned by one function call in a multi-dimensional array. The attribute index is converted to lowercase (attributes are case-insensitive for directory servers, but not when used as array indices). It returns the complete result information in a multi-dimensional array on success, and false on error.

ldap_get_values()

array ldap_get_values(int link_identifier,
                      int result_entry_identifier, string attribute)

ldap_get_values() is used to read all the values of the attribute in the entry from the result. The entry is specified by the result_entry_identifier. The number of values in the entry is stored in an index called count in the resultant array. Individual values are accessed by an integer index in the array. The first index is 0.

This call needs a result_entry_identifier, so needs to be preceded by one of the LDAP search calls and one of the calls to get an individual entry. Your application will either be hard coded to look for certain attributes (such as surname or mail) or you will have to use the ldap_get_attributes function to work out what attributes exist for a given entry. LDAP allows more than one entry for an attribute, so it can, for example, store a number of e-mail addresses for one person's directory entry all labeled with the attribute mail.

ldap_list()

int ldap_list(int link_identifier, string base_dn, string filter
              [, array attributes [, int attrsonly [, int sizelimit
              [, int timelimit [, int deref]]]]])

When we perform a search, we need to specify the base of the tree where the search should begin and also the scope of the search. The scope indicates what part of the tree is to be covered while searching. ldap_list() performs the search for a specified filter on the directory with the scope, LDAP_SCOPE_ONELEVEL. This 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 on a UNIX shell and getting a list of files and folders in the current working directory).

This call takes an optional fourth parameter that is an array of just the required attributes. The newly introduced parameters attrsonly, sizelimit, timelimit and deref have exactly the same functionality as they have in the ldap_search() and ldap_read() functions. This function returns a search result identifier or false on error.

ldap_count_entries()

int ldap_count_entries(int link_identifier, int result_identifier)

ldap_count_entries() returns the number of entries stored as a result of previous search operations (as a result of a search call). result_identifier identifies the internal LDAP result. It returns false on error.

ldap_next_attribute()

string ldap_next_attribute(int link_identifier,
                 int result_entry_identifier, int &ber_identifier)

ldap_next_attribute() is called to retrieve the attributes in an entry. The internal state of the pointer is maintained by the ber_identifier. It is passed by reference to the function. The first call to ldap_next_attribute() is made with the result_entry_identifier returned from ldap_first_attribute(). It returns the next attribute in an entry on success, and false on error.

ldap_next_entry()

int ldap_next_entry(int link_identifier, int result_entry_identifier)

This function returns the entry identifier for the next entry in the result whose entries are being read starting with ldap_first_entry(). Successive calls to 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 ldap_first_entry with the result_identifier as returned from the ldap_first_entry(). If there are no more entries in the result then it returns false.

Search Functions - Page 11
Professional PHP4 Programming
Modification Functions - Page 13