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


SYNOPSIS

       #include <disptmpl.h>

       int ldap_init_templates( file, tmpllistp )
       char           *file;
       struct ldap_disptmpl     **tmpllistp;

       int ldap_init_templates_buf( buf, buflen, tmpllistp )
       char           *buf;
       unsigned long       len;
       struct ldap_disptmpl     **tmpllistp;

       void ldap_free_templates( tmpllist )
       struct ldap_disptmpl     *tmpllist;

       struct ldap_disptmpl *ldap_first_disptmpl( tmpllist )
       struct ldap_disptmpl     *tmpllist;

       struct ldap_disptmpl *ldap_next_disptmpl( tmpllist, tmpl )
       struct ldap_disptmpl     *tmpllist;
       struct ldap_disptmpl     *tmpl;

       struct ldap_disptmpl *ldap_oc2template( oclist, tmpllist )
       char           **oclist;
       struct ldap_disptmpl     *tmpllist;

       struct ldap_disptmpl *ldap_name2template( name, tmpllist )
       char           *name;
       struct ldap_disptmpl     *tmpllist;

       char **ldap_tmplattrs( tmpl, includeattrs, exclude, syntaxmask )
       struct ldap_disptmpl     *tmpl;
       char           **includeattrs;
       int            exclude;
       unsigned long       syntaxmask;

       struct ldap_tmplitem *ldap_first_tmplrow( tmpl )
       struct ldap_disptmpl     *tmpl;

       struct ldap_tmplitem *ldap_next_tmplrow( tmpl, row )
       struct ldap_disptmpl     *tmpl;
       struct ldap_tmplitem     *row;

       struct ldap_tmplitem *ldap_first_tmplcol( tmpl, row )
       struct ldap_disptmpl     *tmpl;
       struct ldap_tmplitem     *row;

       struct ldap_disptmpl     *tmpl;
       struct ldap_tmplitem     *row;
       struct ldap_tmplitem     *col;


