LDAP Library Functions ldapdisptmpl(3LDAP)
NAME
ldapdisptmpl, ldapinittemplates, ldapinittemplatesbuf,
ldapfreetemplates, ldapfirstdisptmpl,
ldapnextdisptmpl, ldapoc2template, ldapname2template,
ldaptmplattrs, ldapfirsttmplrow, ldapnexttmplrow,
ldapfirsttmplcol, ldapnexttmplcol - LDAP display tem-
plate functions
SYNOPSIS
cc[ flag... ] file... -lldap[ library... ]
#include
#include
int ldapinittemplates(char *file, struct ldapdisptmpl **tmpllistp);
int ldapinittemplatesbuf(char *buf, unsigned long len,
struct ldapdisptmpl **tmpllistp);
void ldapfreetemplates(struct ldapdisptmpl *tmpllist);
struct ldapdisptmpl *ldapfirstdisptmpl
(struct ldapdisptmpl *tmpllist);
struct ldapdisptmpl *ldapnextdisptmpl
(struct ldapdisptmpl *tmpllist,struct ldapdisptmpl *tmpl);
struct ldapdisptmpl *ldapoc2template (char **oclist,
struct ldapdisptmpl *tmpllist);
struct ldapdisptmpl *ldapname2template (char *name,
struct ldapdisptmpl *tmpllist);
char **ldaptmplattrs(struct ldapdisptmpl *tmpl, char **includeattrs,
int exclude;, unsigned long syntaxmask);
struct ldaptmplitem *ldapfirsttmplrow(struct ldapdisptmpl *tmpl);
struct ldaptmplitem *ldapnexttmplrow(struct ldapdisptmpl *tmpl,
struct ldaptmplitem *row);
struct ldaptmplitem *ldapfirsttmplcol(struct ldapdisptmpl *tmpl,
struct ldaptmplitem *row, struct ldaptmplitem *col);
SunOS 5.11 Last change: 27 Jan 2002 1
LDAP Library Functions ldapdisptmpl(3LDAP)
struct ldaptmplitem *ldapnexttmplcol(struct ldapdisptmpl *tmpl,
struct ldaptmplitem *row, struct ldaptmplitem *col);
DESCRIPTION
These functions provide a standard way to access LDAP entry
display 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 appropriate
display 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 in
the SYNTAX IDS section below. The ldapentry2text(3LDAP)
functions use the display template functions and produce
text output.
ldapinittemplates() 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. Each
member of the list is an ldapdisptmpl structure (defined
below in the DISPTMPL Structure Elements section).
ldapinittemplatesbuf() 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 LDAPSETDISPTMPLAPDATA() macro is used to set the
value of the dtappdata field in an ldapdisptmpl struc-
ture. This field is reserved for the calling application to
use; it is not used internally.
The LDAPGETDISPTMPLAPDATA() macro is used to retrieve
the value in the dtappdata field.
The LDAPISDISPTMPLOPTIONSET() macro is used to test a
ldapdisptmpl structure for the existence of a template
option. The options currently defined are:
LDAPDTMPLOPTADABLE (it is appropriate to allow entries
of this type to be added), LDAPDTMPLOPTALOWMODRDN (it is
SunOS 5.11 Last change: 27 Jan 2002 2
LDAP Library Functions ldapdisptmpl(3LDAP)
appropriate to offer the "modify rdn"operation),
LDAPDTMPLOPTALTVIEW (this template is merely an alternate
view of another template, typically used for templates
pointed to be an LDAPSYNLINKACTION item).
ldapfreetemplates() disposes of the templates allocated by
ldapinittemplates().
ldapfirstdisptmpl() returns the first template in the list
tmpllist. The tmpllist is typically obtained by calling
ldapinittemplates() .
ldapnextdisptmpl() returns the template after tmpl in the
template list tmpllist. A NUL pointer is returned if tmpl
is the last template in the list.
ldapoc2template() 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 template
where all of the object classes listed in one of the
template's dtoclist elements are contained in oclist is
returned. A NUL pointer is returned if no appropriate tem-
plate is found.
ldaptmplattrs() 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 ldapvaluefree(). The
includeattrs parameter contains a null-terminated array of
attributes that should always be included (it may be NUL 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 syntax-
mask is non-zero are excluded.
ldapfirsttmplrow() returns a pointer to the first row of
items in template tmpl.
ldapnexttmplrow() 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 ldapdisptmpl(3LDAP)
ldapfirsttmplcol() returns a pointer to the first item (in
the first column) of row row within template tmpl. A pointer
to an ldaptmplitem structure (defined below in the TMPLI-
TEM Structure Elements section) is returned.
The LDAPSETMPLITEMAPDATA() macro is used to set the
value of the tiappdata field in a ldaptmplitem struc-
ture. This field is reserved for the calling application to
use; it is not used internally.
The LDAPGETMPLITEMAPDATA() macro is used to retrieve
the value of the tiappdata field.
The LDAPISTMPLITEMOPTIONSET() macro is used to test a
ldaptmplitem structure for the existence of an item option.
The options currently defined are: LDAPDITEMOPTREADONLY
(this attribute should not be modified),
LDAPDITEMOPTSORTVALUES (it makes sense to sort the
values), LDAPDITEMOPTSINGLEVALUED (this attribute can
only hold a single value), LDAPDITEMOPTVALUEREQUIRED
(this attribute must contain at least one value),
LDAPDITEMOPTHIDEIFEMPTY (do not show this item if there
are no values), and LDAPDITEMOPTHIDEIFALSE (for boolean
attributes only: hide this item if the value is FALSE).
ldapnexttmplcol() returns a pointer to the item (column)
that follows column col within row row of template tmpl.
DISPTMPL Structure Elements
The ldapdisptmpl structure is defined as:
struct ldapdisptmpl {
char *dtname;
char *dtpluralname;
char *dticonname;
unsigned long dtoptions;
char *dtauthattrname;
char *dtdefrdnattrname;
char *dtdefaddlocation;
struct ldapoclist *dtoclist;
struct ldapadddeflist *dtadddeflist;
struct ldaptmplitem *dtitems;
void *dtappdata;
struct ldapdisptmpl *dtnext;
};
SunOS 5.11 Last change: 27 Jan 2002 4
LDAP Library Functions ldapdisptmpl(3LDAP)
The dtname member is the singular name of the template.
The dtpluralname is the plural name. The dticonname
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 dtoptions contains options
which may be tested using the LDAPISTMPLITEMOPTIONSET()
macro.
The dtauthattrname contains the name of the DN-syntax
attribute whose value(s) should be used to authenticate to
make changes to an entry. If dtauthattrname is NUL, then
authenticating as the entry itself is appropriate. The
dtdefrdnattrname is the name of the attribute that is nor-
mally used to name entries of this type, for example,
"cn"for person entries. The dtdefaddlocation is the dis-
tinguished name of an entry below which new entries of this
type are typically created (its value is site-dependent).
dtoclist is a pointer to a linked list of object class
arrays, defined as:
struct ldapoclist {
char **ocobjclasses;
struct ldapoclist *ocnext;
};
These are used by the ldapoc2template() function.
dtadddeflist is a pointer to a linked list of rules for
defaulting the values of attributes when new entries are
created. The ldapadddeflist structure is defined as:
struct ldapadddeflist {
int adsource;
char *adattrname;
char *advalue;
struct ldapadddeflist *adnext;
};
The adattrname member contains the name of the attribute
whose value this rule sets. If adsource is
LDAPADSRCONSTANTVALUE then the advalue member contains
the (constant) value to use. If adsource is
LDAPADSRCADERSDN then advalue is ignored and the dis-
tinguished name of the person who is adding the new entry is
SunOS 5.11 Last change: 27 Jan 2002 5
LDAP Library Functions ldapdisptmpl(3LDAP)
used as the default value for adattrname.
TMPLITEM Structure Elements
The ldaptmplitem structure is defined as:
struct ldaptmplitem {
unsigned long tisyntaxid;
unsigned long tioptions;
char *tiattrname;
char *tilabel;
char **tiargs;
struct ldaptmplitem *tinextinrow;
struct ldaptmplitem *tinextincol;
void *tiappdata;
};
Syntax IDs
Syntax ids are found in the ldaptmplitem structure element
tisyntaxid, and they can be used to determine how to
display the values for the attribute associated with an
item. The LDAPGETSYNTYPE() macro can be used to return
a general type from a syntax id. The five general types
currently defined are: LDAPSYNTYPETEXT (for attributes
that are most appropriately shown as text),
LDAPSYNTYPEIMAGE (for JPEG or FAX format images),
LDAPSYNTYPEBOLEAN (for boolean attributes),
LDAPSYNTYPEBUTON (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 is
retrieved, decoded, and displayed), and LDAPSYNTYPEACTION
(for special purpose actions such as "search for the entries
where this entry is listed in the seeAlso attribute").
The LDAPGETSYNOPTIONS macro can be used to retrieve an
unsigned long bitmap that defines options. The only
currently defined option is LDAPSYNOPTDEFER, 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.
LDAPSYNCASEIGNORESTR 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 ldapdisptmpl(3LDAP)
LDAPSYNMULTILINESTR is used for text attributes which con-
sist of multiple lines, for example, postalAddress,
homePostalAddress, multilineDescription, or any attributes
of syntax caseIgnoreList.
LDAPSYNRFC822ADR is used for case ignore string attri-
butes that are RFC-822 conformant mail addresses, for exam-
ple, mail.
LDAPSYNDN is used for attributes with a Distinguished Name
syntax, for example, seeAlso.
LDAPSYNBOLEAN is used for attributes with a boolean syn-
tax.
LDAPSYNJPEGIMAGE is used for attributes with a jpeg syn-
tax, for example, jpegPhoto.
LDAPSYNJPEGBUTON is used to provide a button (or
equivalent interface element) that can be used to retrieve,
decode, and display an attribute of jpeg syntax.
LDAPSYNFAXIMAGE is used for attributes with a photo syn-
tax, for example, Photo. These are actually Group 3 Fax
(T.4) format images.
LDAPSYNFAXBUTON is used to provide a button (or
equivalent interface element) that can be used to retrieve,
decode, and display an attribute of photo syntax.
LDAPSYNAUDIOBUTON 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.
LDAPSYNTIME is used for attributes with the UTCTime syn-
tax, for example, lastModifiedTime. The value(s) should be
displayed in complete date and time fashion.
LDAPSYNDATE 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 ldapdisptmpl(3LDAP)
LDAPSYNLABELEDURL is used for labeledURL attributes.
LDAPSYNSEARCHACTION is used to define a search that is
used to retrieve related information. If tiattrname is not
NUL, it is assumed to be a boolean attribute which will
cause no search to be performed if its value is FALSE.
The tiargs structure member will have four strings in it:
tiargs[ 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, tiargs[ 1 ] should be a filter pattern where any
occurrences of "%v" are replaced with the value derived from
tiargs[ 0 ], tiargs[ 2 ] should be the name of an addi-
tional attribute to retrieve when performing the search, and
tiargs[ 3 ] should be a human-consumable name for that
attribute. The tiargs[ 2 ] attribute is typically
displayed along with a list of distinguished names when mul-
tiple entries are returned by the search.
LDAPSYNLINKACTION is used to define a link to another tem-
plate by name. tiargs[ 0 ] will contain the name of the
display template to use. The ldapname2template() function
can be used to obtain a pointer to the correct
ldapdisptmpl structure.
LDAPSYNADNACTION and LDAPSYNVERIFYDNACTION are
reserved as actions but currently undefined.
ERORS
The init template functions return LDAPTMPLERVERSION if
buf points to data that is newer than can be handled,
LDAPTMPLERMEM if there is a memory allocation problem,
LDAPTMPLERSYNTAX if there is a problem with the format
of the templates buffer or file. LDAPTMPLERFILE is
returned by ldapinittemplates if the file cannot be read.
Other functions generally return NUL upon error.
ATRIBUTES
See attributes(5) for a description of the following attri-
butes:
SunOS 5.11 Last change: 27 Jan 2002 8
LDAP Library Functions ldapdisptmpl(3LDAP)
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsl (32-bit)
SUNWcslx (64-bit)
Interface Stability Evolving
SEE ALSO
ldap(3LDAP), ldapentry2text(3LDAP), ldaptemplates.conf(4),
attributes(5)
SunOS 5.11 Last change: 27 Jan 2002 9
|
