ldap_search

The ldap_search function searches search the LDAP directory and returns a requested set of attributes for each entry matched.

ULONG ldap_search(
  LDAP* ld,
  PCHAR base,
  ULONG scope,
  PCHAR filter,
  PCHAR attrs[],
  ULONG attrsonly
);

Parameters

ld

[in] The session handle.

base

[in] The distinguished name of the entry at which to start the search.

scope

[in] The scope of the search. See Remarks for a description.

filter

[in] The search filter. See Remarks for more information.

attrs

[in] A null-terminated array of strings indicating which attributes to return for each matching entry. Pass NULL to retrieve all available attributes.

attrsonly

[in] A boolean value that should be zero if both attribute types and values are to be returned, nonzero if types only are wanted.

Return Values

If the function succeeds, it returns the message ID of the search operation.

If the function fails, it returns –1 and sets the session error parameters in the LDAP data structure.

Remarks

The ldap_search function initiates an asynchronous search operation. The scope of the search is determined by the value of the scope parameter, as follows:

Three options in the LDAP structure also determine how the search is performed: LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, and LDAP_OPT_DEREF. See the LDAP structure reference for more information.

As an asynchronous function, ldap_search returns a message ID for the operation. Call ldap_result with the message ID to get the result of the operation. To cancel an asynchronous search operation before it has completed, call ldap_abandon.

If you prefer to have the function return the results directly, use the synchronous routine ldap_search_s. Use ldap_search_ext or ldap_search_ext_s if you need support for LDAP 3 server and client controls.

Multithreading: Calls to ldap_search are not thread-safe because the function returns a message ID, rather than the return code. In order to determine whether the call returned an error value, you have to retrieve the return code from the connection block. It is possible for another thread to overwrite the return code before you retrieve it. Use ldap_search_ext, or ldap_search_ext_s, both of which are thread safe.

Note  When connecting to an LDAP 2 server, the application must perform a bind operation (by calling one of the ldap_bind or ldap_simple_bind routines) before attempting other operations.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP4 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in Winldap.h.
  Library: Use Wldap32.lib.
  Unicode: Declared as Unicode and ANSI prototypes.

See Also

Functions, LDAP, ldap_abandon, ldap_bind, ldap_result, ldap_search_ext, ldap_search_ext_s, ldap_search_s, ldap_simple_bind