Mercurial > hg > xemacs-beta

comparison man/lispref/ldap.texi @ 298:70ad99077275 r21-0b47

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r21-0b47
author cvs
date Mon, 13 Aug 2007 10:39:40 +0200
parents
children 74fd4e045ea6
comparison
equal deleted inserted replaced
297:deca3c1083ac 298:70ad99077275
1 @c -*-texinfo-*-
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
7 @chapter LDAP Support
8 @cindex LDAP
9
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.
12
13 @menu
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
17 @end menu
18
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
22
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.0, XEmacs has been
25 successfully built and tested with
26
27 @itemize @bullet
28 @item University of Michigan's LDAP 3.3 (@url{http://www.umich.edu/~dirsvcs/ldap/})
29 @item LDAP SDK 1.0 from Netscape Corp. (@url{http://developer.netscape.com/})
30 @end itemize
31
32 Other libraries conforming to RFC 1823 will probably work also but may
33 require some minor tweaking at C level.
34
35 The standard XEmacs configure script autodetects an installed LDAP
36 library provided the library itself and the corresponding header files
37 can be found in the library and include paths. A successful detection
38 will be signalled in the final output of the configure script.
39
40
41
42 @node XEmacs LDAP API, Syntax of Search Filters, Building XEmacs with LDAP support, LDAP Support
43 @comment node-name, next, previous, up
44 @section XEmacs LDAP API
45
46 XEmacs LDAP API consists of two layers: a low-level layer which tries
47 to stay as close as possible to the C API (where practical) and a
48 higher-level layer which provides more convenient primitives to
49 effectively use LDAP.
50
51 As of XEmacs 21.0, only interfaces to basic LDAP search functions are
52 provided, broader support is planned in future versions.
53
54 @menu
55 * LDAP Variables:: Lisp variables related to LDAP
56 * The High-Level LDAP API:: High-level LDAP lisp functions
57 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
58 @end menu
59
60
61 @node LDAP Variables, The High-Level LDAP API, XEmacs LDAP API, XEmacs LDAP API
62 @comment node-name, next, previous, up
63 @subsection LDAP Variables
64
65 @defvar ldap-default-host
66 The default LDAP server
67 @end defvar
68
69 @defvar ldap-default-port
70 Default TCP port for LDAP connections.
71 Initialized from the LDAP library. Default value is 389.
72 @end defvar
73
74 @defvar ldap-default-base
75 Default base for LDAP searches.
76 This is a string using the syntax of RFC 1779.
77 For instance, "o¬ME, cÿ" limits the search to the
78 Acme organization in the United States.
79 @end defvar
80
81 @defvar ldap-host-parameters-alist
82 An alist of per host options for LDAP transactions.
83 The list elements look like @code{(HOST PROP1 VAL1 PROP2 VAL2 ...)}
84 @var{host} is the name of an LDAP server. @var{propn} and @var{valn} are
85 property/value pairs describing parameters for the server. Valid
86 properties:
87 @table @code
88 @item binddn
89 The distinguished name of the user to bind as. This may look like
90 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
91 @item passwd
92 The password to use for authentication.
93 @item auth
94 The authentication method to use, possible values depend on the LDAP
95 library XEmacs was compiled with, they may include @code{simple},
96 @code{krbv41} and @code{krbv42}.
97 @item base
98 The base for the search. This may look like @samp{cÿ, o¬me}, see
99 RFC 1779 for syntax details.
100 @item scope
101 One of the symbols @code{base}, @code{onelevel} or @code{subtree}
102 indicating the scope of the search limited to a base
103 object, to a single level or to the whole subtree.
104 @item deref
105 The dereference policy is one of the symbols @code{never},
106 @code{always}, @code{search} or @code{find} and defines how aliases are
107 dereferenced.
108 @table @code
109 @item never
110 Aliases are never dereferenced
111 @item always
112 Aliases are always dereferenced
113 @item search
114 Aliases are dereferenced when searching
115 @item find
116 Aliases are dereferenced when locating the base object for the search
117 @end table
118 @item timelimit
119 The timeout limit for the connection in seconds.
120 @item sizelimit
121 The maximum number of matches to return for searches performed on this connection.
122 @end table
123 @end defvar
124
125
126
127 @node The High-Level LDAP API, The Low-Level LDAP API, LDAP Variables, XEmacs LDAP API
128 @comment node-name, next, previous, up
129 @subsection The High-Level LDAP API
130
131 As of this writing the high-level Lisp LDAP API only provides for LDAP
132 searches. Further support is planned in the future.
133
134 The @code{ldap-search} function provides the most convenient interface
135 to perform LDAP searches. It opens a connection to a host, performs the
136 query and cleanly closes the connection thus insulating the user from
137 all the details of the low-level interface such as LDAP Lisp objects
138 @pxref{The Low-Level LDAP API}
139
140 @defun ldap-search filter &optional host attributes attrsonly
141 Perform an LDAP search.
142 @var{filter} is the search filter @pxref{Syntax of Search Filters}
143 @var{host} is the LDAP host on which to perform the search
144 @var{attributes} is the specific attributes to retrieve, @code{nil} means
145 retrieve all
146 @var{attrsonly} if non-@code{nil} retrieves the attributes only without
147 their associated values.
148 Additional search parameters can be specified through
149 @code{ldap-host-parameters-alist}.
150 @end defun
151
152 @node The Low-Level LDAP API, , The High-Level LDAP API, XEmacs LDAP API
153 @comment node-name, next, previous, up
154 @subsection The Low-Level LDAP API
155
156 @menu
157 * The LDAP Lisp Object::
158 * Opening and Closing a LDAP Connection::
159 * Searching on a LDAP Server (Low-level)::
160 @end menu
161
162 @node The LDAP Lisp Object, Opening and Closing a LDAP Connection, The Low-Level LDAP API, The Low-Level LDAP API
163 @comment node-name, next, previous, up
164 @subsubsection The LDAP Lisp Object
165
166 An internal built-in @code{ldap} lisp object represents a LDAP
167 connection.
168
169 @defun ldapp object
170 This function returns non-@code{nil} if @var{object} is a @code{ldap} object.
171 @end defun
172
173 @defun ldap-host ldap
174 Return the server host of the connection represented by @var{ldap}
175 @end defun
176
177 @defun ldap-live-p ldap
178 Return non-@code{nil} if @var{ldap} is an active LDAP connection
179 @end defun
180
181
182 @node Opening and Closing a LDAP Connection, Searching on a LDAP Server (Low-level), The LDAP Lisp Object, The Low-Level LDAP API
183 @comment node-name, next, previous, up
184 @subsubsection Opening and Closing a LDAP Connection
185
186 @defun ldap-open host &optional plist
187 Open a LDAP connection to @var{host}.
188 @var{plist} is a property list containing additional parameters for the connection.
189 Valid keys in that list are:
190 @table @code
191 @item port
192 The TCP port to use for the connection if different from
193 @code{ldap-default-port} or the library builtin value
194 @item auth
195 The authentication method to use, possible values depend on the LDAP
196 library XEmacs was compiled with, they may include @code{simple},
197 @code{krbv41} and @code{krbv42}.
198 @item binddn
199 The distinguished name of the user to bind as. This may look like
200 @samp{cÿ, o¬me, cnÿnny Bugs}, see RFC 1779 for details.
201 @item passwd
202 The password to use for authentication.
203 @item deref
204 The dereference policy is one of the symbols @code{never},
205 @code{always}, @code{search} or @code{find} and defines how aliases are
206 dereferenced.
207 @table @code
208 @item never
209 Aliases are never dereferenced
210 @item always
211 Aliases are always dereferenced
212 @item search
213 Aliases are dereferenced when searching
214 @item find
215 Aliases are dereferenced when locating the base object for the search
216 @end table
217 The default is @code{never}.
218 @item timelimit
219 The timeout limit for the connection in seconds.
220 @item sizelimit
221 The maximum number of matches to return for searches performed on this connection.
222 @end table
223 @end defun
224
225 @defun ldap-close ldap
226 Close the connection represented by @var{ldap}
227 @end defun
228
229
230 @node Searching on a LDAP Server (Low-level), , Opening and Closing a LDAP Connection, The Low-Level LDAP API
231 @comment node-name, next, previous, up
232 @subsubsection Searching on a LDAP Server (Low-level)
233
234 @code{ldap-search-internal} is the low-level primitive to perform a
235 search on a LDAP server. It works directly on an open LDAP connection
236 thus requiring a preliminary call to @code{ldap-open}. Multiple
237 searches can be made on the same connection, then the session must be
238 closed with @code{ldap-close}.
239
240
241 @defun ldap-search-internal ldap filter base scope attrs attrsonly
242 Perform a search on an open connection @var{ldap} created with @code{ldap-open}.
243 @var{filter} is a filter string for the search @pxref{Syntax of Search Filters}
244 @var{base} is the distinguished name at which to start the search.
245 @var{scope} is one of the symbols @code{base}, @code{onelevel} or
246 @code{subtree} indicating the scope of the search limited to a base
247 object, to a single level or to the whole subtree. The default is
248 @code{subtree}.
249 @code{attrs} is a list of strings indicating which attributes to retrieve
250 for each matching entry. If @code{nil} all available attributes are returned.
251 If @code{attrsonly} is non-@code{nil} then only the attributes are retrieved, not
252 their associated values
253 The function returns a list of matching entries. Each entry being itself
254 an alist of attribute/values.
255 @end defun
256
257
258
259
260
261 @node Syntax of Search Filters, , XEmacs LDAP API, LDAP Support
262 @comment node-name, next, previous, up
263 @section Syntax of Search Filters
264
265 LDAP search functions use RFC1558 syntax to describe the search filter.
266 In that syntax simple filters have the form:
267
268 @example
269 (<attr> <filtertype> <value>)
270 @end example
271
272 @code{<attr>} is an attribute name such as @code{cn} for Common Name,
273 @code{o} for Organization, etc...
274
275 @code{<value>} is the corresponding value. This is generally an exact
276 string but may also contain @code{*} characters as wildcards
277
278 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which
279 respectively describe equality, approximate equality, inferiority and
280 superiority.
281
282 Thus @code{(cn=John Smith)} matches all records having a canonical name
283 equal to John Smith.
284
285 A special case is the presence filter @code{(<attr>=*} which matches
286 records containing a particular attribute. For instance @code{(mail=*)}
287 matches all records containing a @code{mail} attribute.
288
289 Simple filters can be connected together with the logical operators
290 @code{&}, @code{|} and @code{!} which stand for the usual and, or and
291 not operators.
292
293 @code{(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))}
294 matches records of class @code{Person} containing a @code{mail}
295 attribute and corresponding to people whose last name is @code{Smith} or
296 whose first name is @code{John}.
297
298
299