9. Bigloo LDAP interface

9.1.1 LDAP types
9.1.2 LDAP connection
9.1.3 LDAP data modifying
9.1.4 LDAP searching
9.1.5 LDAP cache control
9.1.6 LDAP errors handling
9.1.7 LDAP misc utilities

This chapter describes a scheme interface for client LDAP library. The interface allows to write LDAP clients with Bigloo scheme. It was tested with OpenLDAP-1.2.9 package from http://www.openldap.org (5).

The chapter includes many verbatim excerpts from corresponding original manual pages, describing the C interface, which are provided with the package from http://www.openldap.org

9.1 API for C library

9.1.1 LDAP types

foreign: ldap

LDAP server connection handle, resulted from successful call of ldap-open or ldap-init.

Bigloo type: attlist

List of attribute names and values. attlist is a scheme list, each element of which is a scheme list itself, which has the following structure: the first element is the attribute name string, and the rest is a (possibly empty) list of the attribute value strings. For example :

'(("objectclass" "organizationalPerson") ("telephonenumber" "1234567" "7654321"))

The objects of the attlist type are passed as arguments of the following functions: ldap-add, ldap-modify-delete ldap-modify-replace and ldap-get-attributes.

9.1.2 LDAP connection

procedure: ldap-init #!optional host::string port::int

host

LDAP server hostname string. See ldap_init(3) manual page for details.

port

LDAP server port number. See ldap_init(3) manual page for details.

Allocates an LDAP structure but does not open an initial connection

Return LDAP connection handle of type ldap.

See also ldap_init(3) manual page.

procedure: ldap-open #!optional host::string port::int

host

LDAP server hostname string. See ldap_open(3) manual page for details.

port

LDAP server port number. See ldap_open(3) manual page for details.

Opens a connection to an LDAP server and allocates an LDAP structure

Return LDAP connection handle of type ldap.

See also ldap_open(3) manual page.

procedure: ldap-bind ld::ldap who::string cred::string

ld

Result of a successful call to ldap-open or ldap-init

who

Specifies DN for an LDAP entry corresponding to user logging in

cred

Specifies the userPassword attribute value of a LDAP entry corresponding to the user logging in or other credentials

ldap-bind provides the connection with authentication information, and is an interface to ldap_simple_bind C client library function.

Example

This binds the user with DN cn=root,o=jet,c=ru and password secret :

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") ... )

See also ldap_simple_bind(3) manual page.

procedure: ldap-unbind ld::ldap

ld

Result of a successful call to ldap-open or ldap-init

ldap-unbind unbinds from directory, terminates the current association, closes the connection ld and frees resources associated with the corresponding LDAP structure

See also ldap_unbind(3) manual page.

9.1.3 LDAP data modifying

procedure: ldap-add ld::ldap dn::string mods::attlist => #unspecified

ld

Result of a successful call to ldap-open or ldap-init

dn

Specifies DN for a LDAP entry to add

mods

Specifies non-empty attlist. See section 9.1.1 LDAP types.

ldap-add adds new LDAP entry, it is an interface to ldap_add C library function.

Return #unspecified. Generates exception in case of error. Use ldap-errno to get LDAP error code.

Example :