DESCRIPTION

       These  functions  provide  a  standard  way to access LDAP
       entry display templates.  Entry display templates  provide
       a  standard way for LDAP applications to display directory
       entries.  The general idea is that it is possible  to  map
       the  list of object class values present in an entry to an
       appropriate  display  template.   Display  templates   are
       defined    in   a   configuration   file   (see   ldaptem­
       plates.conf(5)).  Each display template  contains  a  pre-
       determined list of items, where each item generally corre­
       sponds to an attribute to be displayed.  The items contain
       information  and  flags that the caller can use to display
       the attribute and values in a  reasonable  fashion.   Each
       item has a syntaxid, which are described in the SYNTAX IDS
       section below.  The ldap_entry2text(3)  routines  use  the
       display template functions and produce text output.

       ldap_init_templates() reads a sequence of templates from a
       valid  LDAP  template  configuration  file  (see  ldaptem­
       plates.conf(5))   Zero   is  returned  upon  success,  and
       tmpllistp is set to point to a list  of  templates.   Each
       member  of the list is an ldap_disptmpl structure (defined
       below in the DISPTMPL STRUCTURE ELEMENTS section).

       ldap_init_templates_buf() reads a  sequence  of  templates
       from  buf (whose size is buflen).  buf should point to the
       data in the format defined for an LDAP template configura­
       tion  file  (see  ldaptemplates.conf(5))  Zero is returned
       upon success, and tmpllistp is set to point to a  list  of
       templates.

       The  LDAP_SET_DISPTMPL_APPDATA()  macro is used to set the
       value of the dt_appdata field in an  ldap_disptmpl  struc­
       ture.   This field is reserved for the calling application
       to use; it is not used internally.

       The LDAP_GET_DISPTMPL_APPDATA() macro is used to  retrieve
       the value in the dt_appdata field.

       The  LDAP_IS_DISPTMPL_OPTION_SET() macro is used to test a
       ldap_disptmpl structure for the existence  of  a  template
       option.     The    options    currently    defined    are:
       LDAP_DTMPL_OPT_ADDABLE (it is appropriate to allow entries
       of  this type to be added), LDAP_DTMPL_OPT_ALLOWMODRDN (it
       is appropriate  to  offer  the  "modify  rdn"  operation),
       LDAP_DTMPL_OPT_ALTVIEW  (this template is merely an alter­
       nate view of another template,  typically  used  for  tem­
       plates pointed to be an LDAP_SYN_LINKACTION item).

       by ldap_init_templates().

       ldap_first_disptmpl() returns the first  template  in  the
       list  tmpllist.   The  tmpllist  is  typically obtained by
       calling ldap_init_templates().

       ldap_next_disptmpl() returns the template  after  tmpl  in
       the  template list tmpllist. A NULL pointer is returned if
       tmpl is the last template in the list.

       ldap_oc2template() searches tmpllist for the best template
       to  use  to  display  an  entry that has a specific set of
       objectClass values.  oclist should  be  a  null-terminated
       array  of  strings that contains the values of the object­
       Class attribute of the entry.  A pointer to the first tem­
       plate where all of the object classes listed in one of the
       template's dt_oclist elements are contained in  oclist  is
       returned.   A  NULL  pointer is returned if no appropriate
       template is found.

       ldap_tmplattrs() returns a null-terminated array that con­
       tains the names of attributes that need to be retrieved if
       the template tmpl is to be used to display an entry.   The
       attribute  list  should  be freed using ldap_value_free().
       The  includeattrs  parameter  contains  a  null-terminated
       array of attributes that should always be included (it may
       be NULL if no extra attributes are required).  If  syntax­
       mask is non-zero, it is used to restrict the attribute set
       returned.  If exclude is zero, only attributes  where  the
       logical AND of the template item syntax id and the syntax­
       mask is non-zero are included.  If  exclude  is  non-zero,
       attributes where the logical AND of the template item syn­
       tax id and the syntaxmask is non-zero are excluded.

       ldap_first_tmplrow() returns a pointer to the first row of
       items in template tmpl.

       ldap_next_tmplrow() returns a pointer to the row that fol­
       lows row in template tmpl.

       ldap_first_tmplcol() returns a pointer to the  first  item
       (in  the  first column) of row row within template tmpl. A
       pointer to an ldap_tmplitem structure  (defined  below  in
       the TMPLITEM STRUCTURE ELEMENTS section) is returned.

       The  LDAP_SET_TMPLITEM_APPDATA()  macro is used to set the
       value of the ti_appdata field in  a  ldap_tmplitem  struc­
       ture.   This field is reserved for the calling application
       to use; it is not used internally.

       The LDAP_GET_TMPLITEM_APPDATA() macro is used to  retrieve
       the value of the ti_appdata field.

       ldap_tmplitem structure  for  the  existence  of  an  item
       option.     The    options    currently    defined    are:
       LDAP_DITEM_OPT_READONLY (this attribute should not be mod­
       ified),  LDAP_DITEM_OPT_SORTVALUES (it makes sense to sort
       the values), LDAP_DITEM_OPT_SINGLEVALUED  (this  attribute
       can   only   hold  a  single  value),  LDAP_DITEM_OPT_VAL­
       UEREQUIRED (this  attribute  must  contain  at  least  one
       value),  LDAP_DITEM_OPT_HIDEIFEMPTY (do not show this item
       if there are no  values),  and  LDAP_DITEM_OPT_HIDEIFFALSE
       (for boolean attributes only:  hide this item if the value
       is FALSE).

       ldap_next_tmplcol() returns a pointer to the item (column)
       that follows column col within row row of template tmpl.


