LDAP Library Functions ldap_disptmpl(3LDAP)
NAME
ldap_disptmpl, ldap_init_templates, ldap_init_templates_buf,
ldap_free_templates, ldap_first_disptmpl,
ldap_next_disptmpl, ldap_oc2template, ldap_name2template,
ldap_tmplattrs, ldap_first_tmplrow, ldap_next_tmplrow,
ldap_first_tmplcol, ldap_next_tmplcol - LDAP display tem-
plate functionsSYNOPSIS
cc[ flag... ] file... -lldap[ library... ]
#include
#include
int ldap_init_templates(char *file, struct ldap_disptmpl **tmpllistp);
int ldap_init_templates_buf(char *buf, unsigned long len,
struct ldap_disptmpl **tmpllistp);
void ldap_free_templates(struct ldap_disptmpl *tmpllist);
struct ldap_disptmpl *ldap_first_disptmpl
(struct ldap_disptmpl *tmpllist);
struct ldap_disptmpl *ldap_next_disptmpl
(struct ldap_disptmpl *tmpllist,struct ldap_disptmpl *tmpl);
struct ldap_disptmpl *ldap_oc2template (char **oclist,
struct ldap_disptmpl *tmpllist);
struct ldap_disptmpl *ldap_name2template (char *name,
struct ldap_disptmpl *tmpllist);
char **ldap_tmplattrs(struct ldap_disptmpl *tmpl, char **includeattrs,
int exclude;, unsigned long syntaxmask);struct ldap_tmplitem *ldap_first_tmplrow(struct ldap_disptmpl *tmpl);
struct ldap_tmplitem *ldap_next_tmplrow(struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row);
struct ldap_tmplitem *ldap_first_tmplcol(struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row, struct ldap_tmplitem *col);
SunOS 5.11 Last change: 27 Jan 2002 1
LDAP Library Functions ldap_disptmpl(3LDAP)
struct ldap_tmplitem *ldap_next_tmplcol(struct ldap_disptmpl *tmpl,
struct ldap_tmplitem *row, struct ldap_tmplitem *col);
DESCRIPTION
These functions provide a standard way to access LDAP entrydisplay templates. Entry display templates provide a stan-
dard 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 appropriatedisplay template. Display templates are defined in a confi-
guration file. See ldaptemplates.conf(4). Each display tem-
plate contains a pre-determined list of items, where each
item generally corresponds 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 inthe SYNTAX IDS section below. The ldap_entry2text(3LDAP)
functions 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(4)). Upon success, 0 is returned, and tmpllistp is set to point to a list of templates. Eachmember 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(4)). Upon success, 0 is returned, 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
SunOS 5.11 Last change: 27 Jan 2002 2
LDAP Library Functions ldap_disptmpl(3LDAP)
appropriate to offer the "modify rdn"operation),LDAP_DTMPL_OPT_ALTVIEW (this template is merely an alternate
view of another template, typically used for templatespointed 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 callingldap_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 ofobjectClass 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 template where all of the object classes listed in one of thetemplate's dt_oclist elements are contained in oclist is
returned. A NULL pointer is returned if no appropriate tem-
plate 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. Theattribute 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 ifno 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 ofthe 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 syntax-
mask 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.SunOS 5.11 Last change: 27 Jan 2002 3
LDAP Library Functions ldap_disptmpl(3LDAP)
ldap_first_tmplcol() returns a pointer to the first item (in
the first column) of row row within template tmpl. A pointerto an ldap_tmplitem structure (defined below in the TMPLI-
TEM 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.
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 modified),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 ElementsThe 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;
};SunOS 5.11 Last change: 27 Jan 2002 4
LDAP Library Functions ldap_disptmpl(3LDAP)
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 correspondto 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 tomake changes to an entry. If dt_authattrname is NULL, then
authenticating as the entry itself is appropriate. Thedt_defrdnattrname is the name of the attribute that is nor-
mally used to name entries of this type, for example,"cn"for person entries. The dt_defaddlocation is the dis-
tinguished name of an entry below which new entries of thistype 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() function.
dt_adddeflist is a pointer to a linked list of rules for
defaulting the values of attributes when new entries arecreated. 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 isSunOS 5.11 Last change: 27 Jan 2002 5
LDAP Library Functions ldap_disptmpl(3LDAP)
used as the default value for ad_attrname.
TMPLITEM Structure ElementsThe 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 IDsSyntax ids are found in the ldap_tmplitem structure element
ti_syntaxid, and they can be used to determine how to
display the values for the attribute associated with anitem. The LDAP_GET_SYN_TYPE() macro can be used to return
a general type from a syntax id. The five general typescurrently 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, for example, in response to the press of a button, a JPEG image isretrieved, 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 onlycurrently 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 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 pur-
poses.SunOS 5.11 Last change: 27 Jan 2002 6
LDAP Library Functions ldap_disptmpl(3LDAP)
LDAP_SYN_MULTILINESTR is used for text attributes which con-
sist of multiple lines, for example, postalAddress, homePostalAddress, multilineDescription, or any attributes of syntax caseIgnoreList.LDAP_SYN_RFC822ADDR is used for case ignore string attri-
butes that are RFC-822 conformant mail addresses, for exam-
ple, mail.LDAP_SYN_DN is used for attributes with a Distinguished Name
syntax, for example, seeAlso.LDAP_SYN_BOOLEAN is used for attributes with a boolean syn-
tax.LDAP_SYN_JPEGIMAGE is used for attributes with a jpeg syn-
tax, for example, jpegPhoto.LDAP_SYN_JPEGBUTTON is used to provide a button (or
equivalent 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, for example, 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 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, for example, lastModifiedTime. The value(s) should be displayed in complete date and time fashion.LDAP_SYN_DATE is used for attributes with the UTCTime syn-
tax, for example, lastModifiedTime. Only the date portion of the value(s) should be displayed.SunOS 5.11 Last change: 27 Jan 2002 7
LDAP Library Functions ldap_disptmpl(3LDAP)
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 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 beused, 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 addi-
tional attribute to retrieve when performing the search, andti_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 mul-
tiple entries are returned by the search.LDAP_SYN_LINKACTION is used to define a link to another tem-
plate by name. ti_args[ 0 ] will contain the name of the
display template to use. The ldap_name2template() function
can be used to obtain a pointer to the correctldap_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 functions generally return NULL upon error.ATTRIBUTES
See attributes(5) for a description of the following attri-
butes:SunOS 5.11 Last change: 27 Jan 2002 8
LDAP Library Functions ldap_disptmpl(3LDAP)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Availability | system/library (32-bit) |
| | SUNWcslx (64-bit) |
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
ldap(3LDAP), ldap_entry2text(3LDAP), ldaptemplates.conf(4),
attributes(5)SunOS 5.11 Last change: 27 Jan 2002 9