Synchronously searches the directory using LDAP client or server controls.
#include <ldap.h>
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);
(IN) Points to the handle for the LDAP session.
(IN) Points to the distinguished name of the entry from which to start the search.
(IN) Specifies the scope of the search and uses one of the following flags:
LDAP_SCOPE_BASE (0x00)—searches the entry specified by the base parameter.
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 the entry specified by the base parameter.
(IN) Points to a search filter.
If NULL is passed, a default filter ("objectclass=*") is used, a filter which matches all entries in the directory. Using a NULL filter is not recommended for subtree searches on trees that potentially have hundreds of thousands of entries.
Simple filters take the form of strings: attribute name=attribute value. For more complex filters, see Using Search Filters.
(IN) Points to a NULL-terminated array of strings indicating which attributes to return with each matching entry. 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.
For example, to return the cn, surname, and givenName attributes, declare attrs as: char* attrs[]={"cn", "surname", "givenName", NULL};
(IN) Specifies whether to return just attributes or attributes and values.
Zero—return both attributes and values
Non-zero—return only attributes
(IN) Points to an array of LDAPControl structures that list the server controls to use with the search. Use NULL to specify no server controls.
(IN) Points to an array of LDAPControl structures that list the client controls to use with the search. Use NULL to specify no client controls.
(IN) Points to a timeval structure that specifies the maximum time to wait for the results of a search to complete. It 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 stored in the session handle option, LDAP_OPT_TIMELIMIT (whose default value is no timeout). For more information about possible values, see timeval.
(IN) Specifies the maximum number of entries to return.
To specify no limit, pass LDAP_NO_LIMIT (0).
To use the current value in the LDAP session handle (the LDAP_OPT_SIZELIMIT option), pass LDAP_DEFAULT_SIZELIMIT (-1).
(OUT) Returns a pointer to an array of result messages if the search succeeds or NULL if no results are returned.
|
0x00 |
LDAP_SUCCESS |
|
Non-zero |
Failure. For a complete list, see |
|
0x53 |
LDAP_ENCODING_ERROR |
|
0x55 |
LDAP_TIMEOUT |
|
0X57 |
LDAP_FILTER_ERROR |
The LDAP_OPT_DEREF option in the LDAP session handle affects how aliases are handled during the search.
The LDAP_DEREF_FINDING value means aliases are dereferenced when locating the base object but not during the search.
The LDAP_DEREF_SEARCHING value means aliases are dereferenced during the search but not when locating the base object of the search.
eDirectory supports two server controls:
Server-side sorting—1.2.840.113556.1.4.473
Virtual list views—2.16.840.1.113730.3.4.9
You must use the ldap_result and the ldap_parse_result functions to retrieve the results of the search.
Server timeouts and size limits for this function are set using the LDAP_OPT_TIMELIMIT and LDAP_OPT_SIZELIMIT options on the LDAP handle. Client timeouts and size limits are set using the timeout and sizelimit parameters.
For sample code, see search.c and searchmsg.c .