ldap_url_search_s() -- Perform an LDAP URL Search Operation (Synchronous)
Syntax
#include <ldap.h> int ldap_url_search_s( LDAP *ld, char *url, int attrsonly, LDAPMessage **res)
Default Public Authority: *USE
Library Name/Service Program: QSYS/QGLDCLNT
Threadsafe: Yes
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:
- 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.
- 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.
Message ID | Error Message Text |
---|---|
CPF3CF2 E | Error(s) occurred during running of ldap_url_search_s API. |
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.
API introduced: V4R3
[ Back to top | LDAP APIs | APIs by category ]