Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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

Syntax 

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

Parameters

ld

[in] Session handle.

base

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

scope

[in] Specifies a value to indicate the scope of the search. The following table shows the possible values.

Value Description

LDAP_SCOPE_BASE

Searches the base entry only.

LDAP_SCOPE_ONELEVEL

Searches all entries in the first level below the base entry, excluding the base entry.

LDAP_SCOPE_SUBTREE

Searches the base entry and all entries in the tree below the base.
filter

[in] Pointer to a null-terminated string that specifies the search filter.

attrs

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

attrsonly

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

Return Value

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

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

Remarks

This function initiates an asynchronous search operation.

You can use the ldap_set_optionfunction with the ldsession handle to set the LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, and LDAP_OPT_DEREF options that determine how the search is performed.

As an asynchronous function, this function returns a message identifier for the operation. Call ldap_resultwith the message identifier 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_extor ldap_search_ext_sif you need support for LDAP 3 server and client controls.

In a multithreading environment, calls to ldap_searchare not thread-safe because the function returns a message identifier, rather than the return code. 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_extor ldap_search_ext_s, both of which are thread-safe.

When connecting to an LDAP 2 server, the application must perform a bind operation (by calling one of the ldap_bindor ldap_simple_bindroutines) before attempting other operations.

Requirements

Header winldap.h
Library wldap32.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also