Mercurial > hg > xemacs-beta
comparison man/lispref/ldap.texi @ 428:3ecd8885ac67 r21-2-22
Import from CVS: tag r21-2-22
author | cvs |
---|---|
date | Mon, 13 Aug 2007 11:28:15 +0200 |
parents | |
children | abe6d1db359e |
comparison
equal
deleted
inserted
replaced
427:0a0253eac470 | 428:3ecd8885ac67 |
---|---|
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.2, XEmacs has been | |
25 successfully built and tested with | |
26 | |
27 @itemize @bullet | |
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/}) | |
31 @end itemize | |
32 | |
33 Other libraries conforming to RFC 1823 will probably work also but may | |
34 require some minor tweaking at C level. | |
35 | |
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. | |
40 | |
41 | |
42 | |
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 | |
46 | |
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 | |
50 effectively use LDAP. | |
51 | |
52 As of XEmacs 21.0, only interfaces to basic LDAP search functions are | |
53 provided, broader support is planned in future versions. | |
54 | |
55 @menu | |
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 | |
59 @end menu | |
60 | |
61 | |
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 | |
65 | |
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 | |
69 a separator. | |
70 @end defvar | |
71 | |
72 @defvar ldap-default-port | |
73 Default TCP port for LDAP connections. | |
74 Initialized from the LDAP library. Default value is 389. | |
75 @end defvar | |
76 | |
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. | |
82 @end defvar | |
83 | |
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 | |
91 properties: | |
92 @table @code | |
93 @item binddn | |
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. | |
96 @item passwd | |
97 The password to use for authentication. | |
98 @item auth | |
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}. | |
102 @item base | |
103 The base for the search. This may look like @samp{cÿ, o¬me}, see | |
104 RFC 1779 for syntax details. | |
105 @item scope | |
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. | |
109 @item deref | |
110 The dereference policy is one of the symbols @code{never}, | |
111 @code{always}, @code{search} or @code{find} and defines how aliases are | |
112 dereferenced. | |
113 @table @code | |
114 @item never | |
115 Aliases are never dereferenced | |
116 @item always | |
117 Aliases are always dereferenced | |
118 @item search | |
119 Aliases are dereferenced when searching | |
120 @item find | |
121 Aliases are dereferenced when locating the base object for the search | |
122 @end table | |
123 @item timelimit | |
124 The timeout limit for the connection in seconds. | |
125 @item sizelimit | |
126 The maximum number of matches to return for searches performed on this connection. | |
127 @end table | |
128 @end defvar | |
129 | |
130 | |
131 | |
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 | |
135 | |
136 As of this writing the high-level Lisp LDAP API only provides for LDAP | |
137 searches. Further support is planned in the future. | |
138 | |
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} | |
144 | |
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 | |
150 retrieve all | |
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}. | |
155 @end defun | |
156 | |
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 | |
160 | |
161 @menu | |
162 * The LDAP Lisp Object:: | |
163 * Opening and Closing a LDAP Connection:: | |
164 * Searching on a LDAP Server (Low-level):: | |
165 @end menu | |
166 | |
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 | |
170 | |
171 An internal built-in @code{ldap} lisp object represents a LDAP | |
172 connection. | |
173 | |
174 @defun ldapp object | |
175 This function returns non-@code{nil} if @var{object} is a @code{ldap} object. | |
176 @end defun | |
177 | |
178 @defun ldap-host ldap | |
179 Return the server host of the connection represented by @var{ldap} | |
180 @end defun | |
181 | |
182 @defun ldap-live-p ldap | |
183 Return non-@code{nil} if @var{ldap} is an active LDAP connection | |
184 @end defun | |
185 | |
186 | |
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 | |
190 | |
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: | |
195 @table @code | |
196 @item port | |
197 The TCP port to use for the connection if different from | |
198 @code{ldap-default-port} or the library builtin value | |
199 @item auth | |
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}. | |
203 @item binddn | |
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. | |
206 @item passwd | |
207 The password to use for authentication. | |
208 @item deref | |
209 The dereference policy is one of the symbols @code{never}, | |
210 @code{always}, @code{search} or @code{find} and defines how aliases are | |
211 dereferenced. | |
212 @table @code | |
213 @item never | |
214 Aliases are never dereferenced | |
215 @item always | |
216 Aliases are always dereferenced | |
217 @item search | |
218 Aliases are dereferenced when searching | |
219 @item find | |
220 Aliases are dereferenced when locating the base object for the search | |
221 @end table | |
222 The default is @code{never}. | |
223 @item timelimit | |
224 The timeout limit for the connection in seconds. | |
225 @item sizelimit | |
226 The maximum number of matches to return for searches performed on this connection. | |
227 @end table | |
228 @end defun | |
229 | |
230 @defun ldap-close ldap | |
231 Close the connection represented by @var{ldap} | |
232 @end defun | |
233 | |
234 | |
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) | |
238 | |
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}. | |
244 | |
245 | |
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 | |
253 @code{subtree}. | |
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. | |
260 @end defun | |
261 | |
262 | |
263 | |
264 | |
265 | |
266 @node Syntax of Search Filters, , XEmacs LDAP API, LDAP Support | |
267 @comment node-name, next, previous, up | |
268 @section Syntax of Search Filters | |
269 | |
270 LDAP search functions use RFC1558 syntax to describe the search filter. | |
271 In that syntax simple filters have the form: | |
272 | |
273 @example | |
274 (<attr> <filtertype> <value>) | |
275 @end example | |
276 | |
277 @code{<attr>} is an attribute name such as @code{cn} for Common Name, | |
278 @code{o} for Organization, etc... | |
279 | |
280 @code{<value>} is the corresponding value. This is generally an exact | |
281 string but may also contain @code{*} characters as wildcards | |
282 | |
283 @code{filtertype} is one @code{=} @code{~=}, @code{<=}, @code{>=} which | |
284 respectively describe equality, approximate equality, inferiority and | |
285 superiority. | |
286 | |
287 Thus @code{(cn=John Smith)} matches all records having a canonical name | |
288 equal to John Smith. | |
289 | |
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. | |
293 | |
294 Simple filters can be connected together with the logical operators | |
295 @code{&}, @code{|} and @code{!} which stand for the usual and, or and | |
296 not operators. | |
297 | |
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}. | |
302 | |
303 | |
304 |