LDAP_URL(3LDAP) LDAP Library Functions LDAP_URL(3LDAP)
NAME
ldap_url, ldap_is_ldap_url, ldap_url_parse, ldap_url_parse_nodn,
ldap_free_urldesc, ldap_url_search, ldap_url_search_s,
ldap_url_search_st, ldap_dns_to_url, ldap_dn_to_url - LDAP Uniform
Resource Locator functions
SYNOPSIS
cc[
flag... ]
file... -lldap[
library... ]
#include <lber.h>
#include <ldap.h>
int ldap_is_ldap_url(
char *url);
int ldap_url_parse(
char *url,
LDAPURLDesc **ludpp);
int ldap_url_parse_nodn(
char *url,
LDAPURLDesc **ludpp);
ldap_free_urldesc(
LDAPURLDesc *ludp);
int ldap_url_search(
LDAP *ld,
char *url,
int attrsonly);
int ldap_url_search_s(
LDAP *ld,
char *url,
int attrsonly,
LDAPMessage **res);
int ldap_url_search_st(
LDAP *ld,
char *url,
int attrsonly,
struct timeval *timeout,
LDAPMessage **res);
char *ldap_dns_to_url(
LDAP *ld,
char *dns_name,
char *attrs,
char *scope,
char *filter);
char *ldap_dn_to_url(
LDAP *ld,
char *dn,
int nameparts);
DESCRIPTION
These functions support the use of LDAP URLs (Uniform Resource Locators).
The following shows the formatting used for LDAP URLs.
ldap://hostport/dn[
?attributes[
?scope[
?filter]]]
where:
hostport Host name with an optional
:portnumber.
dn Base DN to be used for an LDAP search operation.
attributes Comma separated list of attributes to be retrieved.
scope One of these three strings: base one sub (default=base).
filter LDAP search filter as used in a call to
ldap_search(3LDAP).
The following is an example of an LDAP URL:
ldap://ldap.itd.umich.edu/c=US?o,description?one?o=umich
URLs preceded
URL: or wrapped in angle-brackets are tolerated. URLs can
also be preceded by
URL: and wrapped in angle-brackets.
ldap_is_ldap_url() returns a non-zero value if
url looks like an LDAP URL
(as opposed to some other kind of URL). It can be used as a quick check
for an LDAP URL; the
ldap_url_parse() function should be used if a more
thorough check is needed.
ldap_url_parse() breaks down an LDAP URL passed in
url into its component
pieces. If successful, zero is returned, an LDAP URL description is
allocated, filled in, and
ludpp is set to point to it. See
RETURN VALUES for values returned upon error.
ldap_url_parse_nodn() acts just like
ldap_url_parse() but does not
require
dn in the LDAP URL.
ldap_free_urldesc() should be called to free an LDAP URL description that
was obtained from a call to
ldap_url_parse().
ldap_url_search() initiates an asynchronous LDAP search based on the
contents of the
url string. This function acts just like
ldap_search(3LDAP) except that many search parameters are pulled out of
the URL.
ldap_url_search_s() performs a synchronous LDAP search based on the
contents of the
url string. This function acts just like
ldap_search_s(3LDAP) except that many search parameters are pulled out of
the URL.
ldap_url_search_st() performs a synchronous LDAP URL search with a
specified
timeout. This function acts just like
ldap_search_st(3LDAP) except that many search parameters are pulled out of the URL.
ldap_dns_to_url() locates the LDAP URL associated with a DNS domain name.
The supplied DNS domain name is converted into a distinguished name. The
directory entry specified by that distinguished name is searched for a
labeled URI attribute. If successful then the corresponding LDAP URL is
returned. If unsuccessful then that entry's parent is searched and so on
until the target distinguished name is reduced to only two nameparts. If
dns_name is
NULL then the environment variable LOCALDOMAIN is used. If
attrs is not
NULL then it is appended to the URL's attribute list. If
scope is not NULL then it overrides the URL's scope. If
filter is not
NULL then it is merged with the URL's filter. If an error is encountered
then zero is returned, otherwise a string URL is returned. The caller
should free the returned string if it is non-zero.
ldap_dn_to_url() locates the LDAP URL associated with a distinguished
name. The number of nameparts in the supplied distinguished name must be
provided. The specified directory entry is searched for a labeledURI
attribute. If successful then the LDAP URL is returned. If unsuccessful
then that entry's parent is searched and so on until the target
distinguished name is reduced to only two nameparts. If an error is
encountered then zero is returned, otherwise a string URL is returned.
The caller should free the returned string if it is non-zero.
RETURN VALUES
Upon error, one of these values is returned for
ldap_url_parse():
LDAP_URL_ERR_BADSCOPE URL scope string is invalid.
LDAP_URL_ERR_HOSTPORT URL hostport is invalid.
LDAP_URL_ERR_MEM Can't allocate memory space.
LDAP_URL_ERR_NODN URL has no DN (required).
LDAP_URL_ERR_NOTLDAP URL doesn't begin with
ldap://.
ATTRIBUTES
See
attributes(7) for a description of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Interface Stability | Evolving |
+--------------------+-----------------+
SEE ALSO
ldap(3LDAP),
ldap_search(3LDAP),
attributes(7) An LDAP URL Format, Tim Howes and Mark Smith, December 1995. Internet
Draft (work in progress). Currently available at this URL.
ftp://ds.internic.net/internet-drafts/draft-ietf-asid-ldap-format-03.txt
December 2, 2003
LDAP_URL(3LDAP)