MAN page from RedHat Other ldap-devel-3.3-3.i386.rpm

LDAP_DISPTMPL

Section: C Library Functions (3)
Updated: 13 December 1994
Index

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 <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 displaytemplates. Entry display templates provide a standard way for LDAPapplications to display directory entries. The general idea is that itis possible to map the list of object class values present in an entryto an appropriate display template. Display templates are defined in aconfiguration file (see ldaptemplates.conf(5)). Each display templatecontains a pre-determined list of items, where each item generallycorresponds to an attribute to be displayed. The items containinformation and flags that the caller can use to display the attribute andvalues in a reasonable fashion. Each item has a syntaxid, which aredescribed in the SYNTAX IDS section below. The ldap_entry2text(3)routines use the display template functions and produce text output.

ldap_init_templates() reads a sequence of templates from a valid LDAPtemplate configuration file (see ldaptemplates.conf(5))Zerois returned upon success, andtmpllistpis set to point to a list of templates. Each member of the list is anldap_disptmpl structure (defined below in the DISPTMPL STRUCTURE ELEMENTSsection).

ldap_init_templates_buf() reads a sequence of templates frombuf(whose size isbuflen).bufshould point to the data in the format defined for an LDAP templateconfiguration file (see ldaptemplates.conf(5))Zerois returned upon success, andtmpllistpis set to point to a list of templates.

TheLDAP_SET_DISPTMPL_APPDATA()macro is used to set the value of the dt_appdata field in an ldap_disptmplstructure. This field is reserved for the calling application to use; itis not used internally.

TheLDAP_GET_DISPTMPL_APPDATA()macro is used to retrieve the value in the dt_appdata field.

TheLDAP_IS_DISPTMPL_OPTION_SET()macro is used to test a ldap_disptmpl structure for the existence of atemplate 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, typicallyused for templates pointed to be an LDAP_SYN_LINKACTION item).

ldap_free_templates() disposes of the templates allocated byldap_init_templates().

ldap_first_disptmpl() returns the first template in the listtmpllist.Thetmpllistis typically obtained by calling ldap_init_templates().

ldap_next_disptmpl() returns the template aftertmplin the template listtmpllist. ANULLpointer is returned iftmplis the last template in the list.

ldap_oc2template() searchestmpllistfor the best template to use to display an entry that has a specificset of objectClass values.oclistshould be a null-terminated array of strings that contains the valuesof the objectClass attribute of the entry. A pointer to the firsttemplate where all of the object classes listed in one of thetemplate's dt_oclist elements are contained inoclistis returned. ANULLpointer is returned if no appropriate template is found.

ldap_tmplattrs() returns a null-terminated array that contains thenames of attributes that need to be retrieved if the templatetmplis to be used to display an entry. The attribute list should be freedusing ldap_value_free(). Theincludeattrsparameter contains a null-terminated array of attributes that shouldalways be included (it may beNULLif no extra attributes are required). Ifsyntaxmaskis non-zero, it is used to restrict the attribute set returned. Ifexcludeis zero, only attributes where the logical AND of the template itemsyntax id and thesyntaxmaskis non-zero are included. Ifexcludeis non-zero, attributes where the logical AND of the template itemsyntax id and thesyntaxmaskis non-zero are excluded.

ldap_first_tmplrow() returns a pointer to the first row of items intemplatetmpl.

ldap_next_tmplrow() returns a pointer to the row that followsrowin templatetmpl.

ldap_first_tmplcol() returns a pointer to the first item (in the firstcolumn) of rowrowwithin templatetmpl. A pointer to an ldap_tmplitem structure (defined belowin the TMPLITEM STRUCTURE ELEMENTS section) is returned.

TheLDAP_SET_TMPLITEM_APPDATA()macro is used to set the value of the ti_appdata field in a ldap_tmplitemstructure. This field is reserved for the calling application to use; itis not used internally.

TheLDAP_GET_TMPLITEM_APPDATA()macro is used to retrieve the value of the ti_appdata field.

TheLDAP_IS_TMPLITEM_OPTION_SET()macro is used to test a ldap_tmplitem structure for the existence of anitem 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), andLDAP_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 columncolwithin rowrowof templatetmpl.

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_pluralnameis the plural name. The dt_iconname member will contain the name of anicon or other graphical element that can be used to depict entries thatcorrespond to this display template. The dt_options contains options whichmay be tested using the LDAP_IS_TMPLITEM_OPTION_SET() macro.