DISPTMPL STRUCTURE ELEMENTS

       The ldap_disptmpl structure is defined as:
       struct ldap_disptmpl {
            char                    *dt_name;
            char           *dt_pluralname;
            char                    *dt_iconname;
            unsigned long           dt_options;
            char                    *dt_authattrname;
            char                    *dt_defrdnattrname;
            char                    *dt_defaddlocation;
            struct ldap_oclist  *dt_oclist;
            struct ldap_adddeflist   *dt_adddeflist;
            struct ldap_tmplitem     *dt_items;
            void           *dt_appdata;
            struct ldap_disptmpl     *dt_next;
       };
       The  dt_name  member is the singular name of the template.
       The dt_pluralname is the  plural  name.   The  dt_iconname
       member will contain the name of an icon or other graphical
       element that can be used to depict entries that correspond
       to this display template.  The dt_options contains options
       which      may       be       tested       using       the
       LDAP_IS_TMPLITEM_OPTION_SET() macro.

       The  dt_authattrname  contains  the  name of the DN-syntax
       attribute whose value(s) should be used to authenticate to
       make  changes  to  an  entry.  If dt_authattrname is NULL,
       then authenticating as the entry  itself  is  appropriate.
       The dt_defrdnattrname is the name of the attribute that is
       normally used to name entries of this type, e.g., "cn" for
       person  entries.   The  dt_defaddlocation  is  the distin­
       guished name of an entry below which new entries  of  this
       type  are typically created (its value is site-dependent).

       dt_oclist is a pointer to a linked list  of  object  class
       arrays, defined as:
       struct ldap_oclist {
            char           **oc_objclasses;

       };
       These are used by the ldap_oc2template() routine.

       dt_adddeflist  is  a pointer to a linked list of rules for
       defaulting the values of attributes when new  entries  are
       created.  The ldap_adddeflist structure is defined as:
       struct ldap_adddeflist {
            int            ad_source;
            char           *ad_attrname;
            char           *ad_value;
            struct ldap_adddeflist   *ad_next;
       };
       The  ad_attrname member contains the name of the attribute
       whose   value   this   rule   sets.    If   ad_source   is
       LDAP_ADSRC_CONSTANTVALUE then the ad_value member contains
       the  (constant)  value   to   use.    If    ad_source   is
       LDAP_ADSRC_ADDERSDN  then ad_value is ignored and the dis­
       tinguished name of the person who is adding the new  entry
       is used as the default value for ad_attrname.


TMPLITEM STRUCTURE ELEMENTS

       The ldap_tmplitem structure is defined as:
       struct ldap_tmplitem {
            unsigned long       ti_syntaxid;
            unsigned long       ti_options;
            char           *ti_attrname;
            char           *ti_label;
            char           **ti_args;
            struct ldap_tmplitem     *ti_next_in_row;
            struct ldap_tmplitem     *ti_next_in_col;
            void           *ti_appdata;
       };


