ldap_url_search()--Perform an LDAP URL Search Operation

 #include <ldap.h>

 int ldap_url_search(
                LDAP  *ld,
                char  *url,
                int    attrsonly)

The ldap_url_search() function is used to perform an asynchronous LDAP search based on the contents of the url parameter.

This function acts like ldap_search() except that the search parameters are specified by the URL.

This routine supports the use of LDAP URLs (Uniform Resource Locators).

LDAP URLs look like this:

    ldap[s]://[hostport][/[dn[?[attributes][?[scope][?[filter]]]]]]

where:

• hostport is a host name with an optional ":portnumber"
• dn is the base DN to be used for an LDAP search operation
• attributes is a comma separated list of attributes to be retrieved
• scope is one of these three strings: base one sub (default=base)
• filter is LDAP search filter as used in a call to ldap_search

For example:

  ldap://example.ibm.com/c=US?o,description?one?o=ibm

URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated, including the form url:ldapurl.

For example:

   URL:ldap://example.ibm.com/c=US?o,description?one?o=ibm

This form also is allowed: <url:ldapurl>.

For example:

   <URL:ldap://example.ibm.com/c=US?o,description?one?o=ibm>

Notes:

1. For search operations, if hostport is omitted, host and port for the current connection are used. If hostport is specified, and is different from the host and port combination used for the current connection, the search is directed to that host and port, instead of using the current connection. In this case, the underlying referral mechanism is used to bind to hostport.
2. If the LDAP URL does not contain a search filter, the filter defaults to "(objectClass=*)".

Authorities and Locks

None.

Return Value

Message ID of the Operation Initiated

if the request was successful. A subsequent call to ldap_result(), can be used to obtain the result.

-1

if the request was not successful.

Error Conditions

If ldap_url_search() is not successful, -1 will be returned setting the session error parameters (ld_error) in the LDAP structure appropriately, which can be obtained by using ldap_get_lderrno(). See LDAP Client API Error Conditions for possible LDAP error code values.

Error Messages

The following message may be sent from this function.

Related Information

• ldap_free_urldesc() -- Frees an LDAP URL description.
• ldap_is_ldap_url() -- Check a URL string to see if it is an LDAP URL.
• ldap_url_parse() -- Break up an LDAP URL string into its components.
• ldap_url_search_s() -- Synchronously search using an LDAP URL.
• ldap_url_search_st() -- Synchronously search using an LDAP URL and a timeout.