ldap_url_search_st()--Perform an LDAP URL Search Operation (Timed Synchronous)

 #include <sys/time.h>
 #include <ldap.h>
 
 int ldap_url_search_st(
                LDAP            *ld,
                char            *url,
                int             attrsonly,
                struct timeval  *timeout,
                LDAPMessage     **res )

The ldap_url_search_st() function is used to perform a synchronous LDAP search with a specified timeout based on the contents of the url parameter.

This function acts like ldap_search_st() except that the search parameters are retrieved from 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

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.

timeout

(Input) Specifies a timeout value for a synchronous search issued by the ldap_url_search_st() routine.

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_st() 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_s() -- Synchronously search using an LDAP URL.

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