1ldap_disptmpl(3LDAP)        LDAP Library Functions        ldap_disptmpl(3LDAP)
2
3
4

NAME

6       ldap_disptmpl,       ldap_init_templates,      ldap_init_templates_buf,
7       ldap_free_templates,      ldap_first_disptmpl,      ldap_next_disptmpl,
8       ldap_oc2template,          ldap_name2template,          ldap_tmplattrs,
9       ldap_first_tmplrow,       ldap_next_tmplrow,        ldap_first_tmplcol,
10       ldap_next_tmplcol - LDAP display template functions
11

SYNOPSIS

13       cc[ flag... ] file... -lldap[ library... ]
14       #include <lber.h>
15       #include <ldap.h>
16
17       int ldap_init_templates(char *file, struct ldap_disptmpl **tmpllistp);
18
19
20       int ldap_init_templates_buf(char *buf, unsigned long len,
21            struct ldap_disptmpl **tmpllistp);
22
23
24       void ldap_free_templates(struct ldap_disptmpl *tmpllist);
25
26
27       struct ldap_disptmpl *ldap_first_disptmpl
28            (struct ldap_disptmpl *tmpllist);
29
30
31       struct ldap_disptmpl *ldap_next_disptmpl
32            (struct ldap_disptmpl *tmpllist,struct ldap_disptmpl *tmpl);
33
34
35       struct ldap_disptmpl *ldap_oc2template (char **oclist,
36            struct ldap_disptmpl *tmpllist);
37
38
39       struct ldap_disptmpl *ldap_name2template (char *name,
40            struct ldap_disptmpl *tmpllist);
41
42
43       char **ldap_tmplattrs(struct ldap_disptmpl *tmpl, char **includeattrs,
44            int exclude;, unsigned long syntaxmask);
45
46
47       struct ldap_tmplitem *ldap_first_tmplrow(struct ldap_disptmpl *tmpl);
48
49
50       struct ldap_tmplitem *ldap_next_tmplrow(struct ldap_disptmpl *tmpl,
51            struct ldap_tmplitem *row);
52
53
54       struct ldap_tmplitem *ldap_first_tmplcol(struct ldap_disptmpl *tmpl,
55            struct ldap_tmplitem *row, struct ldap_tmplitem *col);
56
57
58       struct ldap_tmplitem *ldap_next_tmplcol(struct ldap_disptmpl *tmpl,
59            struct ldap_tmplitem *row, struct ldap_tmplitem *col);
60
61

DESCRIPTION

