ldap_next_tmplrow
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)