The dt_authattrname contains the name of the DN-syntax attribute whosevalue(s) should be used to authenticate to make changes to an entry. Ifdt_authattrname is NULL, then authenticating as the entry itself isappropriate. The dt_defrdnattrname is the name of the attribute thatis normally used to name entries of this type, e.g., "cn" for personentries. The dt_defaddlocation is the distinguished name of an entrybelow which new entries of this type are typically created (its value issite-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 thevalues of attributes when new entries are created. The ldap_adddefliststructure 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 thisrule sets. If ad_source is LDAP_ADSRC_CONSTANTVALUEthen the ad_value member contains the (constant) value to use.If ad_source isLDAP_ADSRC_ADDERSDNthen ad_value is ignored and the distinguished name of the person whois 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 theattribute associated with an item. The LDAP_GET_SYN_TYPE() macro canbe 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, e.g., in response to the press of a button, a JPEG image isretrieved, decoded, and displayed), andLDAP_SYN_TYPE_ACTION(for special purpose actions such as "search for the entries where thisentry is listed in the seeAlso attribute").

TheLDAP_GET_SYN_OPTIONSmacro can be used to retrieve an unsigned long bitmap that definesoptions. The only currently defined option isLDAP_SYN_OPT_DEFER,which (if set) implies that the values for the attribute should notbe retrieved until requested.

There are sixteen distinct syntax ids currently defined. These generallycorrespond to one or more X.500 syntaxes.

LDAP_SYN_CASEIGNORESTRis used for text attributes which are simple strings whose case is ignoredfor comparison purposes.

LDAP_SYN_MULTILINESTRis used for text attributes which consist of multiple lines,e.g., postalAddress, homePostalAddress, multilineDescription, or anyattributes of syntax caseIgnoreList.

LDAP_SYN_RFC822ADDRis used for case ignore string attributes that are RFC-822 conformantmail addresses, e.g., mail.

LDAP_SYN_DNis used for attributes with a Distinguished Name syntax, e.g., seeAlso.

LDAP_SYN_BOOLEANis used for attributes with a boolean syntax.

LDAP_SYN_JPEGIMAGEis used for attributes with a jpeg syntax, e.g., jpegPhoto.

LDAP_SYN_JPEGBUTTONis used to provide a button (or equivalent interface element) that can beused to retrieve, decode, and display an attribute of jpeg syntax.

LDAP_SYN_FAXIMAGEis used for attributes with a photo syntax, e.g., Photo. These areactually Group 3 Fax (T.4) format images.

LDAP_SYN_FAXBUTTONis used to provide a button (or equivalent interface element) that can beused to retrieve, decode, and display an attribute of photo syntax.

LDAP_SYN_AUDIOBUTTONis used to provide a button (or equivalent interface element) that can beused to retrieve and play an attribute of audio syntax. Audio values arein the "mu law" format, also known as "au" format.

LDAP_SYN_TIMEis used for attributes with the UTCTime syntax, e.g., lastModifiedTime.The value(s) should be displayed in complete date and time fashion.

LDAP_SYN_DATEis used for attributes with the UTCTime syntax, e.g., lastModifiedTime.Only the date portion of the value(s) should be displayed.

LDAP_SYN_LABELEDURLis used for labeledURL attributes.

LDAP_SYN_SEARCHACTIONis 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 whichwill cause no search to be performed if its value is FALSE. The ti_argsstructure member will have four strings in it: ti_args[ 0 ] should bethe name of an attribute whose values are used to help construct a searchfilter or "-dn" is the distinguished name of the entry being displayedshould be used, ti_args[ 1 ] should be a filter pattern where any occurrencesof "%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 performingthe search, and ti_args[ 3 ] should be a human-consumable name for thatattribute. The ti_args[ 2 ] attribute is typically displayed along witha list of distinguished names when multiple entries are returned by thesearch.

LDAP_SYN_LINKACTIONis used to define a link to another template by name. ti_args[ 0 ] willcontain 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_ADDDNACTIONandLDAP_SYN_VERIFYDNACTIONare reserved as actions but currently undefined.

ERRORS

The init template functions returnLDAP_TMPL_ERR_VERSIONif buf points to data that is newer than can be handled,LDAP_TMPL_ERR_MEMif there is a memory allocation problem,LDAP_TMPL_ERR_SYNTAXif there is a problem with the format of the templates buffer or file.LDAP_TMPL_ERR_FILEis returned byldap_init_templatesif the file cannot be read. Other routines generally returnNULLupon error.

This document was created byman2html,using the manual pages.