63       These  functions  provide  a  standard way to access LDAP entry display
64       templates.  Entry display templates provide a  standard  way  for  LDAP
65       applications to display directory entries.  The general idea is that it
66       is possible to map the list of object class values present in an  entry
67       to an appropriate display template.  Display templates are defined in a
68       configuration file. See  ldaptemplates.conf(4). Each  display  template
69       contains a pre-determined list of items, where each item generally cor‐
70       responds to an attribute to be displayed.  The items  contain  informa‐
71       tion  and  flags  that  the caller can use to display the attribute and
72       values in a reasonable fashion.  Each item has a  syntaxid,  which  are
73       described  in the SYNTAX IDS section below.  The ldap_entry2text(3LDAP)
74       functions use the display template functions and produce text output.
75
76
77       ldap_init_templates() reads a sequence of templates from a  valid  LDAP
78       template configuration file (see  ldaptemplates.conf(4)). Upon success,
79       0 is returned, and tmpllistp is set to point to a  list  of  templates.
80       Each member of the list is an ldap_disptmpl structure (defined below in
81       the DISPTMPL Structure Elements section).
82
83
84       ldap_init_templates_buf() reads a sequence of templates from buf (whose
85       size is buflen). buf should point to the data in the format defined for
86       an LDAP template configuration file (see  ldaptemplates.conf(4)).  Upon
87       success,   0  is  returned,  and tmpllistp is set to point to a list of
88       templates.
89
90
91       The LDAP_SET_DISPTMPL_APPDATA() macro is used to set the value  of  the
92       dt_appdata  field  in  an   ldap_disptmpl  structure.   This  field  is
93       reserved for the calling application to use; it is not used internally.
94
95
96       The LDAP_GET_DISPTMPL_APPDATA() macro is used to retrieve the value  in
97       the  dt_appdata field.
98
99
100       The   LDAP_IS_DISPTMPL_OPTION_SET()   macro   is   used   to   test   a
101       ldap_disptmpl structure for the existence of a  template  option.   The
102       options  currently defined are: LDAP_DTMPL_OPT_ADDABLE (it is appropri‐
103       ate to allow entries of this type to be  added),  LDAP_DTMPL_OPT_ALLOW‐
104       MODRDN   (it  is  appropriate  to  offer  the  "modify  rdn"operation),
105       LDAP_DTMPL_OPT_ALTVIEW (this template is merely an  alternate  view  of
106       another  template,  typically  used  for  templates  pointed  to  be an
107       LDAP_SYN_LINKACTION item).
108
109
110       ldap_free_templates()  disposes   of   the   templates   allocated   by
111       ldap_init_templates().
112
113
114       ldap_first_disptmpl()  returns the first template in the list tmpllist.
115       The tmpllist is typically obtained by calling  ldap_init_templates() .
116
117
118       ldap_next_disptmpl() returns the template after tmpl  in  the  template
119       list  tmpllist. A NULL pointer is returned if tmpl is the last template
120       in the list.
121
122
123       ldap_oc2template() searches tmpllist for the best template  to  use  to
124       display an entry that has a specific set of  objectClass values. oclist
125       should be a null-terminated array of strings that contains  the  values
126       of  the   objectClass  attribute  of the entry.  A pointer to the first
127       template where all of the object classes listed  in  one  of  the  tem‐
128       plate's   dt_oclist  elements  are  contained in oclist is returned.  A
129       NULL pointer is returned if no appropriate template is found.
130
131
132       ldap_tmplattrs() returns a  null-terminated  array  that  contains  the
133       names  of  attributes that need to be retrieved if the template tmpl is
134       to be used to display an entry.  The attribute  list  should  be  freed
135       using   ldap_value_free().  The includeattrs parameter contains a null-
136       terminated array of attributes that should always be included  (it  may
137       be  NULL  if  no extra attributes are required).  If syntaxmask is non-
138       zero, it is used to restrict the attribute set returned.  If exclude is
139       zero,  only attributes where the logical  AND of the template item syn‐
140       tax id and the syntaxmask is non-zero are included.  If exclude is non-
141       zero,  attributes where the logical  AND of the template item syntax id
142       and the syntaxmask is non-zero are excluded.
143
144
145       ldap_first_tmplrow() returns a pointer to the first  row  of  items  in
146       template tmpl.
147
148
149       ldap_next_tmplrow()  returns  a  pointer to the row that follows row in
150       template tmpl.
151
152
153       ldap_first_tmplcol() returns a pointer to the first item (in the  first
154       column) of row row within template tmpl. A pointer to an  ldap_tmplitem
155       structure (defined below in the TMPLITEM Structure Elements section) is
156       returned.
157
158
159       The  LDAP_SET_TMPLITEM_APPDATA()  macro is used to set the value of the
160       ti_appdata field in a  ldap_tmplitem structure.  This field is reserved
161       for the calling application to use; it is not used internally.
162
163
164       The  LDAP_GET_TMPLITEM_APPDATA() macro is used to retrieve the value of
165       the  ti_appdata field.
166
167
168       The   LDAP_IS_TMPLITEM_OPTION_SET()   macro   is   used   to   test   a
169       ldap_tmplitem  structure  for  the  existence  of  an item option.  The
170       options currently defined are: LDAP_DITEM_OPT_READONLY (this  attribute
171       should  not  be modified), LDAP_DITEM_OPT_SORTVALUES (it makes sense to
172       sort the values), LDAP_DITEM_OPT_SINGLEVALUED (this attribute can  only
173       hold a single value), LDAP_DITEM_OPT_VALUEREQUIRED (this attribute must
174       contain at least one value), LDAP_DITEM_OPT_HIDEIFEMPTY  (do  not  show
175       this  item if there are no values), and LDAP_DITEM_OPT_HIDEIFFALSE (for
176       boolean attributes only:  hide this item if the value  is FALSE).
177
178
179       ldap_next_tmplcol() returns a pointer to the item (column) that follows
180       column col within row row of template tmpl.
181
182   DISPTMPL Structure Elements
183       The  ldap_disptmpl structure is defined as:
184
185         struct ldap_disptmpl {
186              char                     *dt_name;
187              char           *dt_pluralname;
188              char                     *dt_iconname;
189              unsigned long            dt_options;
190              char                     *dt_authattrname;
191              char                     *dt_defrdnattrname;
192              char                     *dt_defaddlocation;
193              struct ldap_oclist  *dt_oclist;
194              struct ldap_adddeflist   *dt_adddeflist;
195              struct ldap_tmplitem     *dt_items;
196              void           *dt_appdata;
197              struct ldap_disptmpl     *dt_next;
198         };
199
200
201
202       The  dt_name member is the singular name of the template.  The  dt_plu‐
203       ralname is the plural name.  The  dt_iconname member will  contain  the
204       name  of  an icon or other graphical element that can be used to depict
205       entries that correspond to this display template.  The  dt_options con‐
206       tains     options     which     may     be     tested     using     the
207       LDAP_IS_TMPLITEM_OPTION_SET() macro.
208
209
210       The  dt_authattrname contains the name of the DN-syntax attribute whose
211       value(s)  should  be  used to authenticate to make changes to an entry.
212       If dt_authattrname is NULL, then authenticating as the entry itself  is
213       appropriate.  The   dt_defrdnattrname is the name of the attribute that
214       is normally used to name entries of this  type,  for  example,  "cn"for
215       person entries.  The  dt_defaddlocation is the distinguished name of an
216       entry below which new entries of this type are typically  created  (its
217       value is site-dependent).
218
219
220       dt_oclist is a pointer to a linked list of object class arrays, defined
221       as:
222
223         struct ldap_oclist {
224              char           **oc_objclasses;
225              struct ldap_oclist  *oc_next;
226         };
227
228
229
230       These are used by the  ldap_oc2template() function.
231
232
233       dt_adddeflist is a pointer to a linked list of rules for defaulting the
234       values  of  attributes  when new entries are created.  The  ldap_addde‐
235       flist structure is defined as:
236
237         struct ldap_adddeflist {
238              int            ad_source;
239              char           *ad_attrname;
240              char           *ad_value;
241              struct ldap_adddeflist   *ad_next;
242         };
243
244
245
246       The ad_attrname member contains the name of the attribute  whose  value
247       this  rule  sets.   If  ad_source is  LDAP_ADSRC_CONSTANTVALUE then the
248       ad_value member contains the (constant) value to use. If   ad_source is
249       LDAP_ADSRC_ADDERSDN then ad_value is ignored and the distinguished name
250       of the person who is adding the new entry is used as the default  value
251       for  ad_attrname.
252
253   TMPLITEM Structure Elements
254       The  ldap_tmplitem structure is defined as:
255
256         struct ldap_tmplitem {
257              unsigned long       ti_syntaxid;
258              unsigned long       ti_options;
259              char           *ti_attrname;
260              char           *ti_label;
261              char           **ti_args;
262              struct ldap_tmplitem     *ti_next_in_row;
263              struct ldap_tmplitem     *ti_next_in_col;
264              void           *ti_appdata;
265         };
266
267
268   Syntax IDs
269       Syntax  ids  are found in the  ldap_tmplitem structure element  ti_syn‐
270       taxid, and they can be used to determine how to display the values  for
271       the  attribute associated with an item.  The  LDAP_GET_SYN_TYPE() macro
272       can be used to return a general type from a syntax id.  The  five  gen‐
273       eral  types  currently  defined are: LDAP_SYN_TYPE_TEXT (for attributes
274       that are most appropriately shown as  text),  LDAP_SYN_TYPE_IMAGE  (for
275       JPEG   or   FAX  format  images),  LDAP_SYN_TYPE_BOOLEAN  (for  boolean
276       attributes), LDAP_SYN_TYPE_BUTTON (for attributes whose values  are  to
277       be  retrieved  and display only upon  request, for example, in response
278       to the press of a button, a JPEG image is retrieved, decoded, and  dis‐
279       played),  and LDAP_SYN_TYPE_ACTION (for special purpose actions such as
280       "search for the entries where this  entry  is  listed  in  the  seeAlso
281       attribute").
282
283
284       The LDAP_GET_SYN_OPTIONS macro can be used to retrieve an unsigned long
285       bitmap that defines options.  The  only  currently  defined  option  is
286       LDAP_SYN_OPT_DEFER,  which  (if  set)  implies  that the values for the
287       attribute should not be retrieved until requested.
288
289
290       There are sixteen distinct syntax ids currently defined.  These  gener‐
291       ally correspond to one or more X.500 syntaxes.
292
293
294       LDAP_SYN_CASEIGNORESTR  is  used  for  text attributes which are simple
295       strings whose case is ignored for comparison purposes.
296
297
298       LDAP_SYN_MULTILINESTR is used for text attributes which consist of mul‐
299       tiple  lines,  for  example,   postalAddress, homePostalAddress, multi‐
300       lineDescription, or any attributes of syntax  caseIgnoreList.
301
302
303       LDAP_SYN_RFC822ADDR is used for case ignore string attributes that  are
304       RFC-822 conformant mail addresses, for example, mail.
305
306
307       LDAP_SYN_DN  is  used  for attributes with a Distinguished Name syntax,
308       for example,  seeAlso.
309
310
311       LDAP_SYN_BOOLEAN is used for attributes with a boolean syntax.
312
313
314       LDAP_SYN_JPEGIMAGE is used for attributes with a jpeg syntax, for exam‐
315       ple, jpegPhoto.
316
317
318       LDAP_SYN_JPEGBUTTON  is  used to provide a button (or equivalent inter‐
319       face element) that can be used to  retrieve,  decode,  and  display  an
320       attribute of jpeg syntax.
321
322
323       LDAP_SYN_FAXIMAGE is used for attributes with a photo syntax, for exam‐
324       ple, Photo.  These are actually Group 3 Fax (T.4) format images.
325
326
327       LDAP_SYN_FAXBUTTON is used to provide a button (or equivalent interface
328       element) that can be used to retrieve, decode, and display an attribute
329       of photo syntax.
330
331
332       LDAP_SYN_AUDIOBUTTON is used to provide a button (or equivalent  inter‐
333       face  element)  that  can  be used to retrieve and play an attribute of
334       audio syntax.  Audio values are in the "mu law" format, also  known  as
335       "au" format.
336
337
338       LDAP_SYN_TIME is used for attributes with the UTCTime syntax, for exam‐
339       ple,  lastModifiedTime. The value(s) should be  displayed  in  complete
340       date and time fashion.
341
342
343       LDAP_SYN_DATE is used for attributes with the UTCTime syntax, for exam‐
344       ple,  lastModifiedTime. Only the date portion of the value(s) should be
345       displayed.
346
347
348       LDAP_SYN_LABELEDURL is used for  labeledURL attributes.
349
350
351       LDAP_SYN_SEARCHACTION  is  used  to  define  a  search  that is used to
352       retrieve related information.  If   ti_attrname  is  not  NULL,  it  is
353       assumed to be a boolean attribute which will cause no search to be per‐
354       formed if its value is  FALSE.   The   ti_args  structure  member  will
355       have  four  strings  in  it:  ti_args[  0  ]  should  be the name of an
356       attribute whose values are used to help construct a  search  filter  or
357       "-dn"  is the distinguished name of the entry being displayed should be
358       used,  ti_args[ 1 ] should be a filter pattern where any occurrences of
359       "%v"  are replaced with the value derived from  ti_args[ 0 ],  ti_args[
360       2 ] should be the name of an additional attribute to retrieve when per‐
361       forming the search, and  ti_args[ 3 ] should be a human-consumable name
362       for that attribute.  The  ti_args[ 2 ] attribute is typically displayed
363       along  with  a  list  of  distinguished names when multiple entries are
364       returned by the search.
365
366
367       LDAP_SYN_LINKACTION is used to define a link  to  another  template  by
368       name.    ti_args[  0 ] will contain the name of the display template to
369       use.  The  ldap_name2template()  function  can  be  used  to  obtain  a
370       pointer to the correct  ldap_disptmpl structure.
371
372
373       LDAP_SYN_ADDDNACTION   and   LDAP_SYN_VERIFYDNACTION  are  reserved  as
374       actions but currently undefined.
375

ERRORS

377       The init template functions return LDAP_TMPL_ERR_VERSION if  buf points
378       to  data  that is newer than can be handled, LDAP_TMPL_ERR_MEM if there
379       is a memory allocation problem,  LDAP_TMPL_ERR_SYNTAX  if  there  is  a
380       problem   with   the   format   of   the   templates  buffer  or  file.
381       LDAP_TMPL_ERR_FILE is returned by ldap_init_templates if the file  can‐
382       not be read.   Other functions generally return NULL upon error.
383

ATTRIBUTES

385       See attributes(5) for a description of the following attributes:
386
387
388
389
390       ┌─────────────────────────────┬─────────────────────────────┐
391       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
392       │Availability                 │SUNWcsl (32-bit)             │
393       │                             │SUNWcslx (64-bit)            │
394       │Interface Stability          │Evolving                     │
395       └─────────────────────────────┴─────────────────────────────┘
396

SEE ALSO

398       ldap(3LDAP),       ldap_entry2text(3LDAP),       ldaptemplates.conf(4),
399       attributes(5)
400
401
402
403SunOS 5.11                        27 Jan 2002             ldap_disptmpl(3LDAP)
Impressum