ldap_url_search_s() -- Perform an LDAP URL Search Operation (Synchronous)

 #include <ldap.h>

 int ldap_url_search_s(
                LDAP   *ld,
                char   *url,
                int     attrsonly,
                LDAPMessage  **res)

The ldap_url_search_s() function is used to perform a synchronous LDAP search based on the contents of urlparameter.

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

This routine support 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

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

url

(Input) Specifies a pointer to the URL string.

attrsonly

(Input) Specifies attribute information. Set to 1 to request attribute types only. Set to 0 to request both attribute types and attribute values.

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.

Error Conditions

If ldap_url_search_s() is not successful, it returns an LDAP error code other than LDAP_SUCCESS. 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_url_parse() -- Extract information from results.
• ldap_is_ldap_url() -- Check a URL string to see if it is an LDAP URL.
• ldap_url_search() -- Asynchronously search using an LDAP URL.
• ldap_url_search_st() -- Synchronously search using an LDAP URL and a timeout.

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