ldap_search_st()--Perform an LDAP Search Operation (Timed Synchronous)

Syntax #include <sys/time.h> #include <ldap.h> int ldap_search_st( LDAP *ld, char *base, int scope, char *filter, char *attrs[], int attrsonly, struct timeval *timeout, LDAPMessage **res) Threadsafe: Yes

The ldap_search_st() function is used to perform an LDAP search operation.

ldap_search_st() is a synchronous request. Entries returned from the search (if any) are contained in the res parameter. This parameter is opaque to the caller. Entries, attributes, values, etc., should be extracted by calling the result parsing routines . The results contained in res should be freed when no longer in use by calling ldap_msgfree().

Both read and list functions can be obtained by using a filter such as objectclass=* and a scope either of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list).

Authorities and Locks

No OS/400 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 1778, The String Representation of Standard Attribute Syntaxes". 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. To put parentheses 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.

timeout

(Input) For the ldap_search_st() API, this specifies the local search timeout value.

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(), etc...).

Return Value

LDAP_SUCCESS

if the request was successful.

another LDAP error code

if the request was not successful.

Error Conditions

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

Error Messages

    The following message may be set from this function.
    CPF3CF2 E  Error(s) occurred during running of ldap_search_st API.

Related Information

    ldap_search_s() -- Synchronously search the directory.
    ldap_search() -- Asynchronously search the directory.
    ldap_search_ext() -- Asynchronously search the directory with controls.
    ldap_search_ext_s() -- Synchronously search the directory with controls.