'\" te .\" Copyright (C) 1990, Regents of the University of Michigan. All Rights Reserved. .\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved. .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH LDAP_DISPTMPL 3LDAP "Jan 27, 2002" .SH 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 template functions .SH SYNOPSIS .LP .nf cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ] #include #include \fBint\fR \fBldap_init_templates\fR(\fBchar\fR \fI*file\fR, \fBstruct ldap_disptmpl\fR \fI**tmpllistp\fR); .fi .LP .nf \fBint\fR \fBldap_init_templates_buf\fR(\fBchar\fR \fI*buf\fR, \fBunsigned long\fR \fIlen\fR, \fBstruct ldap_disptmpl\fR \fI**tmpllistp\fR); .fi .LP .nf \fBvoid\fR \fBldap_free_templates\fR(\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); .fi .LP .nf \fBstruct ldap_disptmpl\fR \fB*ldap_first_disptmpl\fR (\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); .fi .LP .nf \fBstruct ldap_disptmpl\fR \fB*ldap_next_disptmpl\fR (\fBstruct ldap_disptmpl\fR \fI*tmpllist\fR,\fBstruct ldap_disptmpl\fR \fI*tmpl\fR); .fi .LP .nf \fBstruct ldap_disptmpl\fR \fB*ldap_oc2template\fR (\fBchar\fR \fI**oclist\fR, \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); .fi .LP .nf \fBstruct ldap_disptmpl\fR \fB*ldap_name2template\fR (\fBchar\fR \fI*name\fR, \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR); .fi .LP .nf \fBchar\fR \fB**ldap_tmplattrs\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**includeattrs\fR, \fBint\fR \fIexclude;\fR, \fBunsigned long\fR \fIsyntaxmask\fR); .fi .LP .nf \fBstruct ldap_tmplitem\fR \fB*ldap_first_tmplrow\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR); .fi .LP .nf \fBstruct ldap_tmplitem\fR \fB*ldap_next_tmplrow\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBstruct ldap_tmplitem\fR \fI*row\fR); .fi .LP .nf \fBstruct ldap_tmplitem\fR \fB*ldap_first_tmplcol\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBstruct ldap_tmplitem\fR \fI*row\fR, \fBstruct ldap_tmplitem\fR \fI*col\fR); .fi .LP .nf \fBstruct ldap_tmplitem\fR \fB*ldap_next_tmplcol\fR(\fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBstruct ldap_tmplitem\fR \fI*row\fR, \fBstruct ldap_tmplitem\fR \fI*col\fR); .fi .SH DESCRIPTION .sp .LP 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 \fBldaptemplates.conf\fR(5). 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 \fBldap_entry2text\fR(3LDAP) functions use the display template functions and produce text output. .sp .LP \fBldap_init_templates()\fR reads a sequence of templates from a valid LDAP template configuration file (see \fBldaptemplates.conf\fR(5)). Upon success, \fB0\fR is returned, and \fItmpllistp\fR is set to point to a list of templates. Each member of the list is an \fBldap_disptmpl\fR structure (defined below in the DISPTMPL Structure Elements section). .sp .LP \fBldap_init_templates_buf()\fR reads a sequence of templates from \fIbuf\fR (whose size is \fIbuflen).\fR \fIbuf\fR should point to the data in the format defined for an LDAP template configuration file (see \fBldaptemplates.conf\fR(5)). Upon success, \fB0\fR is returned, and \fItmpllistp\fR is set to point to a list of templates. .sp .LP The \fBLDAP_SET_DISPTMPL_APPDATA()\fR macro is used to set the value of the \fBdt_appdata\fR field in an \fBldap_disptmpl\fR structure. This field is reserved for the calling application to use; it is not used internally. .sp .LP The \fBLDAP_GET_DISPTMPL_APPDATA()\fR macro is used to retrieve the value in the \fBdt_appdata\fR field. .sp .LP The \fBLDAP_IS_DISPTMPL_OPTION_SET()\fR macro is used to test a \fBldap_disptmpl\fR structure for the existence of a template option. The options currently defined are: \fBLDAP_DTMPL_OPT_ADDABLE\fR (it is appropriate to allow entries of this type to be added), \fBLDAP_DTMPL_OPT_ALLOWMODRDN\fR (it is appropriate to offer the "modify rdn"operation), \fBLDAP_DTMPL_OPT_ALTVIEW\fR (this template is merely an alternate view of another template, typically used for templates pointed to be an \fBLDAP_SYN_LINKACTION\fR item). .sp .LP \fBldap_free_templates()\fR disposes of the templates allocated by \fBldap_init_templates()\fR. .sp .LP \fBldap_first_disptmpl()\fR returns the first template in the list \fItmpllist.\fR The \fItmpllist\fR is typically obtained by calling \fBldap_init_templates()\fR \fB\&.\fR .sp .LP \fBldap_next_disptmpl()\fR returns the template after \fItmpl\fR in the template list \fItmpllist.\fR \fIA\fR \fINULL\fR pointer is returned if \fItmpl\fR is the last template in the list. .sp .LP \fBldap_oc2template()\fR searches \fItmpllist\fR for the best template to use to display an entry that has a specific set of \fBobjectClass\fR values. \fIoclist\fR should be a null-terminated array of strings that contains the values of the \fBobjectClass\fR attribute of the entry. A pointer to the first template where all of the object classes listed in one of the template's \fBdt_oclist\fR elements are contained in \fIoclist\fR is returned. A \fINULL\fR pointer is returned if no appropriate template is found. .sp .LP \fBldap_tmplattrs()\fR returns a null-terminated array that contains the names of attributes that need to be retrieved if the template \fItmpl\fR is to be used to display an entry. The attribute list should be freed using \fBldap_value_free\fR(\|). The \fIincludeattrs\fR parameter contains a null-terminated array of attributes that should always be included (it may be \fINULL\fR if no extra attributes are required). If \fIsyntaxmask\fR is non-zero, it is used to restrict the attribute set returned. If \fIexclude\fR is zero, only attributes where the logical \fBAND\fR of the template item syntax id and the \fIsyntaxmask\fR is non-zero are included. If \fIexclude\fR is non-zero, attributes where the logical \fBAND\fR of the template item syntax id and the \fIsyntaxmask\fR is non-zero are excluded. .sp .LP \fBldap_first_tmplrow()\fR returns a pointer to the first row of items in template \fItmpl.\fR .sp .LP \fBldap_next_tmplrow()\fR returns a pointer to the row that follows \fIrow\fR in template \fItmpl.\fR .sp .LP \fBldap_first_tmplcol()\fR returns a pointer to the first item (in the first column) of row \fIrow\fR within template \fItmpl\fR. A pointer to an \fBldap_tmplitem\fR structure (defined below in the TMPLITEM Structure Elements section) is returned. .sp .LP The \fBLDAP_SET_TMPLITEM_APPDATA()\fR macro is used to set the value of the \fBti_appdata\fR field in a \fBldap_tmplitem\fR structure. This field is reserved for the calling application to use; it is not used internally. .sp .LP The \fBLDAP_GET_TMPLITEM_APPDATA()\fR macro is used to retrieve the value of the \fBti_appdata\fR field. .sp .LP The \fBLDAP_IS_TMPLITEM_OPTION_SET()\fR macro is used to test a \fBldap_tmplitem\fR structure for the existence of an item option. The options currently defined are: \fBLDAP_DITEM_OPT_READONLY\fR (this attribute should not be modified), \fBLDAP_DITEM_OPT_SORTVALUES\fR (it makes sense to sort the values), \fBLDAP_DITEM_OPT_SINGLEVALUED\fR (this attribute can only hold a single value), \fBLDAP_DITEM_OPT_VALUEREQUIRED\fR (this attribute must contain at least one value), \fBLDAP_DITEM_OPT_HIDEIFEMPTY\fR (do not show this item if there are no values), and \fBLDAP_DITEM_OPT_HIDEIFFALSE\fR (for boolean attributes only: hide this item if the value is \fBFALSE\fR). .sp .LP \fBldap_next_tmplcol()\fR returns a pointer to the item (column) that follows column \fBcol\fR within row \fIrow\fR of template \fItmpl.\fR .SS "DISPTMPL Structure Elements" .sp .LP The \fBldap_disptmpl\fR structure is defined as: .sp .in +2 .nf 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; }; \fI\fR .fi .in -2 .sp .LP The \fBdt_name\fR member is the singular name of the template. The \fBdt_pluralname\fR is the plural name. The \fBdt_iconname\fR 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 \fBdt_options\fR contains options which may be tested using the \fBLDAP_IS_TMPLITEM_OPTION_SET()\fR macro. .sp .LP The \fBdt_authattrname\fR contains the name of the DN-syntax attribute whose value(s) should be used to authenticate to make changes to an entry. If \fBdt_authattrname\fR is \fINULL\fR, then authenticating as the entry itself is appropriate. The \fBdt_defrdnattrname\fR is the name of the attribute that is normally used to name entries of this type, for example, "cn"for person entries. The \fBdt_defaddlocation\fR is the distinguished name of an entry below which new entries of this type are typically created (its value is site-dependent). .sp .LP \fBdt_oclist\fR is a pointer to a linked list of object class arrays, defined as: .sp .in +2 .nf struct ldap_oclist { char **oc_objclasses; struct ldap_oclist *oc_next; }; .fi .in -2 .sp .LP These are used by the \fBldap_oc2template()\fR function. .sp .LP \fBdt_adddeflist\fR is a pointer to a linked list of rules for defaulting the values of attributes when new entries are created. The \fBldap_adddeflist\fR structure is defined as: .sp .in +2 .nf struct ldap_adddeflist { int ad_source; char *ad_attrname; char *ad_value; struct ldap_adddeflist *ad_next; }; .fi .in -2 .sp .LP The ad_attrname member contains the name of the attribute whose value this rule sets. If \fBad_source\fR is \fBLDAP_ADSRC_CONSTANTVALUE\fR then the \fBad_value\fR member contains the (constant) value to use. If \fBad_source\fR is \fBLDAP_ADSRC_ADDERSDN\fR 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 \fBad_attrname\fR. .SS "TMPLITEM Structure Elements" .sp .LP The \fBldap_tmplitem\fR structure is defined as: .sp .in +2 .nf 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; }; .fi .in -2 .SS "Syntax IDs" .sp .LP Syntax ids are found in the \fBldap_tmplitem\fR structure element \fBti_syntaxid\fR, and they can be used to determine how to display the values for the attribute associated with an item. The \fBLDAP_GET_SYN_TYPE()\fR macro can be used to return a general type from a syntax id. The five general types currently defined are: \fBLDAP_SYN_TYPE_TEXT\fR (for attributes that are most appropriately shown as text), \fBLDAP_SYN_TYPE_IMAGE\fR (for JPEG or FAX format images), \fBLDAP_SYN_TYPE_BOOLEAN\fR (for boolean attributes), \fBLDAP_SYN_TYPE_BUTTON\fR (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 \fBLDAP_SYN_TYPE_ACTION\fR (for special purpose actions such as "search for the entries where this entry is listed in the seeAlso attribute"). .sp .LP The \fBLDAP_GET_SYN_OPTIONS\fR macro can be used to retrieve an unsigned long bitmap that defines options. The only currently defined option is \fBLDAP_SYN_OPT_DEFER,\fR which (if set) implies that the values for the attribute should not be retrieved until requested. .sp .LP There are sixteen distinct syntax ids currently defined. These generally correspond to one or more X.500 syntaxes. .sp .LP \fBLDAP_SYN_CASEIGNORESTR\fR is used for text attributes which are simple strings whose case is ignored for comparison purposes. .sp .LP \fBLDAP_SYN_MULTILINESTR\fR is used for text attributes which consist of multiple lines, for example, \fBpostalAddress\fR, \fBhomePostalAddress\fR, \fBmultilineDescription\fR, or any attributes of syntax \fBcaseIgnoreList\fR. .sp .LP \fBLDAP_SYN_RFC822ADDR\fR is used for case ignore string attributes that are RFC-822 conformant mail addresses, for example, mail. .sp .LP \fBLDAP_SYN_DN\fR is used for attributes with a Distinguished Name syntax, for example, \fBseeAlso\fR. .sp .LP \fBLDAP_SYN_BOOLEAN\fR is used for attributes with a boolean syntax. .sp .LP \fBLDAP_SYN_JPEGIMAGE\fR is used for attributes with a jpeg syntax, for example, jpegPhoto. .sp .LP \fBLDAP_SYN_JPEGBUTTON\fR is used to provide a button (or equivalent interface element) that can be used to retrieve, decode, and display an attribute of jpeg syntax. .sp .LP \fBLDAP_SYN_FAXIMAGE\fR is used for attributes with a photo syntax, for example, Photo. These are actually Group 3 Fax (T.4) format images. .sp .LP \fBLDAP_SYN_FAXBUTTON\fR is used to provide a button (or equivalent interface element) that can be used to retrieve, decode, and display an attribute of photo syntax. .sp .LP \fBLDAP_SYN_AUDIOBUTTON\fR 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. .sp .LP \fBLDAP_SYN_TIME\fR is used for attributes with the UTCTime syntax, for example, \fBlastModifiedTime\fR. The value(s) should be displayed in complete date and time fashion. .sp .LP \fBLDAP_SYN_DATE\fR is used for attributes with the UTCTime syntax, for example, \fBlastModifiedTime\fR. Only the date portion of the value(s) should be displayed. .sp .LP \fBLDAP_SYN_LABELEDURL\fR is used for \fBlabeledURL\fR attributes. .sp .LP \fBLDAP_SYN_SEARCHACTION\fR is used to define a search that is used to retrieve related information. If \fBti_attrname\fR is not \fINULL\fR, it is assumed to be a boolean attribute which will cause no search to be performed if its value is \fBFALSE\fR. The \fBti_args\fR structure member will have four strings in it: \fBti_args[\fR \fB0\fR \fB]\fR 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, \fBti_args[\fR \fB1\fR \fB]\fR should be a filter pattern where any occurrences of "%v" are replaced with the value derived from \fBti_args[ 0 ]\fR, \fBti_args[\fR \fB2\fR \fB]\fR should be the name of an additional attribute to retrieve when performing the search, and \fBti_args[\fR \fB3\fR \fB]\fR should be a human-consumable name for that attribute. The \fBti_args[\fR \fB2\fR \fB]\fR attribute is typically displayed along with a list of distinguished names when multiple entries are returned by the search. .sp .LP \fBLDAP_SYN_LINKACTION\fR is used to define a link to another template by name. \fBti_args[\fR \fB0\fR \fB]\fR will contain the name of the display template to use. The \fBldap_name2template()\fR function can be used to obtain a pointer to the correct \fBldap_disptmpl\fR structure. .sp .LP \fBLDAP_SYN_ADDDNACTION\fR and \fBLDAP_SYN_VERIFYDNACTION\fR are reserved as actions but currently undefined. .SH ERRORS .sp .LP The init template functions return \fBLDAP_TMPL_ERR_VERSION\fR if \fIbuf\fR points to data that is newer than can be handled, \fBLDAP_TMPL_ERR_MEM\fR if there is a memory allocation problem, \fBLDAP_TMPL_ERR_SYNTAX\fR if there is a problem with the format of the templates buffer or file. \fBLDAP_TMPL_ERR_FILE\fR is returned by \fBldap_init_templates\fR if the file cannot be read. Other functions generally return \fINULL\fR upon error. .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for a description of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE Interface Stability Evolving .TE .SH SEE ALSO .sp .LP .BR ldap (3LDAP), .BR ldap_entry2text (3LDAP), .BR ldaptemplates.conf (5), .BR attributes (7)