]> git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_disptmpl.3
merged with autoconf branch
[openldap] / doc / man / man3 / ldap_disptmpl.3
1 .TH LDAP_DISPTMPL 3 "22 September 1998" "OpenLDAP LDVERSION"
2 .SH NAME
3 ldap_init_templates, ldap_init_templates_buf, ldap_free_templates, ldap_first_disptmpl, ldap_next_disptmpl, ldap_oc2template, ldap_tmplattrs, ldap_first_tmplrow, ldap_next_tmplrow, ldap_first_tmplcol, ldap_next_tmplcol, \- LDAP display template routines
4 .SH SYNOPSIS
5 .nf
6 .ft B
7 #include <disptmpl.h>
8 .ft
9 .LP
10 .ft B
11 int ldap_init_templates( file, tmpllistp )
12 .ft
13 char                    *file;
14 struct ldap_disptmpl    **tmpllistp;
15 .LP
16 .ft B
17 int ldap_init_templates_buf( buf, buflen, tmpllistp )
18 .ft
19 char                    *buf;
20 unsigned long           len;
21 struct ldap_disptmpl    **tmpllistp;
22 .LP
23 .ft B
24 void ldap_free_templates( tmpllist )
25 .ft
26 struct ldap_disptmpl    *tmpllist;
27 .LP
28 .ft B
29 struct ldap_disptmpl *ldap_first_disptmpl( tmpllist )
30 .ft
31 struct ldap_disptmpl    *tmpllist;
32 .LP
33 .ft B
34 struct ldap_disptmpl *ldap_next_disptmpl( tmpllist, tmpl )
35 .ft
36 struct ldap_disptmpl    *tmpllist;
37 struct ldap_disptmpl    *tmpl;
38 .LP
39 .ft B
40 struct ldap_disptmpl *ldap_oc2template( oclist, tmpllist )
41 .ft
42 char                    **oclist;
43 struct ldap_disptmpl    *tmpllist;
44 .LP
45 .ft B
46 struct ldap_disptmpl *ldap_name2template( name, tmpllist )
47 .ft
48 char                    *name;
49 struct ldap_disptmpl    *tmpllist;
50 .LP
51 .ft B
52 char **ldap_tmplattrs( tmpl, includeattrs, exclude, syntaxmask )
53 .ft
54 struct ldap_disptmpl    *tmpl;
55 char                    **includeattrs;
56 int                     exclude;
57 unsigned long           syntaxmask;
58 .LP
59 .ft B
60 struct ldap_tmplitem *ldap_first_tmplrow( tmpl )
61 .ft
62 struct ldap_disptmpl    *tmpl;
63 .LP
64 .ft B
65 struct ldap_tmplitem *ldap_next_tmplrow( tmpl, row )
66 .ft
67 struct ldap_disptmpl    *tmpl;
68 struct ldap_tmplitem    *row;
69 .LP
70 .ft B
71 struct ldap_tmplitem *ldap_first_tmplcol( tmpl, row )
72 .ft
73 struct ldap_disptmpl    *tmpl;
74 struct ldap_tmplitem    *row;
75 .LP
76 .ft B
77 struct ldap_tmplitem *ldap_next_tmplcol( tmpl, row, col )
78 .ft
79 struct ldap_disptmpl    *tmpl;
80 struct ldap_tmplitem    *row;
81 struct ldap_tmplitem    *col;
82 .fi
83 .SH DESCRIPTION
84 These functions provide a standard way to access LDAP entry display
85 templates.  Entry display templates provide a standard way for LDAP
86 applications to display directory entries.  The general idea is that it
87 is possible to map the list of object class values present in an entry
88 to an appropriate display template.  Display templates are defined in a
89 configuration file (see ldaptemplates.conf(5)).  Each display template
90 contains a pre-determined list of items, where each item generally
91 corresponds to an attribute to be displayed.  The items contain
92 information and flags that the caller can use to display the attribute and
93 values in a reasonable fashion.  Each item has a syntaxid, which are
94 described in the SYNTAX IDS section below.  The ldap_entry2text(3)
95 routines use the display template functions and produce text output.
96 .LP
97 ldap_init_templates() reads a sequence of templates from a valid LDAP
98 template configuration file (see ldaptemplates.conf(5))
99 .I Zero
100 is returned upon success, and
101 .I tmpllistp
102 is set to point to a list of templates.  Each member of the list is an
103 ldap_disptmpl structure (defined below in the DISPTMPL STRUCTURE ELEMENTS
104 section).
105 .LP
106 .LP
107 ldap_init_templates_buf() reads a sequence of templates from
108 .I buf
109 (whose size is
110 .I buflen).
111 .I buf
112 should point to the data in the format defined for an LDAP template
113 configuration file (see ldaptemplates.conf(5))
114 .I Zero
115 is returned upon success, and
116 .I tmpllistp
117 is set to point to a list of templates.
118 .LP
119 The
120 .B LDAP_SET_DISPTMPL_APPDATA()
121 macro is used to set the value of the dt_appdata field in an ldap_disptmpl
122 structure.  This field is reserved for the calling application to use; it
123 is not used internally.
124 .LP
125 The
126 .B LDAP_GET_DISPTMPL_APPDATA()
127 macro is used to retrieve the value in the dt_appdata field.
128 .LP
129 The
130 .B LDAP_IS_DISPTMPL_OPTION_SET()
131 macro is used to test a ldap_disptmpl structure for the existence of a
132 template option.  The options currently defined are:
133 .B LDAP_DTMPL_OPT_ADDABLE
134 (it is appropriate to allow entries of this type to be added),
135 .B LDAP_DTMPL_OPT_ALLOWMODRDN
136 (it is appropriate to offer the "modify rdn" operation),
137 .B LDAP_DTMPL_OPT_ALTVIEW
138 (this template is merely an alternate view of another template, typically
139 used for templates pointed to be an LDAP_SYN_LINKACTION item).
140 .LP
141 ldap_free_templates() disposes of the templates allocated by
142 ldap_init_templates().
143 .LP
144 ldap_first_disptmpl() returns the first template in the list
145 .I tmpllist.
146 The
147 .I tmpllist
148 is typically obtained by calling ldap_init_templates().
149 .LP
150 ldap_next_disptmpl() returns the template after
151 .I tmpl
152 in the template list
153 .I tmpllist.  A
154 .SM NULL
155 pointer is returned if
156 .I tmpl
157 is the last template in the list.
158 .LP
159 ldap_oc2template() searches
160 .I tmpllist
161 for the best template to use to display an entry that has a specific
162 set of objectClass values.
163 .I oclist
164 should be a null-terminated array of strings that contains the values
165 of the objectClass attribute of the entry.  A pointer to the first
166 template where all of the object classes listed in one of the
167 template's dt_oclist elements are contained in
168 .I oclist
169 is returned.  A
170 .B NULL
171 pointer is returned if no appropriate template is found.
172 .LP
173 ldap_tmplattrs() returns a null-terminated array that contains the
174 names of attributes that need to be retrieved if the template
175 .I tmpl
176 is to be used to display an entry.  The attribute list should be freed
177 using ldap_value_free().  The
178 .I includeattrs
179 parameter contains a null-terminated array of attributes that should
180 always be included (it may be
181 .B NULL
182 if no extra attributes are required).  If
183 .I syntaxmask
184 is non-zero, it is used to restrict the attribute set returned.  If
185 .I exclude
186 is zero, only attributes where the logical AND of the template item
187 syntax id and the
188 .I syntaxmask
189 is non-zero are included.  If
190 .I exclude
191 is non-zero, attributes where the logical AND of the template item
192 syntax id and the
193 .I  syntaxmask
194 is non-zero are excluded.
195 .LP
196 ldap_first_tmplrow() returns a pointer to the first row of items in
197 template
198 .I tmpl.
199 .LP
200 ldap_next_tmplrow() returns a pointer to the row that follows
201 .I row
202 in template
203 .I tmpl.
204 .LP
205 ldap_first_tmplcol() returns a pointer to the first item (in the first
206 column) of row
207 .I row
208 within template
209 .I tmpl.  A pointer to an ldap_tmplitem structure (defined below
210 in the TMPLITEM STRUCTURE ELEMENTS section) is returned.
211 .LP
212 The
213 .B LDAP_SET_TMPLITEM_APPDATA()
214 macro is used to set the value of the ti_appdata field in a ldap_tmplitem
215 structure.  This field is reserved for the calling application to use; it
216 is not used internally.
217 .LP
218 The
219 .B LDAP_GET_TMPLITEM_APPDATA()
220 macro is used to retrieve the value of the ti_appdata field.
221 .LP
222 The
223 .B LDAP_IS_TMPLITEM_OPTION_SET()
224 macro is used to test a ldap_tmplitem structure for the existence of an
225 item option.  The options currently defined are:
226 .B LDAP_DITEM_OPT_READONLY
227 (this attribute should not be modified),
228 .B LDAP_DITEM_OPT_SORTVALUES
229 (it makes sense to sort the values),
230 .B LDAP_DITEM_OPT_SINGLEVALUED
231 (this attribute can only hold a single value),
232 .B LDAP_DITEM_OPT_VALUEREQUIRED
233 (this attribute must contain at least one value),
234 .B LDAP_DITEM_OPT_HIDEIFEMPTY
235 (do not show this item if there are no values), and
236 .B LDAP_DITEM_OPT_HIDEIFFALSE
237 (for boolean attributes only:  hide this item if the value is FALSE).
238 .LP
239 ldap_next_tmplcol() returns a pointer to the item (column) that follows column
240 .I col
241 within row
242 .I row
243 of template
244 .I tmpl.
245 .SH DISPTMPL STRUCTURE ELEMENTS
246 The ldap_disptmpl structure is defined as:
247 .nf
248 .ft B
249 struct ldap_disptmpl {
250         char                    *dt_name;
251         char                    *dt_pluralname;
252         char                    *dt_iconname;
253         unsigned long           dt_options;
254         char                    *dt_authattrname;
255         char                    *dt_defrdnattrname;
256         char                    *dt_defaddlocation;
257         struct ldap_oclist      *dt_oclist;
258         struct ldap_adddeflist  *dt_adddeflist;
259         struct ldap_tmplitem    *dt_items;
260         void                    *dt_appdata;
261         struct ldap_disptmpl    *dt_next;
262 };
263 .ft
264 .fi
265 The dt_name member is the singular name of the template.  The dt_pluralname
266 is the plural name.  The dt_iconname member will contain the name of an
267 icon or other graphical element that can be used to depict entries that
268 correspond to this display template.  The dt_options contains options which
269 may be tested using the LDAP_IS_TMPLITEM_OPTION_SET() macro.
270 .LP
271 The dt_authattrname contains the name of the DN-syntax attribute whose
272 value(s) should be used to authenticate to make changes to an entry.  If
273 dt_authattrname is NULL, then authenticating as the entry itself is
274 appropriate.  The dt_defrdnattrname is the name of the attribute that
275 is normally used to name entries of this type, e.g., "cn" for person
276 entries.  The dt_defaddlocation is the distinguished name of an entry
277 below which new entries of this type are typically created (its value is
278 site-dependent).
279 .LP
280 dt_oclist is a pointer to a linked list of object class arrays, defined as:
281 .nf
282 .ft B
283 struct ldap_oclist {
284         char                    **oc_objclasses;
285         struct ldap_oclist      *oc_next;
286 };
287 .ft
288 .fi
289 These are used by the ldap_oc2template() routine.
290 .LP
291 dt_adddeflist is a pointer to a linked list of rules for defaulting the
292 values of attributes when new entries are created.  The ldap_adddeflist
293 structure is defined as:
294 .nf
295 .ft B
296 struct ldap_adddeflist {
297         int                     ad_source;
298         char                    *ad_attrname;
299         char                    *ad_value;
300         struct ldap_adddeflist  *ad_next;
301 };
302 .ft
303 .fi
304 The ad_attrname member contains the name of the attribute whose value this
305 rule sets.  If ad_source is 
306 .B LDAP_ADSRC_CONSTANTVALUE
307 then the ad_value member contains the (constant) value to use.
308 If  ad_source is
309 .B LDAP_ADSRC_ADDERSDN
310 then ad_value is ignored and the distinguished name of the person who
311 is adding the new entry is used as the default value for ad_attrname. 
312 .SH TMPLITEM STRUCTURE ELEMENTS
313 The ldap_tmplitem structure is defined as:
314 .nf
315 .ft B
316 struct ldap_tmplitem {
317         unsigned long           ti_syntaxid;
318         unsigned long           ti_options;
319         char                    *ti_attrname;
320         char                    *ti_label;
321         char                    **ti_args;
322         struct ldap_tmplitem    *ti_next_in_row;
323         struct ldap_tmplitem    *ti_next_in_col;
324         void                    *ti_appdata;
325 };
326 .ft
327 .fi
328 .SH SYNTAX IDS
329 Syntax ids are found in the ldap_tmplitem structure element ti_syntaxid,
330 and they can be used to determine how to display the values for the
331 attribute associated with an item.  The LDAP_GET_SYN_TYPE() macro can
332 be used to return a general type from a syntax id.  The five general types
333 currently defined are:
334 .B LDAP_SYN_TYPE_TEXT
335 (for attributes that are most appropriately shown as text),
336 .B LDAP_SYN_TYPE_IMAGE
337 (for JPEG or FAX format images),
338 .B LDAP_SYN_TYPE_BOOLEAN
339 (for boolean attributes),
340 .B LDAP_SYN_TYPE_BUTTON
341 (for attributes whose values are to be retrieved and display only upon 
342 request, e.g., in response to the press of a button, a JPEG image is
343 retrieved, decoded, and displayed), and
344 .B LDAP_SYN_TYPE_ACTION
345 (for special purpose actions such as "search for the entries where this
346 entry is listed in the seeAlso attribute").
347 .LP
348 The
349 .B LDAP_GET_SYN_OPTIONS
350 macro can be used to retrieve an unsigned long bitmap that defines
351 options.  The only currently defined option is
352 .B LDAP_SYN_OPT_DEFER,
353 which (if set) implies that the values for the attribute should not
354 be retrieved until requested.
355 .LP
356 There are sixteen distinct syntax ids currently defined.  These generally
357 correspond to one or more X.500 syntaxes.
358 .LP
359 .B LDAP_SYN_CASEIGNORESTR
360 is used for text attributes which are simple strings whose case is ignored
361 for comparison purposes.
362 .LP
363 .B LDAP_SYN_MULTILINESTR
364 is used for text attributes which consist of multiple lines,
365 e.g., postalAddress, homePostalAddress, multilineDescription, or any
366 attributes of syntax caseIgnoreList.
367 .LP
368 .B LDAP_SYN_RFC822ADDR
369 is used for case ignore string attributes that are RFC-822 conformant
370 mail addresses, e.g., mail.
371 .LP
372 .B LDAP_SYN_DN
373 is used for attributes with a Distinguished Name syntax, e.g., seeAlso.
374 .LP
375 .B LDAP_SYN_BOOLEAN
376 is used for attributes with a boolean syntax.
377 .LP
378 .B LDAP_SYN_JPEGIMAGE
379 is used for attributes with a jpeg syntax, e.g., jpegPhoto.
380 .LP
381 .B LDAP_SYN_JPEGBUTTON
382 is used to provide a button (or equivalent interface element) that can be
383 used to retrieve, decode, and display an attribute of jpeg syntax.
384 .LP
385 .B LDAP_SYN_FAXIMAGE
386 is used for attributes with a photo syntax, e.g., Photo.  These are
387 actually Group 3 Fax (T.4) format images.
388 .LP
389 .B LDAP_SYN_FAXBUTTON
390 is used to provide a button (or equivalent interface element) that can be
391 used to retrieve, decode, and display an attribute of photo syntax.
392 .LP
393 .B LDAP_SYN_AUDIOBUTTON
394 is used to provide a button (or equivalent interface element) that can be
395 used to retrieve and play an attribute of audio syntax.  Audio values are
396 in the "mu law" format, also known as "au" format.
397 .LP
398 .B LDAP_SYN_TIME
399 is used for attributes with the UTCTime syntax, e.g., lastModifiedTime.
400 The value(s) should be displayed in complete date and time fashion.
401 .LP
402 .B LDAP_SYN_DATE
403 is used for attributes with the UTCTime syntax, e.g., lastModifiedTime.
404 Only the date portion of the value(s) should be displayed.
405 .LP
406 .B LDAP_SYN_LABELEDURL
407 is used for labeledURL attributes.
408 .LP
409 .B LDAP_SYN_SEARCHACTION
410 is used to define a search that is used to retrieve related information.
411 If ti_attrname is not NULL, it is assumed to be a boolean attribute which
412 will cause no search to be performed if its value is FALSE.  The ti_args
413 structure member will have four strings in it:  ti_args[ 0 ] should be
414 the name of an attribute whose values are used to help construct a search
415 filter or "-dn" is the distinguished name of the entry being displayed
416 should be used, ti_args[ 1 ] should be a filter pattern where any occurrences
417 of "%v" are replaced with the value derived from ti_args[ 0 ], ti_args[ 2 ]
418 should be the name of an additional attribute to retrieve when performing
419 the search, and ti_args[ 3 ] should be a human-consumable name for that
420 attribute.  The ti_args[ 2 ] attribute is typically displayed along with
421 a list of distinguished names when multiple entries are returned by the
422 search.
423 .LP
424 .B LDAP_SYN_LINKACTION
425 is used to define a link to another template by name.  ti_args[ 0 ] will
426 contain the name of the display template to use.  The ldap_name2template()
427 routine can be used to obtain a pointer to the correct ldap_disptmpl structure.
428 .LP
429 .B LDAP_SYN_ADDDNACTION
430 and
431 .B LDAP_SYN_VERIFYDNACTION
432 are reserved as actions but currently undefined.
433 .SH ERRORS
434 The init template functions return
435 .B LDAP_TMPL_ERR_VERSION
436 if buf points to data that is newer than can be handled,
437 .B LDAP_TMPL_ERR_MEM
438 if there is a memory allocation problem,
439 .B LDAP_TMPL_ERR_SYNTAX
440 if there is a problem with the format of the templates buffer or file.
441 .B LDAP_TMPL_ERR_FILE
442 is returned by
443 .B ldap_init_templates
444 if the file cannot be read.   Other routines generally return
445 .B NULL
446 upon error.
447 .SH SEE ALSO
448 .BR ldap (3),
449 .BR ldap_entry2text (3),
450 .BR ldaptemplates.conf (5)
451 .SH ACKNOWLEDGEMENTS
452 .B      OpenLDAP
453 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
454 .B      OpenLDAP
455 is derived from University of Michigan LDAP 3.3 Release.