(let((ld(ldap-open))) ;; open default LDAP connection (ldap-bind ld "cn=root,o=jet,c=ru" "secret") ;; introduce self to server ;; add new entry (ldap-add ld "cn=Tsichevski,o=jet,c=ru" '(("cn" "Tsichevski Vladimir") ("objectclass" "person") ("organization" "jet"))))

See also ldap_add(3) manual page.

procedure: ldap-modify-add ld::ldap dn::string mods::ldapattr

ld

Result of a successful call to ldap-open or ldap-init

dn

Specifies DN for an existing LDAP entry Specifies non-empty list of modifiers. See section 9.1.1 LDAP types.

ldap-modify-add adds new attributes to LDAP entry, it is an interface to ldap_modify C library function.

Example :

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") (ldap-modify-add ld "cn=Tsichevski,o=jet,c=ru" '(("cn" "Tsichevski Vladimir") ("objectclass" "person") ("organization" "jet"))))

See alsoldap_modify(3) manual page.

procedure: ldap-modify-delete ld::ldap dn::string mods::attlist

ld

Result of a successful call to ldap-open or ldap-init

dn

Specifies DN for an existing LDAP entry

mods

Specifies non-empty attlist. See section 9.1.1 LDAP types.

ldap-modify-delete removes attributes from LDAP entry, and is an interface to ldap_modify C API function.

Example :

In the following example the value jet of attribute organization will be removed from entry cn=Tsichevski,o=jet,c=ru.

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") (ldap-modify-delete ld "cn=Tsichevski,o=jet,c=ru" '(("organization" "jet"))))

In the next example the entire attribute organization will be removed from cn=Tsichevski,o=jet,c=ru entry.

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") (ldap-modify-delete ld "cn=Tsichevski,o=jet,c=ru" '(("organization"))))

See also ldap_modify(3) manual page.

procedure: ldap-modify-replace ld::ldap dn::string mods::attlist

ld

Result of a successful call to ldap-open or ldap-init

dn

Specifies the distinct name of an existing LDAP entry

mods

Specifies non-empty attlist. See section 9.1.1 LDAP types.

ldap-modify-replace replaces attributes of LDAP entry, creating the attribute in necessary, and is an interface to ldap_modify LDAP client library.

Example :

In the following example the new value jet of attribute organization replaces the old value in entry cn=Tsichevski,o=jet,c=ru.

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") (ldap-modify-replace ld "cn=Tsichevski,o=jet,c=ru" '(("organization" "jet"))))

See also ldap_modify(3) manual page.

procedure: ldap-delete ld::ldap dn::string

ld

Result of a successful call to ldap-open or ldap-init

dn

Specifies DN for an existing LDAP entry to remove

ldap-delete removes LDAP entry, and is an interface to ldap_delete C API function.

Example :

(let((ld(ldap-open))) (ldap-bind ld "cn=root,o=jet,c=ru" "secret") (ldap-delete ld "cn=Tsichevski,o=jet,c=ru"))

See also ldap_delete(3) manual page.

9.1.4 LDAP searching

procedure: ldap-search ld::ldap #!key base scope filter atts attrsonly?

ld

Result of a successful call to ldap-open or ldap-init

base

Search base DN. System default value used if not specified. See ldap.conf(5) manual page.

scope

Symbol base or integer 0, to search the object itself, symbol onelevel or integer 1, to search the object's immediate children, symbol subtree or integer 2 to get all the object subtree. The default is subtree.

filter

String representation of the filter to apply. See ldap_search(3) manual page for details. Default is "objectclass=*".

atts

List of names of LDAP attributes to be shown in search results. If omitted, all the attributes will be shown.

attrsonly

If true, then search result will have only the names of LDAP attributes (no attribute values).

ldap-search returns integer result LDAP message id or raises an exception in case of error.

See example in ldap-next-entry.

See also ldap_search(3) manual page.

procedure: ldap-count-entries ld::ldap msg::ldap-message => int

ld

Result of a successful call to ldap-open or ldap-init LDAP message object, resulted from successful invocation of ldap-result

Return value

ldap-count-entries returns the number of entries in search result or raises an exception in case of error.

Example :

In this example the total number of entries in LDAP tree is measured :

(let*((ld(ldap-open)) (msgid(ldap-search ld atts: '()));; only DN's, no attributes (result(ldap-result ld msgid))) (ldap-count-entries ld result))

See also ldap_count_entries(3) manual page.

procedure: ldap-first-entry ld::ldap msg::ldap-message*

ld

Result of a successful call to ldap-open or ldap-init LDAP message object, resulted from successful invocation of ldap-result

ldap-first-entry returns the first result entry or #f if no more entries available.

The following returns root entry in LDAP tree:

(let*((ld(ldap-open)) (msgid(ldap-search ld atts: '())) (result(ldap-result ld msgid))) (ldap-first-entry ld result))

See also ldap_first_entry(3) manual page.

procedure: ldap-get-dn ld::ldap msg::ldap-message*

ld

Result of a successful call to ldap-open or ldap-init

msg

LDAP message object as returned from ldap-first-entry or ldap-next-entry

return DN of LDAP message

See also ldap_get_dn(3) manual page.

procedure: ldap-get-attributes ld::ldap msg::ldap-message* => attlist

ld

Result of a successful call to ldap-open or ldap-init

msg

LDAP message object as returned from ldap-first-entry or ldap-next-entry

Return list of entry attributes in form of attlist. See section 9.1.1 LDAP types.

Example :

See example in ldap-next-entry.

procedure: ldap-get-values ld::ldap msg::ldap-message* attr::string

ld

Result of a successful call to ldap-open or ldap-init

msg

The LDAP message object returned from ldap-first-entry, ldap-next-entry

attr

The attribute name (scheme string)

returns values of specific attribute

Return list of attribute values (scheme strings) or #f of entry has no such attribute.

Example :

The following statement returns first value of attribute objectclass of LDAP root entry

(let*((ld(ldap-open)) (msgid(ldap-search ld)) (result(ldap-result ld msgid)) (msg(ldap-first-entry ld result))) (ldap-get-values ld result "objectclass")) => ("organization")

See also ldap_get_values(3) manual page.

procedure: ldap-message-free msg::ldap-message*

msg

LDAP message object returned from ldap-first-entry, ldap-next-entry

frees an LDAP message structure

procedure: ldap-next-entry ld::ldap msg::ldap-message*

ld

Result of a successful call to ldap-open or ldap-init LDAP message object, resulted from successful invocation of ldap-result

ldap-next-entry returns the result entry following given entry or #f if no more entries available.

Example :

This opens LDAP connection, and retrieves all antries in the LDAP tree :

(let*((ld(ldap-open)) (msgid(ldap-search ld atts: '())) (result(ldap-result ld msgid))) (let loop((msg(ldap-first-entry ld result)) (accu '())) (if msg (let((node(cons(ldap-get-dn ld msg) (ldap-get-attributes ld msg)))) (loop (ldap-next-entry ld msg) (cons node accu))) (begin(ldap-message-free result) (reverse accu))))) => (("dc=jet,dc=msk,dc=ru" ("cn" "Jet Infosystems Int.") ("objectclass" "dmd")) ("uid=archive,dc=jet,dc=msk,dc=ru" ("uid" "archive") ("objectclass" "documentSeries") ("cn" "Archive of documents")) ...

See also ldap_first_entry(3) manual page.

procedure: ldap-result ld::ldap msgid::int #!optional timeout

ld

Result of a successful call to ldap-open or ldap-init

msgid

Specifies LDAP request id, returned by successful invocation of one of LDAP operation routines (e.g., ldap-search, ldap-modify).

timeout

Optionally specifies the response waiting timeout in seconds. If is not provided the infinite wait assumed.

This routine is used to wait for and return the result of an operation previously initiated by one of the LDAP operation routines (e.g., ldap-search, ldap-modify).

ldap-result returns the result LDAP message or raises an exception in case of error.

See example in ldap-next-entry.

See also ldap_result(3) manual page.

9.1.5 LDAP cache control

procedure: ldap-flush-cache! ld::ldap

ld

Result of a successful call to ldap-open or ldap-init

Deletes cache contents, but does not effect it in any other way

See also ldap_flush_cache(3) manual page.

procedure: ldap-destroy-cache! ld::ldap

ld

Result of a successful call to ldap-open or ldap-init

Turn off caching and completely remove cache from memory

See also ldap_destroy_cache(3) manual page.

procedure: ldap-disable-cache! ld::ldap

ld

Result of a successful call to ldap-open or ldap-init

Temporarily disables use of cache (new requests are not cached and cache is not checked when returning results). It does not delete the cache contents from memory

See also ldap_disable_cache(3) manual page.

procedure: ldap-enable-cache! ld::ldap timeout::int maxmem::int

ld

Result of a successful call to ldap-open or ldap-init

timeout

Timeout in seconds. Used to decide how long to keep cached requests

maxmem

Cache size limit in bytes. Used to set an upper bound on how much memory cache will use. You can specify 0 for maxmem to restrict cache size by the timeout only.

Turns on local caching or changes cache parameters (lifetime of cached requests and memory used).

See also ldap_enable_cache(3) manual page.

procedure: ldap-set-cache-options! ld::ldap opts::int

ld

Result of a successful call to ldap-open or ldap-init

opts

See ldap_set_cache_options(3) manual page for details.

See ldap_set_cache_options(3) manual page for details.

procedure: ldap-uncache-entry! ld::ldap dn::string

ld

Result of a successful call to ldap-open or ldap-init

dn

DN of entry to remove.

Removes all requests that make reference to the DN from the cache

See also ldap_uncache_entry(3) manual page.

procedure: ldap-uncache-request! ld::ldap msgid::int

ld

Result of a successful call to ldap-open or ldap-init

msgid

Specifies LDAP request id, returned by successful invocation of one of LDAP operation routines (e.g., ldap-search, ldap-modify).

remove the request indicated by the LDAP request id msgid from the cache

See also ldap_uncache_request(3) manual page.

9.1.6 LDAP errors handling

procedure: ldap-errno ld::ldap => int

ld

Result of a successful call to ldap-open or ldap-init

Result of the last LDAP API call. The value of 0 if no error. To get a readable error description use ldap-error-string.

procedure: ldap-error-string errno::int => string

errno

LDAP error number. Use ldap-errno to get this value from ldap structure.

Interface to ldap_err2string() C API call.

See also ldap_err2string(3) manual page.

9.1.7 LDAP misc utilities

procedure: ldap-explode-dn dn::string

dn

DN string as returned by ldap-get-dn

Takes a DN as returned by ldap-get-dn and breaks it up into its component parts. This is an interface to ldap_explode_dn() C call.

See also ldap_explode_dn(3) manual page.

Example :

(ldap-explode-dn " o=jet, c=ru") => ("c=ru" " o=jet")

procedure: ldap-answer ld::ldap msgid::int => pair-nil

Given a result of successful ldap-search operation msgid, returns the list of LDAP entries. Every element of this list is a result of cons operation on the DN of the entry, and entry attribute list in a attlist format.

This example code does essentially same operation as the example code provided in ldap-next-entry section.

(let*((ld(ldap-open)) (msgid(ldap-search ld))) (ldap-answer ld msgid))

procedure: ldap-delete-recursive ld::ldap dn::bstring => pair-nil

This procedure deletes the LDAP entry along with all descendants of that entry. Return the entry list just deleted in a form described in ldap-answer section.

procedure: current-ldap #!optional new-value

Realizes the concept of default LDAP connection. Other procedures use the result of calling current-ldap procedure as a default LDAP connection handle.

=>

procedure: ldap-defbase #!optional arg => bstring

Realizes the ldap default base concept according to the following rules:

• If no arguments given, and value was previously set, returns this value.
• If an argument given, and the argument is a string, store and return that value.
• If an argument given, and the argument is a LDAP connection handle, perfor a ldap-search operation without giving a base argument, return the DN of entry returned.
• If an argument given, and the value was not previously set, resolve the default base using (current-ldap) as a LDAP connection.

(ldap-defbase) => "dc=jet,dc=msk,dc=ru"

procedure: ldap-commit! dn::bstring new-atts::pair #!optional ldap

Intellectual LDAP entry update. Reads the LDAP entry, examines the difference between the old attributes and the new ones. Performs the appropriate updates: removes the obsolete attributes with the use of ldap-modify-delete, adds the new attributes using ldap-modify-add, replaces the attribute values with the use of ldap-modify-replace.