SYNTAX IDS

       Syntax  ids  are found in the ldap_tmplitem structure ele­
       ment ti_syntaxid, and they can be used to determine how to
       display  the  values  for the attribute associated with an
       item.  The LDAP_GET_SYN_TYPE() macro can be used to return
       a  general  type from a syntax id.  The five general types
       currently defined are: LDAP_SYN_TYPE_TEXT (for  attributes
       that    are    most    appropriately   shown   as   text),
       LDAP_SYN_TYPE_IMAGE  (for  JPEG  or  FAX  format  images),
       LDAP_SYN_TYPE_BOOLEAN     (for     boolean    attributes),
       LDAP_SYN_TYPE_BUTTON (for attributes whose values  are  to
       be  retrieved  and  display  only  upon  request, e.g., in
       response to the  press  of  a  button,  a  JPEG  image  is
       retrieved,      decoded,      and      displayed),     and
       LDAP_SYN_TYPE_ACTION (for special purpose actions such  as
       "search  for the entries where this entry is listed in the
       seeAlso attribute").

       The LDAP_GET_SYN_OPTIONS macro can be used to retrieve  an
       unsigned  long  bitmap  that  defines  options.   The only

       set)  implies that the values for the attribute should not
       be retrieved until requested.

       There are sixteen distinct syntax ids  currently  defined.
       These  generally correspond to one or more X.500 syntaxes.

       LDAP_SYN_CASEIGNORESTR is used for text  attributes  which
       are  simple  strings  whose case is ignored for comparison
       purposes.

       LDAP_SYN_MULTILINESTR is used for  text  attributes  which
       consist of multiple lines, e.g., postalAddress, homePosta­
       lAddress, multilineDescription, or any attributes of  syn­
       tax caseIgnoreList.

       LDAP_SYN_RFC822ADDR   is   used  for  case  ignore  string
       attributes that are  RFC-822  conformant  mail  addresses,
       e.g., mail.

       LDAP_SYN_DN  is  used  for attributes with a Distinguished
       Name syntax, e.g., seeAlso.

       LDAP_SYN_BOOLEAN is used for  attributes  with  a  boolean
       syntax.

       LDAP_SYN_JPEGIMAGE is used for attributes with a jpeg syn­
       tax, e.g., jpegPhoto.

       LDAP_SYN_JPEGBUTTON is used to provide a button (or equiv­
       alent  interface  element)  that  can be used to retrieve,
       decode, and display an attribute of jpeg syntax.

       LDAP_SYN_FAXIMAGE is used for attributes with a photo syn­
       tax,  e.g.,  Photo.   These are actually Group 3 Fax (T.4)
       format images.

       LDAP_SYN_FAXBUTTON is used to provide a button (or equiva­
       lent  interface  element)  that  can  be used to retrieve,
       decode, and display an attribute of photo syntax.

       LDAP_SYN_AUDIOBUTTON is  used  to  provide  a  button  (or
       equivalent interface element) that can be used to retrieve
       and play an attribute of audio syntax.  Audio  values  are
       in the "mu law" format, also known as "au" format.

       LDAP_SYN_TIME is used for attributes with the UTCTime syn­
       tax, e.g., lastModifiedTime.  The value(s) should be  dis­
       played in complete date and time fashion.

       LDAP_SYN_DATE is used for attributes with the UTCTime syn­
       tax, e.g., lastModifiedTime.  Only the date portion of the
       value(s) should be displayed.


       LDAP_SYN_SEARCHACTION  is  used to define a search that is
       used to retrieve related information.  If  ti_attrname  is
       not  NULL,  it  is assumed to be a boolean attribute which
       will cause no search to  be  performed  if  its  value  is
       FALSE.   The  ti_args  structure  member  will  have  four
       strings in it:  ti_args[ 0 ] should  be  the  name  of  an
       attribute whose values are used to help construct a search
       filter or "-dn" is the distinguished  name  of  the  entry
       being  displayed  should be used, ti_args[ 1 ] should be a
       filter pattern where any occurrences of "%v" are  replaced
       with  the  value  derived  from ti_args[ 0 ], ti_args[ 2 ]
       should be the name of an additional attribute to  retrieve
       when  performing  the search, and ti_args[ 3 ] should be a
       human-consumable name for that attribute.  The ti_args[  2
       ]  attribute  is  typically displayed along with a list of
       distinguished names when multiple entries are returned  by
       the search.

       LDAP_SYN_LINKACTION  is  used  to define a link to another
       template by name.  ti_args[ 0 ] will contain the  name  of
       the  display  template  to  use.  The ldap_name2template()
       routine can be used to obtain a  pointer  to  the  correct
       ldap_disptmpl structure.

       LDAP_SYN_ADDDNACTION   and   LDAP_SYN_VERIFYDNACTION   are
       reserved as actions but currently undefined.


ERRORS

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


SEE ALSO

       ldap(3), ldap_entry2text(3), ldaptemplates.conf(5)


ACKNOWLEDGEMENTS

       OpenLDAP is developed and maintained by The OpenLDAP  Pro­
       ject (http://www.openldap.org/).  OpenLDAP is derived from
       University of Michigan LDAP 3.3 Release.


Man(1) output converted with man2html