In LDAP, search functions are used for both searching and reading information from the directory. The LDAP Libraries for C provide the following asynchronous and synchronous functions:
A search results can contain entry, references, or search result messages. The last message in the results is always a search result message. Each message type has its own set of functions for reading the results. If you use the ldap_first_message and ldap_next_message functions, the following message types are returned:
LDAP_RES_SEARCH_ENTRY
Returns the directory entries from the search.
LDAP_RES_SEARCH_REFERENCE
Returns a sequence of one or more LDAP URLs. An LDAP_RES_SEARCH_REFERENCE is returned for each area not explored by this LDAP server during the search.
If the LDAP server is configured to follow referrals automatically, the LDAP server will never return LDAP_RES_SEARCH_REFERENCE to the application.
LDAP_RES_SEARCH_RESULT
Returns a search result message.
If you are only interested in the entry messages from the search, you can use the ldap_first_entry and ldap_next_entry to read just the entry results and to skip any other type of message.
If you are only interested in search references returned from the search, you can use the ldap_first_reference and ldap_next_reference functions to read the references and to skip any other type of message.
The search parameters set up the criteria for where the search begins, what entries to find, and what information to return with the matching entries. Search contraints determine how many entries to return and set time limits on looking for the entries. These same parameters and constraints can be set up to perform read operations.
Base. The base parameter specifies the container in the directory where the search begins. You can specify the root of the directory tree, or any container or branch of the directory tree. For quick searches, be as specific as you can because a branch search is always faster than a full search from the tree root.
Scope. The scope parameter specifies how deep to search. It allows three levels to be set:
LDAP_SCOPE_BASE (0x00)—searches only the entry specified by the base parameter. If the base parameter is set to the entry and the scope parameter set to this level, the search becomes a read of this entry.
LDAP_SCOPE_ONELEVEL (0x01)—searches the immediate subordinates of the entry specified by the base parameter.
LDAP_SCOPE_SUBTREE (0x02)—searches the entire subtree starting with, and including, the entry specified by the base parameter. If the eDirectory server does not contain replicas for all the containers in the specified subtree, the server can automatically follow referrals to other servers. A session option, LDAP_OPT_REFERRALS, allows you to specify whether referrals are followed automatically or whether search references should be returned to where the additional entries are located. For more information, see Section 6.10, Session Preference Options
LDAP_SCOPE_SUBORDINATESUBTREE (0x03)—searches all subordinates of the specified base object, but does not include the base object, as the subtree scope does.
Filter. The search filter specifies what you are searching for. The following is a simple filter that searches for all entries with the last name of Smith.
"sn=Smith"
The default filter, if no filter is specified, is "(objectClass=*)". This filter searches every entry in the directory since the objectClass attribute is a required attribute of all entries in the directory.
These simple filters are strings with the following format:
attribute_name operator value
For example, if you specified (cn=Kim Smith), the search would return entries with a common name of Kim Smith.
For information about the grammar required to create more complex search filters, see Using Search Filters.
Attributes. The attribute parameter specifies which attributes to return with each matching entry. The parameter accepts the following types of values:
To return specific attributes, you pass a NULL-terminated array of attribute names in the parameter.
To return only entry names (and no attributes), set the first, and only, string in the array to LDAP_NO_ATTRS.
To return all attributes, set this parameter to NULL
Attributes Only. This parameter determines whether values are returned with the attributes specified in the attribute parameter. Set this parameter to zero (0) to return attributes and values. Set it to a non-zero value to return only attribute names and no values.
Time Limit. The time limit determines how long the server should wait for search results before returning to the client. The time limit is approximate because the client passes the value to the LDAP server with the search request and is dependent upon the LDAP server's interpretation of the limit.
The ldap_search_ext, ldap_search_ext_s, and ldap_search_ st functions allow you to specify the time limit with a timeout parameter. This parameter points to a timeval structure that specifies the maximum time to wait for the results of a search to complete. The structure specifies both the time the server waits for the operation to complete as well as the time the local function waits for the server to respond. If the timeout parameter is set to NULL, the client timeout is infinite and the server uses the timeout value specified in the LDAP_OPT_TIMELIMIT option.
The other search functions do not have a timeout parameter and use the LDAP_OPT_TIMELIMIT option. This option determines the number of seconds an LDAP server will spend on a search. A value of LDAP_NO_LIMIT (0) means no limit. The default is LDAP_NO_LIMIT.
To get the option's current value, use ldap_get_option.
To set the option's value, use ldap_set_option.
Search Result Limits. This parameter or constraint determines how many entries are returned in a search results. Two functions, ldap_search_ext and ldap_search_ext_s, have a sizelimit parameter. To specify no limit, set this parameter to LDAP_NO_LIMIT (0). To use the value in the LDAP_OPT_SIZELIMIT option, set this parameter to -1.
The other search functions use the LDAP_OPT_SIZELIMIT option to determine how many entries are returned from a search. A value of LDAP_NO_LIMIT (0) means no limit. The default is LDAP_NO_LIMIT.
To get the current value, use ldap_get_option.
To set the value, use ldap_set_option.
Alias Dereferencing. The LDAP_OPT_DEREF option determines how aliases are handled during a search. It supports the following values:
LDAP_DEREF_NEVER (0X00)
LDAP_DEREF_SEARCHING (0x01)
LDAP_DEREF_FINDING (0x02)
LDAP_DEREF_ALWAYS (0x03)
The default is LDAP_DEREF_NEVER.
The LDAP_DEREF_SEARCHING flag indicates that aliases are dereferenced during the search but not when locating the base object of the search.
The LDAP_DEREF_FINDING flag indicates that aliases are dereferenced when locating the base object but not during the search.
The LDAP_DEREF_ALWAYS flag indicates that aliases are dereferenced when locating the base object and when finding entries.
The LDAP_DEREF_NEVER flag indicates that aliases are not dereferenced.
To get the current value, use ldap_get_option.
To set the value, use ldap_set_option.
The LDAP search filter grammar is specified in RFC 2254 and 2251. The grammar uses ABNF notation.
filter = " ( " filtercomp " ) "
filtercomp = and / or /not /item
and = "&" filterlist
filterlist = 1*filter
or = "|" filterlist
filterlist = 1*filter
not = "!" filterlist
filterlist = 1*filter
item = simple/present/substring/extensible
simple = attr filtertype value
attr = name | name;binary
filtertype = equal/approx/greater/less
value = data valid for the attribute's syntax
equal = "="
approx = "~="
greater = ">="
less = "<="
present = attr "=*"
attr = name | name;binary
substing = attr "=" [initial] any [final]
attr = name | name;binary
initial = value
any = "*" *(value "*")
final = value
extensible = attr [":dn"] [":" matchingrule] ":="value
/[":dn] ":" matchingrule ":=" value
/matchingrule = name | OID
For additional options for the attr option, see Section 4.1.5 of RFC 2251.
For additional information on the value option, see Section 4.1.6 of RFC 2251.
IMPORTANT:eDirectory does not support LDAP approximate (~=) matching or extensible matching rules.
Table 1-7 LDAP Filter Operators
The following boolean operators can be combined with the standard operators to form more complex filters. Note that boolean operator syntax is used different in search filters than in the C and Java programming languages, but the concepts are the same.
Table 1-8 LDAP Filter Boolean Operators
Table 1-9 Examples for Different Filters
Operational attributes are not automatically returned in search results; they must be requested by name in the search operation. For a list of supported operational attributes in eDirectory 8.5, see LDAP Operational Attributes
in LDAP and eDirectory. The LDAP servers in previous releases of eDirectory do not support operational attributes.