--- name: "ldap_disptmpl" section: "3" platform: "linux" package: "libldap2-dev" version: "2.0.23-6.3" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/ldap_disptmpl" --- # ldap\_disptmpl(3) LDAP display template routines ## NAME 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 ``` **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)](/ldaptemplates.conf/5.md)). Each display template 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 [ldap\_entry2text(3)](/ldap_entry2text/3.md) 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 [ldaptemplates.conf(5)](/ldaptemplates.conf/5.md)) *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 configuration file (see [ldaptemplates.conf(5)](/ldaptemplates.conf/5.md)) *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 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 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 template 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 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 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 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\_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 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 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, homePostalAddress, multilineDescription, 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 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 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 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 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 displayed. **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 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/3.md), [**ldap\_entry2text**(3)](/ldap_entry2text/3.md), [**ldaptemplates.conf**(5)](/ldaptemplates.conf/5.md) ## 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.