1ldap_disptmpl(3LDAP) LDAP Library Functions ldap_disptmpl(3LDAP)
2
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
13 cc[ flag... ] file... -lldap[ library... ]
14 #include <lber.h>
15 #include <ldap.h>
16 int ldap_init_templates(char *file, struct ldap_disptmpl **tmpllistp);
18 int ldap_init_templates_buf(char *buf, unsigned long len,
21 struct ldap_disptmpl **tmpllistp);
22 void ldap_free_templates(struct ldap_disptmpl *tmpllist);
25 struct ldap_disptmpl *ldap_first_disptmpl
28 (struct ldap_disptmpl *tmpllist);
29 struct ldap_disptmpl *ldap_next_disptmpl
32 (struct ldap_disptmpl *tmpllist,struct ldap_disptmpl *tmpl);
33 struct ldap_disptmpl *ldap_oc2template (char **oclist,
36 struct ldap_disptmpl *tmpllist);
37 struct ldap_disptmpl *ldap_name2template (char *name,
40 struct ldap_disptmpl *tmpllist);
41 char **ldap_tmplattrs(struct ldap_disptmpl *tmpl, char **includeattrs,
44 int exclude;, unsigned long syntaxmask);
45 struct ldap_tmplitem *ldap_first_tmplrow(struct ldap_disptmpl *tmpl);
48 struct ldap_tmplitem *ldap_next_tmplrow(struct ldap_disptmpl *tmpl,
51 struct ldap_tmplitem *row);
52 struct ldap_tmplitem *ldap_first_tmplcol(struct ldap_disptmpl *tmpl,
55 struct ldap_tmplitem *row, struct ldap_tmplitem *col);
56 struct ldap_tmplitem *ldap_next_tmplcol(struct ldap_disptmpl *tmpl,
59 struct ldap_tmplitem *row, struct ldap_tmplitem *col);
60
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 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 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 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 The LDAP_GET_DISPTMPL_APPDATA() macro is used to retrieve the value in
97 the dt_appdata field.
98 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 ldap_free_templates() disposes of the templates allocated by
111 ldap_init_templates().
112 ldap_first_disptmpl() returns the first template in the list tmpllist.
115 The tmpllist is typically obtained by calling ldap_init_templates() .
116 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 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 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 ldap_first_tmplrow() returns a pointer to the first row of items in
146 template tmpl.
147 ldap_next_tmplrow() returns a pointer to the row that follows row in
150 template tmpl.
151 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 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 The LDAP_GET_TMPLITEM_APPDATA() macro is used to retrieve the value of
165 the ti_appdata field.
166 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 ldap_next_tmplcol() returns a pointer to the item (column) that follows
180 column col within row row of template tmpl.
181 DISPTMPL Structure Elements
183 The ldap_disptmpl structure is defined as:
184 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 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 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 dt_oclist is a pointer to a linked list of object class arrays, defined
221 as:
222 struct ldap_oclist {
224 char **oc_objclasses;
225 struct ldap_oclist *oc_next;
226 };
227 These are used by the ldap_oc2template() function.
231 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 struct ldap_adddeflist {
238 int ad_source;
239 char *ad_attrname;
240 char *ad_value;
241 struct ldap_adddeflist *ad_next;
242 };
243 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 TMPLITEM Structure Elements
254 The ldap_tmplitem structure is defined as:
255 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 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 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 There are sixteen distinct syntax ids currently defined. These gener‐
291 ally correspond to one or more X.500 syntaxes.
292 LDAP_SYN_CASEIGNORESTR is used for text attributes which are simple
295 strings whose case is ignored for comparison purposes.
296 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 LDAP_SYN_RFC822ADDR is used for case ignore string attributes that are
304 RFC-822 conformant mail addresses, for example, mail.
305 LDAP_SYN_DN is used for attributes with a Distinguished Name syntax,
308 for example, seeAlso.
309 LDAP_SYN_BOOLEAN is used for attributes with a boolean syntax.
312 LDAP_SYN_JPEGIMAGE is used for attributes with a jpeg syntax, for exam‐
315 ple, jpegPhoto.
316 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 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 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 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 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 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 LDAP_SYN_LABELEDURL is used for labeledURL attributes.
349 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 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 LDAP_SYN_ADDDNACTION and LDAP_SYN_VERIFYDNACTION are reserved as
374 actions but currently undefined.
375
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
385 See attributes(5) for a description of the following attributes:
386 ┌─────────────────────────────┬─────────────────────────────┐
391 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
392 │Availability │SUNWcsl (32-bit) │
393 │ │SUNWcslx (64-bit) │
394 │Interface Stability │Evolving │
395 └─────────────────────────────┴─────────────────────────────┘
396
398 ldap(3LDAP), ldap_entry2text(3LDAP), ldaptemplates.conf(4),
399 attributes(5)
400SunOS 5.11 27 Jan 2002 ldap_disptmpl(3LDAP)