--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/ldap.texi	Mon Aug 13 10:39:40 2007 +0200
@@ -0,0 +1,299 @@
+@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.0, XEmacs has been
+successfully built and tested with
+
+@itemize @bullet
+@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
+@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. @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}.
+
+
+