Unix/Linux Go Back    


RedHat 9 (Linux i386) - man page for ldap_next_disptmpl (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


LDAP_DISPTMPL(3)								 LDAP_DISPTMPL(3)

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 display templates.  Entry dis-
       play 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  configu-
       ration  file (see ldaptemplates.conf(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 SYN-
       TAX 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 LDAP template  configura-
       tion  file (see ldaptemplates.conf(5)) 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))  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 tem-
       plate  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 con-
       tains 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  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 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  dis-
       tinguished 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 informa-
       tion.  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  occur-
       rences  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_entry2text(3), ldaptemplates.conf(5)

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.

OpenLDAP 2.0.27-Release 		22 September 1998			 LDAP_DISPTMPL(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:31 PM.