git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_disptmpl.3

   1 .TH LDAP_DISPTMPL 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-1999 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.