ldap_search_ext_s -- Synchronously Search the Directory Using 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)

The ldap_search_ext_s() routine initiates a synchronous search operation, allowing LDAP controls to be sent to the server and client.

Authorities and Locks

No IBM^® i authority is required. All authority checking is done by the LDAP server.

Parameters

ld

(Input) Specifies the LDAP pointer returned by a previous call to ldap_init(), ldap_ssl_init(), or ldap_open().

base

(Input) Specifies the DN of the entry at which to start the search.

scope

(Input) Specifies the scope of the search. It can be LDAP_SCOPE_BASE (to search the object itself), or LDAP_SCOPE_ONELEVEL (to search the object's immediate children), or LDAP_SCOPE_SUBTREE (to search the object and all its descendents).

filter

(Input) Specifies a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified using a prefix notation according to the following BNF:

      <filter>     ::= '(' <filtercomp> ')'
      <filtercomp> ::= <and> | <or> | <not> | <simple>
      <and>        ::= '&' <filterlist>
      <or>         ::= '|' <filterlist>
      <not>        ::= '!' <filter>
      <filterlist> ::= <filter> | <filter> <filterlist>
      <simple>     ::= <attributetype> <filtertype> <attributevalue>
      <filtertype> ::= '=' | '~=' | '<=' | '>='

The '~=' construct is used to specify approximate matching. The representation for <attributetype> and <attributevalue> are as described in RFC 2252, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions." In addition, <attributevalue> can be a single * to achieve an attribute existence test, or can contain text and *'s interspersed to achieve substring matching.

For example, the filter "(mail=*)" will find any entries that have a mail attribute. The filter "(mail=*@student.of.life.edu)" will find any entries that have a mail attribute ending in the specified string.

More complex filters are created using the & and | operators. For example, the filter "(&(objectclass=person)(mail=*))" will find any entries that have an objectclass of person and a mail attribute. To put parentheses or asterisks in a filter, escape them with a backslash '\' character. See RFC 2254, "A String Representation of LDAP Search Filters," for a more complete description of allowable filters.

attrs

(Input) Specifies a null-terminated array of character string attribute types to return from entries that match filter. If NULL is specified, all attributes will be returned.

attrsonly

(Input) Specifies attribute information. Attrsonly should be set to 1 to request attribute types only. Set to 0 to request both attributes types and attribute values.

serverctrls

(Input) Specifies a list of LDAP server controls. This parameter may be set to null. See Controls for LDAP APIs for more information about server controls.

clientctrls

(Input) Specifies a list of LDAP client controls. This parameter may be set to null. See Controls for LDAP APIs for more information about client controls.

sizelimit

(Input) Specifies the maximum number of entries to return. Note that the server may set a lower limit which is enforced at the server.

timeout

(Input) The local search timeout value and the operation time limit that is sent to the server within the search request.

res

(Output) Contains the result of the synchronous search operation. This result should be passed to the LDAP parsing routines (see ldap_first_entry(), ldap_next_entry(), and so on). The caller is responsible for freeing res with ldap_msgfree().

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error

if the request was not successful. The code can be interpreted by ldap_perror() or ldap_err2string().

Error Conditions

If ldap_search_ext_s() is not successful, an error code will be returned. See LDAP Client API Error Conditions for possible values for the error codes.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_first_entry() -- Retrieve first LDAP entry.
• ldap_first_reference() -- Return first continuation reference in a chain of search results.
• ldap_count_entries() -- Return number of entries in a chain of search results.
• ldap_msgfree() -- Free LDAP result message.
• ldap_search_s() -- Synchronously search the directory.
• ldap_search() -- Asynchronously search the directory.
• ldap_search_ext() -- Asynchronously search the directory with controls.
• ldap_search_st() -- Synchronously search the directory with timeout.

The ldap_search_ext_s() API supports LDAP V3 server controls, client controls, and allows varying size and time limits to be easily specified for each search operation.

[ Back to top | LDAP APIs | APIs by category ]