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

   1 .TH LDAP_DISPTMPL 3  "13 December 1994" "U-M LDAP 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)