ABCDEFGHIJKLMNOPQRSTUVWXYZ

ldap_next_disptmpl

LDAP_DISPTMPL(3)                                              LDAP_DISPTMPL(3)



NAME
       ldap_init_templates,    ldap_init_templates_buf,   ldap_free_templates,
       ldap_first_disptmpl, ldap_next_disptmpl, ldap_oc2template, ldap_tmplat-
       trs,    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_tmplitem *ldap_next_tmplcol( tmpl, row, col )
       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 ldaptemplates.conf(5)).  Each display template
       contains a pre-determined list of items, where each item generally cor-
       responds  to  an attribute to be displayed.  The items contain informa-
       tion 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) rou-
       tines 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  ldaptemplates.conf(5))   Zero   is
       returned  upon success, and tmpllistp is set to point to a list of tem-
       plates.  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  configuration 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 structure.  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 cur-
       rently 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 alternate view of
       another template,  typically  used  for  templates  pointed  to  be  an
       LDAP_SYN_LINKACTION item).

       ldap_free_templates()   disposes   of   the   templates   allocated  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 objectClass 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 contains 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  syntaxmask  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  syntaxmask  is non-zero are included.  If exclude is non-
       zero, attributes where the logical AND of the template item  syntax  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  follows  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 structure.  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.

       The LDAP_IS_TMPLITEM_OPTION_SET() macro is used to test a 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_VALUEREQUIRED (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_plu-
       ralname  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 con-
       tains     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 distinguished 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;
            struct ldap_oclist  *oc_next;
       };
       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 distinguished 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  element  ti_syn-
       taxid,  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 gen-
       eral 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 currently defined option is
       LDAP_SYN_OPT_DEFER, which (if set) implies  that  the  values  for  the
       attribute should not be retrieved until requested.

       There  are sixteen distinct syntax ids currently defined.  These gener-
       ally 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 mul-
       tiple lines, e.g., postalAddress, homePostalAddress,  multilineDescrip-
       tion, or any attributes of syntax 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 syntax, e.g.,
       jpegPhoto.

       LDAP_SYN_JPEGBUTTON is used to provide a button (or  equivalent  inter-
       face  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  syntax,  e.g.,
       Photo.  These are actually Group 3 Fax (T.4) format images.

       LDAP_SYN_FAXBUTTON is used to provide a button (or equivalent 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 inter-
       face 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  syntax,  e.g.,
       lastModifiedTime.   The  value(s)  should be displayed in complete date
       and time fashion.

       LDAP_SYN_DATE is used for attributes with  the  UTCTime  syntax,  e.g.,
       lastModifiedTime.  Only the date portion of the value(s) should be dis-
       played.

       LDAP_SYN_LABELEDURL is used for labeledURL attributes.

       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 per-
       formed  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 perform-
       ing 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   Project
       (http://www.openldap.org/).   OpenLDAP  is  derived  from University of
       Michigan LDAP 3.3 Release.



OpenLDAP 2.0.27-Release        22 September 1998              LDAP_DISPTMPL(3)