2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1998 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/ldap.info
6 @node LDAP Support, Internationalization, ToolTalk Support, top
10 XEmacs can be linked with a LDAP client library to provide Elisp primitives
11 to access directory servers using the Lightweight Directory Access Protocol.
14 * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
15 * XEmacs LDAP API:: Lisp access to LDAP functions
16 * Syntax of Search Filters:: A brief summary of RFC 1558
19 @node Building XEmacs with LDAP support, XEmacs LDAP API, LDAP Support, LDAP Support
20 @comment node-name, next, previous, up
21 @section Building XEmacs with LDAP support
23 LDAP support must be added to XEmacs at build time since it requires
24 linking to an external LDAP client library. As of 21.2, XEmacs has been
25 successfully built and tested with
28 @item OpenLDAP 1.0.3 (@url{http://www.openldap.org/})
29 @item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
30 @item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
33 Other libraries conforming to RFC 1823 will probably work also but may
34 require some minor tweaking at C level.
36 The standard XEmacs configure script autodetects an installed LDAP
37 library provided the library itself and the corresponding header files
38 can be found in the library and include paths. A successful detection
39 will be signalled in the final output of the configure script.
43 @node XEmacs LDAP API, Syntax of Search Filters, Building XEmacs with LDAP support, LDAP Support
44 @comment node-name, next, previous, up
45 @section XEmacs LDAP API
47 XEmacs LDAP API consists of two layers: a low-level layer which tries
48 to stay as close as possible to the C API (where practical) and a
49 higher-level layer which provides more convenient primitives to
52 As of XEmacs 21.0, only interfaces to basic LDAP search functions are
53 provided, broader support is planned in future versions.
56 * LDAP Variables:: Lisp variables related to LDAP
57 * The High-Level LDAP API:: High-level LDAP lisp functions
58 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
62 @node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
63 @comment node-name, next, previous, up
64 @subsection LDAP Variables
66 @defvar ldap-default-host
67 The default LDAP server hostname.
68 A TCP port number can be appended to that name using a colon as
72 @defvar ldap-default-port
73 Default TCP port for LDAP connections.
74 Initialized from the LDAP library. Default value is 389.
77 @defvar ldap-default-base
78 Default base for LDAP searches.
79 This is a string using the syntax of RFC 1779.
80 For instance, "o¬ME, cÿ" limits the search to the
81 Acme organization in the United States.
84 @defvar ldap-host-parameters-alist
85 An alist of per host options for LDAP transactions.
86 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
87 @var{host} is the name of an LDAP server. A TCP port number can be
88 appended to that name using a colon as a separator.
89 @var{propn} and @var{valn} are
90 property/value pairs describing parameters for the server. Valid
94 The distinguished name of the user to bind as. This may look like
95 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
97 The password to use for authentication.
99 The authentication method to use, possible values depend on the LDAP
100 library XEmacs was compiled with, they may include @code{simple},
101 @code{krbv41} and @code{krbv42}.
103 The base for the search. This may look like @samp{cÿ, o¬me}, see
104 RFC 1779 for syntax details.
106 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
107 indicating the scope of the search limited to a base
108 object, to a single level or to the whole subtree.
110 The dereference policy is one of the symbols @code{never},
111 @code{always}, @code{search} or @code{find} and defines how aliases are
115 Aliases are never dereferenced
117 Aliases are always dereferenced
119 Aliases are dereferenced when searching
121 Aliases are dereferenced when locating the base object for the search
124 The timeout limit for the connection in seconds.
126 The maximum number of matches to return for searches performed on this connection.
132 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
133 @comment node-name, next, previous, up
134 @subsection The High-Level LDAP API
136 As of this writing the high-level Lisp LDAP API only provides for LDAP
137 searches. Further support is planned in the future.
139 The @code{ldap-search} function provides the most convenient interface
140 to perform LDAP searches. It opens a connection to a host, performs the
141 query and cleanly closes the connection thus insulating the user from
142 all the details of the low-level interface such as LDAP Lisp objects
143 @pxref{The Low-Level LDAP API}
145 @defun ldap-search filter &optional host attributes attrsonly
146 Perform an LDAP search.
147 @var{filter} is the search filter @pxref{Syntax of Search Filters}
148 @var{host} is the LDAP host on which to perform the search
149 @var{attributes} is the specific attributes to retrieve, @code{nil} means
151 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
152 their associated values.
153 Additional search parameters can be specified through
154 @code{ldap-host-parameters-alist}.
157 @node The Low-Level LDAP API, , The High-Level LDAP API, XEmacs LDAP API
158 @comment node-name, next, previous, up
159 @subsection The Low-Level LDAP API
162 * The LDAP Lisp Object::
163 * Opening and Closing a LDAP Connection::
164 * Searching on a LDAP Server (Low-level)::
167 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
168 @comment node-name, next, previous, up
169 @subsubsection The LDAP Lisp Object
171 An internal built-in @code{ldap} lisp object represents a LDAP
175 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
178 @defun ldap-host ldap
179 Return the server host of the connection represented by @var{ldap}
182 @defun ldap-live-p ldap
183 Return non-@code{nil} if @var{ldap} is an active LDAP connection
187 @node Opening and Closing a LDAP Connection, Searching on a LDAP Server (Low-level), The LDAP Lisp Object, The Low-Level LDAP API
188 @comment node-name, next, previous, up
189 @subsubsection Opening and Closing a LDAP Connection
191 @defun ldap-open host &optional plist
192 Open a LDAP connection to @var{host}.
193 @var{plist} is a property list containing additional parameters for the connection.
194 Valid keys in that list are:
197 The TCP port to use for the connection if different from
198 @code{ldap-default-port} or the library builtin value
200 The authentication method to use, possible values depend on the LDAP
201 library XEmacs was compiled with, they may include @code{simple},
202 @code{krbv41} and @code{krbv42}.
204 The distinguished name of the user to bind as. This may look like
205 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
207 The password to use for authentication.
209 The dereference policy is one of the symbols @code{never},
210 @code{always}, @code{search} or @code{find} and defines how aliases are
214 Aliases are never dereferenced
216 Aliases are always dereferenced
218 Aliases are dereferenced when searching
220 Aliases are dereferenced when locating the base object for the search
222 The default is @code{never}.
224 The timeout limit for the connection in seconds.
226 The maximum number of matches to return for searches performed on this connection.
230 @defun ldap-close ldap
231 Close the connection represented by @var{ldap}
235 @node Searching on a LDAP Server (Low-level), , Opening and Closing a LDAP Connection, The Low-Level LDAP API
236 @comment node-name, next, previous, up
237 @subsubsection Searching on a LDAP Server (Low-level)
239 @code{ldap-search-internal} is the low-level primitive to perform a
240 search on a LDAP server. It works directly on an open LDAP connection
241 thus requiring a preliminary call to @code{ldap-open}. Multiple
242 searches can be made on the same connection, then the session must be
243 closed with @code{ldap-close}.
246 @defun ldap-search-internal ldap filter base scope attrs attrsonly
247 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
248 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
249 @var{base} is the distinguished name at which to start the search.
250 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
251 @code{subtree} indicating the scope of the search limited to a base
252 object, to a single level or to the whole subtree. The default is
254 @code{attrs} is a list of strings indicating which attributes to retrieve
255 for each matching entry. If @code{nil} all available attributes are returned.
256 If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
257 their associated values
258 The function returns a list of matching entries. Each entry being itself
259 an alist of attribute/values.
266 @node Syntax of Search Filters, , XEmacs LDAP API, LDAP Support
267 @comment node-name, next, previous, up
268 @section Syntax of Search Filters
270 LDAP search functions use RFC1558 syntax to describe the search filter.
271 In that syntax simple filters have the form:
274 (<attr> <filtertype> <value>)
277 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
278 @code{o} for Organization, etc...
280 @code{<value>} is the corresponding value. This is generally an exact
281 string but may also contain @code{*} characters as wildcards
283 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
284 respectively describe equality, approximate equality, inferiority and
287 Thus @code{(cn=John Smith)} matches all records having a canonical name
290 A special case is the presence filter @code{(<attr>=*} which matches
291 records containing a particular attribute. For instance @code{(mail=*)}
292 matches all records containing a @code{mail} attribute.
294 Simple filters can be connected together with the logical operators
295 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
298 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
299 matches records of class @code{Person} containing a @code{mail}
300 attribute and corresponding to people whose last name is @code{Smith} or
301 whose first name is @code{John}.