@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1998 Free Software Foundation, Inc. 
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/ldap.info
@node LDAP Support, Internationalization, ToolTalk Support, top
@chapter LDAP Support
@cindex LDAP

XEmacs can be linked with a LDAP client library to provide Elisp primitives
to access directory servers using the Lightweight Directory Access Protocol.

@menu
* Building XEmacs with LDAP support::  How to add LDAP support to XEmacs
* XEmacs LDAP API::             Lisp access to LDAP functions
* Syntax of Search Filters::    A brief summary of RFC 1558
@end menu

@node Building XEmacs with LDAP support, XEmacs LDAP API, LDAP Support, LDAP Support
@comment  node-name,  next,  previous,  up
@section Building XEmacs with LDAP support

LDAP support must be added to XEmacs at build time since it requires
linking to an external LDAP client library.  As of 21.2, XEmacs has been
successfully built and tested with

@itemize @bullet
@item OpenLDAP 1.0.3 (@url{http://www.openldap.org/})
@item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
@item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
@end itemize

Other libraries conforming to RFC 1823 will probably work also but may
require some minor tweaking at C level.

The standard XEmacs configure script autodetects an installed LDAP
library provided the library itself and the corresponding header files
can be found in the library and include paths.  A successful detection
will be signalled in the final output of the configure script.



@node XEmacs LDAP API, Syntax of Search Filters, Building XEmacs with LDAP support, LDAP Support
@comment  node-name,  next,  previous,  up
@section XEmacs LDAP API

XEmacs LDAP API consists of two layers:  a low-level layer which tries
to stay as close as possible to the C API (where practical) and a
higher-level layer which provides more convenient primitives to
effectively use LDAP.

As of XEmacs 21.0, only interfaces to basic LDAP search functions are
provided, broader support is planned in future versions.

@menu
* LDAP Variables::              Lisp variables related to LDAP
* The High-Level LDAP API::     High-level LDAP lisp functions 
* The Low-Level LDAP API::      Low-level LDAP lisp primitives
@end menu


@node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
@comment  node-name,  next,  previous,  up
@subsection LDAP Variables

@defvar ldap-default-host
The default LDAP server hostname.
A TCP port number can be appended to that name using a colon as 
a separator.
@end defvar

@defvar ldap-default-port
Default TCP port for LDAP connections.
Initialized from the LDAP library. Default value is 389.
@end defvar

@defvar ldap-default-base
Default base for LDAP searches.
This is a string using the syntax of RFC 1779.
For instance, "o¬ME, cÿ" limits the search to the
Acme organization in the United States.
@end defvar

@defvar ldap-host-parameters-alist
An alist of per host options for LDAP transactions.  
The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
@var{host} is the name of an LDAP server. A TCP port number can be
appended to that name using a colon as a separator.
@var{propn} and @var{valn} are
property/value pairs describing parameters for the server.  Valid
properties:
@table @code
@item binddn
The distinguished name of the user to bind as.  This may look like
@samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
@item passwd
The password to use for authentication.
@item auth
The authentication method to use, possible values depend on the LDAP
library XEmacs was compiled with, they may include @code{simple},
@code{krbv41} and @code{krbv42}.
@item base
The base for the search. This may look like @samp{cÿ, o¬me}, see 
RFC 1779 for syntax details.
@item scope
One of the symbols @code{base}, @code{onelevel} or @code{subtree} 
indicating the scope of the search limited to a base
object, to a single level or to the whole subtree. 
@item deref
The dereference policy is one of the symbols @code{never},
@code{always}, @code{search} or @code{find} and defines how aliases are
dereferenced.
@table @code
@item never
Aliases are never dereferenced
@item always
Aliases are always dereferenced
@item search
Aliases are dereferenced when searching
@item find
Aliases are dereferenced when locating the base object for the search
@end table
@item timelimit
The timeout limit for the connection in seconds.
@item sizelimit
The maximum number of matches to return for searches performed on this connection.
@end table
@end defvar



@node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
@comment  node-name,  next,  previous,  up
@subsection The High-Level LDAP API

As of this writing the high-level Lisp LDAP API only provides for LDAP
searches.  Further support is planned in the future.

The @code{ldap-search} function provides the most convenient interface
to perform LDAP searches.  It opens a connection to a host, performs the
query and cleanly closes the connection thus insulating the user from
all the details of the low-level interface such as LDAP Lisp objects
@pxref{The Low-Level LDAP API}

@defun ldap-search filter &optional host attributes attrsonly
Perform an LDAP search.
@var{filter} is the search filter @pxref{Syntax of Search Filters}
@var{host} is the LDAP host on which to perform the search
@var{attributes} is the specific attributes to retrieve, @code{nil} means 
retrieve all
@var{attrsonly} if non-@code{nil} retrieves the attributes only without 
their associated values.
Additional search parameters can be specified through 
@code{ldap-host-parameters-alist}.
@end defun

@node The Low-Level LDAP API,  , The High-Level LDAP API, XEmacs LDAP API
@comment  node-name,  next,  previous,  up
@subsection The Low-Level LDAP API

@menu
* The LDAP Lisp Object::        
* Opening and Closing a LDAP Connection::  
* Searching on a LDAP Server (Low-level)::  
@end menu

@node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
@comment  node-name,  next,  previous,  up
@subsubsection The LDAP Lisp Object

An internal built-in @code{ldap} lisp object represents a LDAP
connection.

@defun ldapp object
This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
@end defun

@defun ldap-host ldap
Return the server host of the connection represented by @var{ldap}
@end defun

@defun ldap-live-p ldap
Return non-@code{nil} if @var{ldap} is an active LDAP connection
@end defun


@node Opening and Closing a LDAP Connection, Searching on a LDAP Server (Low-level), The LDAP Lisp Object, The Low-Level LDAP API
@comment  node-name,  next,  previous,  up
@subsubsection Opening and Closing a LDAP Connection

@defun ldap-open host &optional plist
Open a LDAP connection to @var{host}.
@var{plist} is a property list containing additional parameters for the connection.
Valid keys in that list are:
@table @code
@item port
The TCP port to use for the connection if different from
@code{ldap-default-port} or the library builtin value
@item auth
The authentication method to use, possible values depend on the LDAP
library XEmacs was compiled with, they may include @code{simple},
@code{krbv41} and @code{krbv42}.
@item binddn
The distinguished name of the user to bind as.  This may look like
@samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
@item passwd
The password to use for authentication.
@item deref
The dereference policy is one of the symbols @code{never},
@code{always}, @code{search} or @code{find} and defines how aliases are
dereferenced.
@table @code
@item never
Aliases are never dereferenced
@item always
Aliases are always dereferenced
@item search
Aliases are dereferenced when searching
@item find
Aliases are dereferenced when locating the base object for the search
@end table
The default is @code{never}.
@item timelimit
The timeout limit for the connection in seconds.
@item sizelimit
The maximum number of matches to return for searches performed on this connection.
@end table
@end defun

@defun ldap-close ldap
Close the connection represented by @var{ldap}
@end defun


@node Searching on a LDAP Server (Low-level),  , Opening and Closing a LDAP Connection, The Low-Level LDAP API
@comment  node-name,  next,  previous,  up
@subsubsection Searching on a LDAP Server (Low-level)

@code{ldap-search-internal} is the low-level primitive to perform a
search on a LDAP server.  It works directly on an open LDAP connection
thus requiring a preliminary call to @code{ldap-open}.  Multiple
searches can be made on the same connection, then the session must be
closed with @code{ldap-close}.


@defun ldap-search-internal ldap filter base scope attrs attrsonly
Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
@var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
@var{base} is the distinguished name at which to start the search.
@var{scope} is one of the symbols @code{base}, @code{onelevel} or
@code{subtree} indicating the scope of the search limited to a base
object, to a single level or to the whole subtree.  The default is
@code{subtree}.
@code{attrs} is a list of strings indicating which attributes to retrieve
for each matching entry. If @code{nil} all available attributes are returned.
If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
their associated values
The function returns a list of matching entries.  Each entry being itself
an alist of attribute/values.
@end defun





@node Syntax of Search Filters,  , XEmacs LDAP API, LDAP Support
@comment  node-name,  next,  previous,  up
@section Syntax of Search Filters

LDAP search functions use RFC1558 syntax to describe the search filter.
In that syntax simple filters have the form:

@example
(<attr> <filtertype> <value>)
@end example

@code{<attr>} is an attribute name such as @code{cn} for Common Name,
@code{o} for Organization, etc...

@code{<value>} is the corresponding value.  This is generally an exact
string but may also contain @code{*} characters as wildcards

@code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which 
respectively describe equality, approximate equality, inferiority and
superiority. 

Thus @code{(cn=John Smith)} matches all records having a canonical name
equal to John Smith.

A special case is the presence filter @code{(<attr>=*} which matches
records containing a particular attribute.  For instance @code{(mail=*)}
matches all records containing a @code{mail} attribute.

Simple filters can be connected together with the logical operators
@code{&}, @code{|} and @code{!} which stand for the usual and, or and
not operators.

@code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
matches records of class @code{Person} containing a @code{mail}
attribute and corresponding to people whose last name is @code{Smith} or 
whose first name is @code{John}.