Copyright Digital Equipment Corp. All rights reserved.
Searching
The following functions are used to search the LDAP directory,
returning a requested set of attributes for each entry matched.
There are five variations.
int ldap_search_ext(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
int *msgidp
);
int ldap_search_ext_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPControl **serverctrls,
LDAPControl **clientctrls,
struct timeval *timeout,
int sizelimit,
LDAPMessage **res
);
int ldap_search(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly
);
int ldap_search_s(
LDAP *ld,
const char *base,
int scope,
const char *filter,
char **attrs,
int attrsonly,
LDAPMessage **res
);
int ldap_search_st(
LDAP *ld,
char *base,
int scope,
char *filter,
char **attrs,
int attrsonly,
struct timeval *timeout,
LDAPMessage **res
);
Parameters are as follows:
ld The session handle.
base The dn of the entry at which to start the search.
scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL
(0x01), or LDAP_SCOPE_SUBTREE (0x02), indicating
the scope of the search.
filter A character string representing the search filter.
The value NULL can be passed to indicate that the
filter (objectclass=*) that matches all entries
should be used.
attrs A NULL-terminated array of strings indicating
which attributes to return for each matching
entry. Passing NULL for this parameter causes
all available user attributes to be retrieved. The
special constant string LDAP_NO_ATTRS (1.1) can be
used as the only element in the array to indicate
that no attribute types should be returned by the
server. The special constant string LDAP_ALL_USER_
ATTRS (*), can be used in the attrs array along
with the names of some operational attributes to
indicate that all user attributes plus the listed
operational attributes should be returned.
attrsonly A boolean value that should be either zero if both
attribute types and values are to be returned or
non-zero if only types are wanted.
timeout For the ldap_search_st() function, this specifies
the local search timeout value (if it is NULL,
the timeout is infinite). For the ldap_search_
ext() and ldap_search_ext_s() functions, this
specifies both the local search timeout value
and the operation time limit that is sent to the
server within the search request. For the ldap_
search_ext() and ldap_search_ext_s() functions,
passing a NULL value for timeout causes the global
default timeout stored in the LDAP session handle
to be used (set using ldap_set_option() with the
LDAP_OPT_TIMELIMIT parameter).
sizelimit For the ldap_search_ext() and ldap_search_ext_s()
calls, this is a limit on the number of entries to
return from the search. A value of LDAP_NO_LIMIT
(0) means no limit.
res For the synchronous calls, this is a result
parameter which will contain the results of the
search upon completion of the call.
serverctrls List of LDAP server controls.
clientctrls List of client controls.
msgidp This result parameter will be set to the message
id of the request if the ldap_search_ext() call
succeeds.
There are three options in the session handle ld that potentially
affect how the search is performed. They are as follows:
LDAP_OPT_ A limit on the number of entries to return from
SIZELIMIT the search. A value of LDAP_NO_LIMIT (0) means
no limit. Note that the value from the session
handle is ignored when using the ldap_search_
ext() or ldap_search_ext_s() functions.
LDAP_OPT_ A limit on the number of seconds to spend on
TIMELIMIT the search. A value of LDAP_NO_LIMIT (0) means
no limit. Note that the value from the session
handle is ignored when using the ldap_search_
ext() or ldap_search_ext_s() functions.
LDAP_OPT_DEREF One of LDAP_DEREF_NEVER(0x00), LDAP_DEREF_
SEARCHING(0x01), LDAP_DEREF_FINDING (0x02),
or LDAP_DEREF_ALWAYS (0x03), specifying how
aliases should be handled during the search.
The LDAP_DEREF_SEARCHING value means aliases
should be dereferenced during the search but not
when locating the base object of the search. The
LDAP_DEREF_FINDING value means aliases should be
dereferenced when locating the base object but
not during the search.
The ldap_search_ext() function initiates an asynchronous search
operation and returns either the constant LDAP_SUCCESS if the
request was successfully sent or another LDAP error code if
not. See Errors for more information about possible errors and
how to interpret them. If successful, ldap_search_ext() places
the message id of the request in *msgidp. A subsequent call to
ldap_result() can be used to obtain the results from the search.
These results can be parsed using the result parsing functions
described in Errors.
Similar to ldap_search_ext(), the ldap_search() function
initiates an asynchronous search operation and returns the
message id of the operation initiated. As for ldap_search_ext(),
a subsequent call to ldap_result() can be used to obtain the
result of the search. In case of error, ldap_search() will return
-1, setting the session error parameters in the LDAP structure
appropriately.
The synchronous ldap_search_ext_s(), ldap_search_s(), and ldap_
search_st() functions all return the result of the operation,
either the constant LDAP_SUCCESS if the operation was successful
or another LDAP error code if it was not. See Errors for more
information about possible errors and how to interpret them.
Entries returned from the search (if any) are contained in the
res parameter. This parameter is opaque to the caller. Entries,
attributes, and values should be extracted by calling the parsing
functions. The results contained in res should be freed when no
longer in use by calling ldap_msgfree().
The ldap_search_ext() and ldap_search_ext_s() functions support
LDAPv3 server controls, client controls, and allow varying size
and time limits to be easily specified for each search operation.
The ldap_search_st() function is identical to ldap_search_s()
except that it takes an additional parameter specifying a local
timeout for the search. The local search timeout is used to
limit the amount of time the API implementation will wait for
a search to complete. After the local search timeout the search
operation will return LDAP_TIMEOUT if the search result has not
been removed.
Additional information available:
Reading_and_Listing_the_Children_of_an_Entry