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