Errors can be interpreted by calling
.BR ldap_err2string (3).
.SH SEARCH FILTERS
-Search filters to be passed to the ldap search routines can be
-constructed by hand, or by calling the
-.BR ldap_getfilter (3)
-routines, which use the
-.BR ldapgetfilter.conf (5)
-file to turn a string (presumably that a user has typed) into a series
-of search filters.
+Search filters to be passed to the ldap search routines are to be
+constructed by hand.
.SH DISPLAYING RESULTS
Results obtained from the ldap search routines can be output by hand,
by calling
.BR ldap_get_values (3)
to retrieve a given attribute's value. Attribute values
may or may not be displayable.
-.LP
-Alternatively, the entry can be output automatically by calling
-the
-.BR ldap_entry2text (3),
-.BR ldap_entry2text_search (3),
-.BR ldap_entry2html (3),
-or
-.BR ldap_entry2html_search (3)
-routines. These routines look up the object
-class of the entry they are passed in the
-.BR ldaptemplates.conf (5)
-file to decide which attributes to display and how to display them.
-Output is handled via a routine passed in as a parameter.
.SH UNIFORM RESOURCE LOCATORS (URLS)
The
.BR ldap_url (3)
Also provided are various utility routines. The
.BR ldap_sort (3)
routines are used to sort the entries and values returned via
-the ldap search routines. The
-.BR ldap_friendly (3)
-routines are
-used to map from short two letter country codes (or other strings)
-to longer "friendlier" names.
+the ldap search routines.
.SH BER LIBRARY
Also included in the distribution is a set of lightweight Basic
Encoding Rules routines. These routines are used by the LDAP library
.SM ldap_delete_s(3)
synchronously delete an entry
.TP
-.SM ldap_init_templates(3)
-initialize display template routines from a file
-.TP
-.SM ldap_init_templates_buf(3)
-initialize display template routines from a buffer
-.TP
-.SM ldap_free_templates(3)
-free display template routine memory
-.TP
-.SM ldap_first_disptmpl(3)
-get first display template
-.TP
-.SM ldap_next_disptmpl(3)
-get next display template
-.TP
-.SM ldap_oc2template(3)
-return template appropriate for objectclass
-.TP
-.SM ldap_name2template(3)
-return named template
-.TP
-.SM ldap_tmplattrs(3)
-return attributes needed by template
-.TP
-.SM ldap_first_tmplrow(3)
-return first row of displayable items in a template
-.TP
-.SM ldap_next_tmplrow(3)
-return next row of displayable items in a template
-.TP
-.SM ldap_first_tmplcol(3)
-return first column of displayable items in a template
-.TP
-.SM ldap_next_tmplcol(3)
-return next column of displayable items in a template
-.TP
-.SM ldap_entry2text(3)
-display an entry as text using a display template
-.TP
-.SM ldap_entry2text_search(3)
-search for and display an entry as text using a display template
-.TP
-.SM ldap_vals2text(3)
-display values as text
-.TP
-.SM ldap_entry2html(3)
-display an entry as HTML (HyperText Markup Language) using a display template
-.TP
-.SM ldap_entry2html_search(3)
-search for and display an entry as HTML using a display template
-.TP
-.SM ldap_vals2html(3)
-display values as HTML
-.TP
.SM ldap_perror(3)
print an LDAP error indication to standard error
.TP
.SM ldap_count_entries(3)
return number of entries in a search result
.TP
-.SM ldap_friendly_name(3)
-map from unfriendly to friendly names
-.TP
-.SM ldap_free_friendlymap(3)
-free resources used by ldap_friendly(3)
-.TP
.SM ldap_get_dn(3)
extract the DN from an entry
.TP
.SM ldap_count_values_len(3)
return number of values
.TP
-.SM ldap_init_getfilter(3)
-initialize getfilter routines from a file
-.TP
-.SM ldap_init_getfilter_buf(3)
-initialize getfilter routines from a buffer
-.TP
-.SM ldap_getfilter_free(3)
-free resources allocated by ldap_init_getfilter(3)
-.TP
-.SM ldap_getfirstfilter(3)
-return first search filter
-.TP
-.SM ldap_getnextfilter(3)
-return next search filter
-.TP
-.SM ldap_build_filter(3)
-construct an LDAP search filter from a pattern
-.TP
-.SM ldap_setfilteraffixes(3)
-set prefix and suffix for search filters
-.TP
.SM ldap_modify(3)
asynchronously modify an entry
.TP
.SM ldap_url_parse(3)
break up an LDAP URL string into its components
.TP
-.SM ldap_init_searchprefs(3)
-initialize searchprefs routines from a file
-.TP
-.SM ldap_init_searchprefs_buf(3)
-initialize searchprefs routines from a buffer
-.TP
-.SM ldap_free_searchprefs(3)
-free memory allocated by searchprefs routines
-.TP
-.SM ldap_first_searchobj(3)
-return first searchpref object
-.TP
-.SM ldap_next_searchobj(3)
-return next searchpref object
-.TP
.SM ldap_sort_entries(3)
sort a list of search results
.TP
+++ /dev/null
-.TH LDAP_DISPTMPL 3 "22 September 1998" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH 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
-.SH SYNOPSIS
-.nf
-.ft B
-#include <disptmpl.h>
-.ft
-.LP
-.ft B
-int ldap_init_templates( file, tmpllistp )
-.ft
-char *file;
-struct ldap_disptmpl **tmpllistp;
-.LP
-.ft B
-int ldap_init_templates_buf( buf, buflen, tmpllistp )
-.ft
-char *buf;
-unsigned long len;
-struct ldap_disptmpl **tmpllistp;
-.LP
-.ft B
-void ldap_free_templates( tmpllist )
-.ft
-struct ldap_disptmpl *tmpllist;
-.LP
-.ft B
-struct ldap_disptmpl *ldap_first_disptmpl( tmpllist )
-.ft
-struct ldap_disptmpl *tmpllist;
-.LP
-.ft B
-struct ldap_disptmpl *ldap_next_disptmpl( tmpllist, tmpl )
-.ft
-struct ldap_disptmpl *tmpllist;
-struct ldap_disptmpl *tmpl;
-.LP
-.ft B
-struct ldap_disptmpl *ldap_oc2template( oclist, tmpllist )
-.ft
-char **oclist;
-struct ldap_disptmpl *tmpllist;
-.LP
-.ft B
-struct ldap_disptmpl *ldap_name2template( name, tmpllist )
-.ft
-char *name;
-struct ldap_disptmpl *tmpllist;
-.LP
-.ft B
-char **ldap_tmplattrs( tmpl, includeattrs, exclude, syntaxmask )
-.ft
-struct ldap_disptmpl *tmpl;
-char **includeattrs;
-int exclude;
-unsigned long syntaxmask;
-.LP
-.ft B
-struct ldap_tmplitem *ldap_first_tmplrow( tmpl )
-.ft
-struct ldap_disptmpl *tmpl;
-.LP
-.ft B
-struct ldap_tmplitem *ldap_next_tmplrow( tmpl, row )
-.ft
-struct ldap_disptmpl *tmpl;
-struct ldap_tmplitem *row;
-.LP
-.ft B
-struct ldap_tmplitem *ldap_first_tmplcol( tmpl, row )
-.ft
-struct ldap_disptmpl *tmpl;
-struct ldap_tmplitem *row;
-.LP
-.ft B
-struct ldap_tmplitem *ldap_next_tmplcol( tmpl, row, col )
-.ft
-struct ldap_disptmpl *tmpl;
-struct ldap_tmplitem *row;
-struct ldap_tmplitem *col;
-.fi
-.SH 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)). 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)
-routines use the display template functions and produce text output.
-.LP
-ldap_init_templates() reads a sequence of templates from a valid LDAP
-template configuration file (see ldaptemplates.conf(5))
-.I Zero
-is returned upon success, and
-.I 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).
-.LP
-.LP
-ldap_init_templates_buf() reads a sequence of templates from
-.I buf
-(whose size is
-.I buflen).
-.I buf
-should point to the data in the format defined for an LDAP template
-configuration file (see ldaptemplates.conf(5))
-.I Zero
-is returned upon success, and
-.I tmpllistp
-is set to point to a list of templates.
-.LP
-The
-.B 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.
-.LP
-The
-.B LDAP_GET_DISPTMPL_APPDATA()
-macro is used to retrieve the value in the dt_appdata field.
-.LP
-The
-.B 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:
-.B LDAP_DTMPL_OPT_ADDABLE
-(it is appropriate to allow entries of this type to be added),
-.B LDAP_DTMPL_OPT_ALLOWMODRDN
-(it is appropriate to offer the "modify rdn" operation),
-.B 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).
-.LP
-ldap_free_templates() disposes of the templates allocated by
-ldap_init_templates().
-.LP
-ldap_first_disptmpl() returns the first template in the list
-.I tmpllist.
-The
-.I tmpllist
-is typically obtained by calling ldap_init_templates().
-.LP
-ldap_next_disptmpl() returns the template after
-.I tmpl
-in the template list
-.I tmpllist. A
-.SM NULL
-pointer is returned if
-.I tmpl
-is the last template in the list.
-.LP
-ldap_oc2template() searches
-.I tmpllist
-for the best template to use to display an entry that has a specific
-set of objectClass values.
-.I 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
-.I oclist
-is returned. A
-.B NULL
-pointer is returned if no appropriate template is found.
-.LP
-ldap_tmplattrs() returns a null-terminated array that contains the
-names of attributes that need to be retrieved if the template
-.I tmpl
-is to be used to display an entry. The attribute list should be freed
-using ldap_value_free(). The
-.I includeattrs
-parameter contains a null-terminated array of attributes that should
-always be included (it may be
-.B NULL
-if no extra attributes are required). If
-.I syntaxmask
-is non-zero, it is used to restrict the attribute set returned. If
-.I exclude
-is zero, only attributes where the logical AND of the template item
-syntax id and the
-.I syntaxmask
-is non-zero are included. If
-.I exclude
-is non-zero, attributes where the logical AND of the template item
-syntax id and the
-.I syntaxmask
-is non-zero are excluded.
-.LP
-ldap_first_tmplrow() returns a pointer to the first row of items in
-template
-.I tmpl.
-.LP
-ldap_next_tmplrow() returns a pointer to the row that follows
-.I row
-in template
-.I tmpl.
-.LP
-ldap_first_tmplcol() returns a pointer to the first item (in the first
-column) of row
-.I row
-within template
-.I tmpl. A pointer to an ldap_tmplitem structure (defined below
-in the TMPLITEM STRUCTURE ELEMENTS section) is returned.
-.LP
-The
-.B 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.
-.LP
-The
-.B LDAP_GET_TMPLITEM_APPDATA()
-macro is used to retrieve the value of the ti_appdata field.
-.LP
-The
-.B 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:
-.B LDAP_DITEM_OPT_READONLY
-(this attribute should not be modified),
-.B LDAP_DITEM_OPT_SORTVALUES
-(it makes sense to sort the values),
-.B LDAP_DITEM_OPT_SINGLEVALUED
-(this attribute can only hold a single value),
-.B LDAP_DITEM_OPT_VALUEREQUIRED
-(this attribute must contain at least one value),
-.B LDAP_DITEM_OPT_HIDEIFEMPTY
-(do not show this item if there are no values), and
-.B LDAP_DITEM_OPT_HIDEIFFALSE
-(for boolean attributes only: hide this item if the value is FALSE).
-.LP
-ldap_next_tmplcol() returns a pointer to the item (column) that follows column
-.I col
-within row
-.I row
-of template
-.I tmpl.
-.SH DISPTMPL STRUCTURE ELEMENTS
-The ldap_disptmpl structure is defined as:
-.nf
-.ft B
-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;
-};
-.ft
-.fi
-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.
-.LP
-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).
-.LP
-dt_oclist is a pointer to a linked list of object class arrays, defined as:
-.nf
-.ft B
-struct ldap_oclist {
- char **oc_objclasses;
- struct ldap_oclist *oc_next;
-};
-.ft
-.fi
-These are used by the ldap_oc2template() routine.
-.LP
-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:
-.nf
-.ft B
-struct ldap_adddeflist {
- int ad_source;
- char *ad_attrname;
- char *ad_value;
- struct ldap_adddeflist *ad_next;
-};
-.ft
-.fi
-The ad_attrname member contains the name of the attribute whose value this
-rule sets. If ad_source is
-.B LDAP_ADSRC_CONSTANTVALUE
-then the ad_value member contains the (constant) value to use.
-If ad_source is
-.B 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.
-.SH TMPLITEM STRUCTURE ELEMENTS
-The ldap_tmplitem structure is defined as:
-.nf
-.ft B
-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;
-};
-.ft
-.fi
-.SH 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:
-.B LDAP_SYN_TYPE_TEXT
-(for attributes that are most appropriately shown as text),
-.B LDAP_SYN_TYPE_IMAGE
-(for JPEG or FAX format images),
-.B LDAP_SYN_TYPE_BOOLEAN
-(for boolean attributes),
-.B 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
-.B LDAP_SYN_TYPE_ACTION
-(for special purpose actions such as "search for the entries where this
-entry is listed in the seeAlso attribute").
-.LP
-The
-.B LDAP_GET_SYN_OPTIONS
-macro can be used to retrieve an unsigned long bitmap that defines
-options. The only currently defined option is
-.B LDAP_SYN_OPT_DEFER,
-which (if set) implies that the values for the attribute should not
-be retrieved until requested.
-.LP
-There are sixteen distinct syntax ids currently defined. These generally
-correspond to one or more X.500 syntaxes.
-.LP
-.B LDAP_SYN_CASEIGNORESTR
-is used for text attributes which are simple strings whose case is ignored
-for comparison purposes.
-.LP
-.B LDAP_SYN_MULTILINESTR
-is used for text attributes which consist of multiple lines,
-e.g., postalAddress, homePostalAddress, multilineDescription, or any
-attributes of syntax caseIgnoreList.
-.LP
-.B LDAP_SYN_RFC822ADDR
-is used for case ignore string attributes that are RFC-822 conformant
-mail addresses, e.g., mail.
-.LP
-.B LDAP_SYN_DN
-is used for attributes with a Distinguished Name syntax, e.g., seeAlso.
-.LP
-.B LDAP_SYN_BOOLEAN
-is used for attributes with a boolean syntax.
-.LP
-.B LDAP_SYN_JPEGIMAGE
-is used for attributes with a jpeg syntax, e.g., jpegPhoto.
-.LP
-.B 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.
-.LP
-.B LDAP_SYN_FAXIMAGE
-is used for attributes with a photo syntax, e.g., Photo. These are
-actually Group 3 Fax (T.4) format images.
-.LP
-.B 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.
-.LP
-.B 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.
-.LP
-.B 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.
-.LP
-.B 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.
-.LP
-.B LDAP_SYN_LABELEDURL
-is used for labeledURL attributes.
-.LP
-.B 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.
-.LP
-.B 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.
-.LP
-.B LDAP_SYN_ADDDNACTION
-and
-.B LDAP_SYN_VERIFYDNACTION
-are reserved as actions but currently undefined.
-.SH ERRORS
-The init template functions return
-.B LDAP_TMPL_ERR_VERSION
-if buf points to data that is newer than can be handled,
-.B LDAP_TMPL_ERR_MEM
-if there is a memory allocation problem,
-.B LDAP_TMPL_ERR_SYNTAX
-if there is a problem with the format of the templates buffer or file.
-.B LDAP_TMPL_ERR_FILE
-is returned by
-.B ldap_init_templates
-if the file cannot be read. Other routines generally return
-.B NULL
-upon error.
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldap_entry2text (3),
-.BR ldaptemplates.conf (5)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-ldap_init_templates.3
-ldap_init_templates_buf.3
-ldap_free_templates.3
-ldap_first_disptmpl.3
-ldap_next_disptmpl.3
-ldap_oc2template.3
-ldap_tmplattrs.3
-ldap_first_tmplrow.3
-ldap_next_tmplrow.3
-ldap_first_tmplcol.3
-ldap_next_tmplcol.3
+++ /dev/null
-.TH LDAP_ENTRY2TEXT 3 "22 September 1998" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldap_entry2text, ldap_entry2text_search, ldap_vals2text \- LDAP entry display routines
-.SH SYNOPSIS
-.nf
-.ft B
-#include <ldap.h>
-#include <disptmpl.h>
-.ft
-.LP
-.ft B
-int ldap_entry2text( ld, buf, entry, tmpl, defattrs, defvals, writeproc,
- writeparm, eol, rdncount, opts )
-.ft
- LDAP *ld;
- char *buf;
- LDAPMessage *entry;
- struct ldap_disptmpl *tmpl;
- char **defattrs;
- char ***defvals;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
- unsigned long opts;
-.LP
-.ft B
-int ldap_entry2text_search( ld, entry, tmpllist, defattrs, defvals,
- writeproc, writeparm, eol, rdncount, opts )
-.ft
- LDAP *ld;
- char *dn;
- char *base;
- LDAPMessage *entry;
- struct ldap_disptmpl *tmpllist;
- char **defattrs;
- char ***defvals;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
- unsigned long opts;
-.LP
-.ft B
-int ldap_vals2text( ld, buf, vals, label, labelwidth, syntaxid, writeproc,
- writeparm, eol, rdncount )
-.ft
- LDAP *ld;
- char *buf;
- char **vals;
- char *label;
- int labelwidth;
- unsigned long syntaxid;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
-.LP
-.ft B
-int ldap_entry2html( ld, buf, entry, tmpl, defattrs, defvals, writeproc,
- writeparm, eol, rdncount, opts )
-.ft
- LDAP *ld;
- char *buf;
- LDAPMessage *entry;
- struct ldap_disptmpl *tmpl;
- char **defattrs;
- char ***defvals;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
- unsigned long opts;
- char *urlprefix;
- char *base;
-.LP
-.ft B
-int ldap_entry2html_search( ld, entry, tmpllist, defattrs, defvals,
- writeproc, writeparm, eol, rdncount, opts )
-.ft
- LDAP *ld;
- char *dn;
- LDAPMessage *entry;
- struct ldap_disptmpl *tmpllist;
- char **defattrs;
- char ***defvals;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
- unsigned long opts;
- char *urlprefix;
-.LP
-.ft B
-int ldap_vals2html( ld, buf, vals, label, labelwidth, syntaxid, writeproc,
- writeparm, eol, rdncount )
-.ft
- LDAP *ld;
- char *buf;
- char **vals;
- char *label;
- int labelwidth;
- unsigned long syntaxid;
- int (*writeproc)();
- void *writeparm;
- char *eol;
- int rdncount;
- char *urlprefix;
-.LP
-.ft B
-
-
-#define LDAP_DISP_OPT_AUTOLABELWIDTH 0x00000001
-#define LDAP_DISP_OPT_HTMLBODYONLY 0x00000002
-
-#define LDAP_DTMPL_BUFSIZ 2048
-.ft
-.fi
-.SH DESCRIPTION
-These functions use the LDAP display template routines (see
-ldap_disptmpl(3) and ldap_templates.conf(5)) to produce a plain text
-or an HyperText Markup Language (HTML) display of an entry or a set of
-values. Typical plain text output produced for an entry might look like:
-.nf
-
- "Barbara J Jensen, Information Technology Division"
- Also Known As:
- Babs Jensen
- Barbara Jensen
- Barbara J Jensen
- E-Mail Address:
- bjensen@terminator.rs.itd.umich.edu
- Work Address:
- 535 W. William
- Ann Arbor, MI 48103
- Title:
- Mythical Manager, Research Systems
- ...
-.fi
-The exact output produced will depend on the display template configuration.
-HTML output is similar to the plain text output, but more richly formatted.
-.LP
-.B ldap_entry2text(\|)
-produces a text representation of
-.I entry
-and writes the text by calling the
-.I writeproc
-function. All of the attributes values to be displayed must be present
-in
-.I entry;
-no interaction with the LDAP server will be performed within
-.B ldap_entry2text.
-.I ld
-is the LDAP pointer obtained by a previous call to
-.B ldap_open.
-.I writeproc
-should be declared as:
-.LP
-.ft B
-.nf
-int writeproc( writeparm, p, len )
-.ft
- void *writeparm;
- char *p;
- int len;
-.fi
-.LP
-where
-.I p
-is a pointer to text to be written and
-.I len
-is the length of the text.
-.I p
-is guaranteed to be zero-terminated. Lines of text are terminated
-with the string
-.I eol.
-.I buf
-is a pointer to a buffer of size
-.B LDAP_DTMPL_BUFSIZ
-or larger. If
-.I buf is
-.B NULL
-then a buffer is allocated and freed internally.
-.I tmpl
-is a pointer to the display template to be used (usually obtained by calling
-.B ldap_oc2template).
-If
-.I tmpl
-is NULL,
-no template is used and a generic display is produced.
-.I defattrs
-is a NULL-terminated array of LDAP attribute names which you wish to
-provide default values for (only used if
-.I entry
-contains no values for the attribute). An array of NULL-terminated arrays of
-default values corresponding to the attributes should be passed in
-.I defvals. The
-.I rdncount
-parameter is used to limit the number of Distinguished Name (DN) components
-that are actually displayed for DN attributes. If
-.I rdncount
-is zero, all components are shown.
-.I opts
-is used to specify output options. The only values currently allowed
-are zero (default output),
-.B LDAP_DISP_OPT_AUTOLABELWIDTH
-which causes the width for labels to be determined based on the longest
-label in
-.I tmpl, and
-.B LDAP_DISP_OPT_HTMLBODYONLY.
-The
-.B LDAP_DISP_OPT_HTMLBODYONLY
-option instructs the library not to include <HTML>, <HEAD>, <TITLE>, and
-<BODY> tags. In other words, an HTML fragment is generated, and the
-caller is responsible for prepending and appending the appropriate HTML
-tags to construct a correct HTML document.
-.LP
-.B ldap_entry2text_search(\|)
-is similar to
-.B ldap_entry2text,
-and all of the like-named parameters have the same meaning except as noted
-below.
-If
-.I base
-is not NULL, it is the search base to use when executing search actions. If
-it is NULL, search action template items are ignored. If
-.I entry
-is not NULL, it should contain the
-.I objectClass
-attribute values for the entry to be displayed. If
-.I entry
-is NULL,
-.I dn
-must not be NULL, and
-.B ldap_entry2text_search
-will retrieve the objectClass values itself by calling
-.B ldap_search_s.
-.B ldap_entry2text_search
-will determine the appropriate display template to use by calling
-.B ldap_oc2template,
-and will call
-.B ldap_search_s
-to retrieve any attribute values to be displayed. The
-.I tmpllist
-parameter is a pointer to the entire list of templates available (usually
-obtained by calling
-.B ldap_init_templates
-or
-.B ldap_init_templates_buf).
-If
-.I tmpllist
-is NULL,
-.B ldap_entry2text_search
-will attempt to read a load templates from the default template configuration
-file ETCDIR/ldaptemplates.conf.
-.LP
-.B ldap_vals2text
-produces a text representation of a single set of LDAP attribute values. The
-.I ld,
-.I buf,
-.I writeproc,
-.I writeparm,
-.I eol,
-and
-.I rdncount
-parameters are the same as the like-named parameters for
-.B ldap_entry2text.
-.I vals
-is a NULL-terminated list of values, usually obtained by a call to
-.B ldap_get_values.
-.I label
-is a string shown next to the values (usually a friendly form of an
-LDAP attribute name).
-.I labelwidth
-specifies the label margin, which is the number of blank spaces displayed
-to the left of the values. If zero is passed, a default label width is
-used.
-.I syntaxid
-is a display template attribute syntax identifier (see ldap_disptmpl(3)
-for a list of the pre-defined
-.B LDAP_SYN_...
-values).
-.LP
-.B ldap_entry2html
-produces an HTML representation of
-.I entry.
-It behaves exactly like ldap_entry2text(3), except for the formatted output
-and the addition of two parameters.
-.I urlprefix
-is the starting text to use when constructing an LDAP URL. The default is
-the string
-.I ldap:///
-The second additional parameter,
-.I base,
-the search base to use when executing search actions. If it is NULL, search
-action template items are ignored.
-.LP
-.B ldap_entry2html_search
-behaves exactly like ldap_entry2text_search(3), except HTML output is produced
-and one additional parameter is required.
-.I urlprefix
-is the starting text to use when constructing an LDAP URL. The default is
-the string
-.I ldap:///
-.LP
-.B ldap_vals2html
-behaves exactly like ldap_vals2text, except HTML output is produced
-and one additional parameter is required.
-.I urlprefix
-is the starting text to use when constructing an LDAP URL. The default is
-the string
-.I ldap:///
-.SH ERRORS
-These routines all return an LDAP error code (LDAP_SUCCESS is returned
-if no error occurs). See ldap_error(3) for details. The
-.I ld_errno
-field of the
-.I ld
-parameter is also set to indicate the error.
-.SH FILES
-ETCDIR/ldaptemplates.conf
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldap_disptmpl (3),
-.BR ldaptemplates.conf (5)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-ldap_entry2text_search.3
-ldap_vals2text.3
-ldap_entry2html.3
-ldap_entry2html_search.3
-ldap_vals2html.3
+++ /dev/null
-.TH LDAP_GETFILTER 3 "23 July 2001" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldap_init_getfilter, ldap_init_getfilter_buf, ldap_getfilter_free,
-ldap_getfirstfilter, ldap_getnextfilter, ldap_build_filter \- LDAP filter generating routines
-.SH SYNOPSIS
-.nf
-.ft B
-#include <ldap.h>
-.ft
-.fi
-.LP
-.nf
-.ft B
-#define LDAP_FILT_MAXSIZ 1024
-
-typedef struct ldap_filt_info {
- char *lfi_filter;
- char *lfi_desc;
- int lfi_scope;
- int lfi_isexact;
- struct ldap_filt_info *lfi_next;
-} LDAPFiltInfo;
-
-typedef struct ldap_filt_list {
- char *lfl_tag;
- char *lfl_pattern;
- char *lfl_delims;
- LDAPFiltInfo *lfl_ilist;
- struct ldap_filt_list *lfl_next;
-} LDAPFiltList;
-
-typedef struct ldap_filt_desc {
- LDAPFiltList *lfd_filtlist;
- LDAPFiltInfo *lfd_curfip;
- LDAPFiltInfo lfd_retfi;
- char lfd_filter[ LDAP_FILT_MAXSIZ ];
- char *lfd_curval;
- char *lfd_curvalcopy;
- char **lfd_curvalwords;
- char *lfd_filtprefix;
- char *lfd_filtsuffix;
-} LDAPFiltDesc;
-.ft
-.fi
-.LP
-.ft B
-LDAPFiltDesc *ldap_init_getfilter( file )
-.ft
-char *file;
-.LP
-.nf
-.ft B
-LDAPFiltDesc *ldap_init_getfilter_buf( buf, buflen )
-.ft
-char *buf;
-long buflen;
-.LP
-.ft B
-ldap_getfilter_free( lfdp )
-.ft
-LDAPFiltDesc *lfdp;
-.LP
-.nf
-.ft B
-LDAPFiltInfo *ldap_getfirstfilter(lfdp, tagpat, value)
-.ft
-LDAPFiltDesc *lfdp;
-char *tagpat;
-char *value;
-.LP
-.nf
-.ft B
-LDAPFiltInfo *ldap_getnextfilter(lfdp)
-.ft
-LDAPFiltDesc *lfdp;
-.LP
-.ft B
-void ldap_setfilteraffixes(lfdp, prefix, suffix)
-.ft
-LDAPFiltDesc *lfdp;
-char *prefix;
-char *suffix;
-.LP
-.ft B
-void ldap_build_filter( buf, buflen, pattern, prefix, suffix,
- attr, value, valwords )
-.ft
-char *buf;
-unsigned long buflen;
-char *pattern;
-char *prefix;
-char *suffix;
-char *attr;
-char *value;
-char **valwords;
-.SH DESCRIPTION
-.LP
-These routines are used to generate filters to be used in
-ldap_search(3) or ldap_search_s(3). Either ldap_init_getfilter or
-ldap_init_getfilter_buf must be called prior to calling any of
-the other routines except ldap_build_filter.
-.LP
-ldap_init_getfilter()
-takes a file name as its only argument. The contents of the file must
-be a valid LDAP filter configuration file (see ldapfilter.conf(5)). If
-the file is successfully read, a pointer to an LDAPFiltDesc is
-returned. This is an opaque object that is passed in subsequent get
-filter calls.
-.LP
-ldap_init_getfilter_buf()
-reads from
-.I buf
-(whose length is
-.I buflen)
-the LDAP filter configuration information.
-.I buf
-must point to the contents of a valid LDAP filter configuration file
-(see ldapfilter.conf(5)). If the filter configuration information is
-successfully read, a pointer to an LDAPFiltDesc is returned. This is
-an opaque object that is passed in subsequent get filter calls.
-.LP
-ldap_getfilter_free()
-deallocates the memory consumed by ldap_init_getfilter. Once it is
-called, the LDAPFiltDesc is no longer valid and cannot be used again.
-.LP
-ldap_getfirstfilter()
-retrieves the first filter that is appropriate for
-.I value.
-Only filter sets that have tags that match the regular expession
-.I tagpat
-are considered. ldap_getfirstfilter returns a pointer to an
-LDAPFiltInfo structure, which contains a filter with
-.I value
-inserted as appropriate in lfi_filter, a text match description in
-lfi_desc, lfi_scope set to indicate the search scope, and lfi_isexact
-set to indicate the type of filter. NULL is returned
-if no matching filters are found. lfi_scope will be one of
-.B LDAP_SCOPE_BASE,
-.B LDAP_SCOPE_ONELEVEL,
-or
-.B LDAP_SCOPE_SUBTREE.
-lfi_isexact
-will be zero if the filter has any '~' or '*' characters in it and
-non-zero otherwise.
-.LP
-ldap_getnextfilter()
-retrieves the next appropriate filter in the filter set that was
-determined when ldap_getfirstfilter was called. It returns NULL when
-the list has been exhausted.
-.LP
-ldap_setfilteraffixes()
-sets a
-.I prefix
-to be prepended and a
-.I suffix
-to be appended to all filters returned in the future.
-.LP
-ldap_build_filter()
-constructs an LDAP search filter in
-.I buf.
-.I buflen
-is the size, in bytes, of the largest filter
-.I buf
-can hold. A pattern for the desired filter is passed in
-.I pattern.
-Where the string %a appears in the pattern it is replaced with
-.I attr.
-.I prefix
-is pre-pended to the resulting filter, and
-.I suffix
-is appended. Either can be NULL (in which case they are not used).
-.I value
-and
-.I valwords
-are used when the string %v appears in
-.I pattern.
-See ldapfilter.conf(5) for a description of how %v is handled.
-.LP
-.SH ERRORS
-NULL is returned by ldap_init_getfilter if there is an error reading
-.I file.
-NULL is returned by ldap_getfirstfilter and ldap_getnextfilter when there
-are no more appropriate filters to return.
-.SH NOTES
-.LP
-The return values for all of these functions are declared in the
-<ldap.h> header file.
-Some routines may dynamically allocate memory
-which the caller must free using the supplied deallocator routines.
-.SH FILES
-ETCDIR/ldapfilter.conf
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldapfilter.conf (5)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-ldap_init_getfilter.3
-ldap_init_getfilter_buf.3
-ldap_getfilter_free.3
-ldap_getfirstfilter.3
-ldap_getnextfilter.3
-ldap_setfilteraffixes.3
-ldap_build_filter.3
+++ /dev/null
-.TH SEARCHPREFS 3 "22 September 1998" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldap_init_searchprefs, ldap_init_searchprefs_buf, ldap_free_searchprefs, ldap_first_searchobj, ldap_next_searchobj \- LDAP search preference configuration routeines
-.SH SYNOPSIS
-.nf
-.ft B
-#include <srchpref.h>
-.ft
-.fi
-.LP
-.nf
-.ft B
-struct ldap_searchattr {
- char *sa_attrlabel;
- char *sa_attr;
- /* max 32 matchtypes for now */
- u_long sa_matchtypebitmap;
- char *sa_selectattr;
- char *sa_selecttext;
- struct ldap_searchattr *sa_next;
-};
-
-struct ldap_searchmatch {
- char *sm_matchprompt;
- char *sm_filter;
- struct ldap_searchmatch *sm_next;
-};
-
-struct ldap_searchobj {
- char *so_objtypeprompt;
- unsigned long so_options;
- char *so_prompt;
- short so_defaultscope;
- char *so_filterprefix;
- char *so_filtertag;
- char *so_defaultselectattr;
- char *so_defaultselecttext;
- struct ldap_searchattr *so_salist;
- struct ldap_searchmatch *so_smlist;
- struct ldap_searchobj *so_next;
-};
-.ft
-.fi
-.LP
-.nf
-.ft B
-int ldap_init_searchprefs( file, solistp )
- char \(**file;
- struct ldap_searchobj \(***solistp;
-.ft
-.fi
-.LP
-.nf
-.ft B
-int ldap_init_searchprefs_buf( buf, buflen, solistp )
- char \(**buf;
- unsigned long len;
- struct ldap_searchobj \(***solistp;
-.ft
-.fi
-.LP
-.nf
-.ft B
-struct ldap_searchobj \(**ldap_free_searchprefs( solist )
- struct ldap_searchobj \(**solist;
-.ft
-.fi
-.LP
-.nf
-.ft B
-struct ldap_searchobj \(**ldap_first_searchobj( solist )
- struct ldap_seachobj \(**solist;
-.ft
-.fi
-.LP
-.nf
-.ft B
-struct ldap_searchobj \(**ldap_next_searchobj( solist, so )
- struct ldap_searchobj \(**solist;
- struct ldap_searchobj \(**so;
-
-.SH DESCRIPTION
-These functions provide a standard way to access LDAP search preference
-configuration data. LDAP search preference configurations are typically
-used by LDAP client programs to specify which attributes a user may
-search by, labels for the attributes, and LDAP filters and scopes
-associated with those searches. Client software presents these choices
-to a user, who can then specify the type of search to be performed.
-.LP
-.B ldap_init_searchprefs(\|)
-reads a sequence of search preference configurations from a valid LDAP
-searchpref configuration file
-(see ldapsearchprefs.conf(5))
-.I Zero
-is returned upon success, and
-.I solistp
-is set to point to a list of search preference data structures.
-.LP
-.B ldap_init_searchprefs_buf(\|)
-reads a sequence of search preference configurations from
-.I buf
-(whose size is
-.I buflen).
-.I buf
-should point to the data in the format defined for an LDAP search preference
-configuration file (see ldapsearchprefs.conf(5))
-.I Zero
-is returned upon success, and
-.I solistp
-is set to point to a list of search preference data structures.
-
-.LP
-.B ldap_free_searchprefs(\|)
-disposes of the data structures allocated by
-.B ldap_init_searchprefs(\|).
-.LP
-.B ldap_first_searchpref(\|)
-returns the first search preference data structure in the list
-.I solist.
-The
-.I solist
-is typically obtained by calling
-.B ldap_init_searchprefs(\|).
-.LP
-.B ldap_next_searchpref(\|)
-returns the search preference after
-.I so
-in the template list
-.I solist. A
-.SM NULL
-pointer is returned if
-.I so
-is the last entry in the list.
-.LP
-.SH ERRORS
-The init preferences functions return
-.B LDAP_SEARCHPREF_ERR_VERSION
-if buf points to data that is newer than can be handled, and
-.B LDAP_SEARCHPREF_ERR_MEM
-if there is a memory allocation problem.
-.SH NOTES
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldapsearchprefs.conf (5),
-.BR ldapd (8)
-.LP
-Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight Directory Access
-Protocol", OSI-DS-26, April 1992.
-.LP
-Howes, T., Hardcastle-Kille, S., Yeong, W., and Robbins, C., "Lightweight
-Directory Access Protocol", OSI-DS-26, April 1992.
-.LP
-Hardcastle-Kille, S., "A String Representation of Distinguished Names",
-OSI-DS-23, April 1992.
-.LP
-Information Processing - Open Systems Interconnection - The Directory,
-International Organization for Standardization. International Standard
-9594, (1988).
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-ldap_init_searchprefs.3
-ldap_init_searchprefs_buf.3
-ldap_free_searchprefs.3
-ldap_first_searchobj.3
-ldap_next_searchobj.3
+++ /dev/null
-.TH LDAPFILTER.CONF 5 "20 August 2000" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldapfilter.conf \- configuration file for LDAP get filter routines
-.SH SYNOPSIS
-ETCDIR/ldapfilter.conf
-.SH DESCRIPTION
-.LP
-The file
-.B ETCDIR/ldapfilter.conf
-contains information used by
-the LDAP get filter routines (see
-.BR ldap-getfilter (3)).
-Blank lines and
-lines that have a first character of `#' are treated as comments and
-ignored. The configuration information consists of lines that contain
-one, two, three, four, or five tokens. Tokens are separated
-by white space, and double quotes `"' can be used to include white space
-inside a token.
-.LP
-The file consists of a sequence of one or more filter sets. A filter
-set begins with a line containing a single token called a
-.I tag.
-The
-.I tag
-is used in the
-.BR ldap_getfirstfilter (3)
-call to select the filter set.
-.LP
-The filter set consists of a sequence of one or more filter lists. The
-first line in a filter list must contain four or five tokens: the
-.I value pattern,
-the
-.I delimiter list,
-a
-.I filter template,
-a
-.I match description,
-and an optional
-.I search scope.
-The
-.I value pattern
-is a regular expression that is matched against the
-.B value
-passed to the
-.BR ldap_getfirstfilter (3)
-call to select the filter list.
-.LP
-The
-.I delimiter list
-is a list of characters (in the form of a single string) that are used to
-break the
-.B value
-into distinct words.
-.LP
-The
-.I filter template
-is used to construct an LDAP filter (it is described further below)
-.LP
-The
-.I match description
-is returned to the called along with a filter as a piece of text that can
-be used to describe the sort of LDAP search that took place. It should
-correctly compete both of the following phrases:
-"One
-.I match description
-match was found for..."
-and
-"Three
-.I match description
-matches were found for...."
-.LP
-The
-.I search scope
-is optional, and should be one of "base", "onelevel", or "subtree". If
-.I search scope
-is not provided, the default is "subtree".
-.LP
-The remaining lines of the filter list should contain two or three tokens,
-a
-.I filter template,
-a
-.I match description
-and an optional
-.I search scope
-(as described above).
-.LP
-The
-.I filter template
-is similar in concept to a printf(3) style format
-string. Everything is taken literally except for the character
-sequences:
-.nf
-.ft I
- %v
- %v$
- %vN
- %vM-N
- %vN-
-.ft
-.fi
-A plain
-.I %v
-means to substitute the entire
-.B value
-string in place of the
-.I %v.
-.I %v$
-means substitute the last word in this spot.
-A
-.I %vN,
-where N is a single digit 1-9, means substitute word N in this spot.
-Words are number from left to right within the value starting at 1.
-A
-.I %vM-N,
-where M and N are both single digits 1-9, means substitute the indicated
-sequence of words.
-A
-.I %vN-,
-where N is again a single digit 1-9, means substitute word N through the
-last word in
-.B value.
-.SH EXAMPLE
-The following ldap filter configuration file contains two filter sets
-.RB ( finger
-and
-.B go500gw
-.BR onelevel ),
-each of which contains four filter lists.
-.LP
-.nf
- # ldap filter file
- #
- finger
- "=" " " "%v" "arbitrary filter"
-
- "[0-9][0-9\-]*" " " "(telephoneNumber=*%v)" "phone number"
-
- "@" " " "(mail=%v)" "email address"
-
- "^.[. _].*" ". _" "(cn=%v1* %v2-)" "first initial"
-
- ".*[. _].$" ". _" "(cn=%v1-*)" "last initial"
-
- "[. _]" ". _" "(|(sn=%v1-)(cn=%v1-))" "exact"
- "(|(sn~=%v1-)(cn~=%v1-))" "approximate"
-
- ".*" ". " "(|(cn=%v1)(sn=%v1)(uid=%v1))" "exact"
- "(|(cn~=%v1)(sn~=%v1))" "approximate"
-
- "go500gw onelevel"
- "^..$" " " "(|(o=%v)(c=%v)(l=%v)(co=%v))" "exact" "onelevel"
- "(|(o~=%v)(c~=%v)(l~=%v)(co~=%v))" "approximate" "onelevel"
-
- " " " " "(|(o=%v)(l=%v)(co=%v)" "exact" "onelevel"
- "(|(o~=%v)(l~=%v)(co~=%v)" "approximate" "onelevel"
-
- "\." " " "(associatedDomain=%v)" "exact" "onelevel"
-
- ".*" " " "(|(o=%v)(l=%v)(co=%v)" "exact" "onelevel"
- "(|(o~=%v)(l~=%v)(co~=%v)" "approximate" "onelevel"
-.fi
-.LP
-The call
-.ft B
-ldap_getfirstfilter( lfdp, "finger", "m.smith" );
-.ft
-will return an LDAPFiltInfo structure with the
-.B lfi_filter
-member containing the string
-.I (cn=m* smith)
-with the
-.B lfi_desc
-member containing the string
-.I first initial,
-and
-.B lfi_scope
-containing the value LDAP_SCOPE_SUBTREE.
-.LP
-The call
-.ft B
-ldap_getfirstfilter( lfdp, "go500gw onelevel", "umich" );
-.ft
-will return an LDAPFiltInfo structure with the
-.B lfi_filter
-member containing the string
-.I (|(o=umich)(l=umich)(co=umich)
-with the
-.B lfi_desc
-member containing the string
-.I exact,
-and
-.B lfi_scope
-containing the value LDAP_SCOPE_ONELEVEL.
-.SH FILES
-ETCDIR/ldapfilter.conf
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldap_getfilter (3)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-.TH LDAPSEARCHPREFS.CONF 5 "20 August 2000" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldapsearchprefs.conf \- configuration file for LDAP search preference routines
-.SH SYNOPSIS
-ETCDIR/ldapsearchprefs.conf
-.SH DESCRIPTION
-.LP
-The file ETCDIR/ldapsearchprefs.conf contains information used by
-the LDAP search preference routines (see ldap-searchpref(3)). Blank lines
-and lines that have a first character of `#' are treated as comments and
-ignored. Non-comment lines contain one or more tokens. Tokens are
-separated by white space, and double quotes `"' can be used to include
-white space inside a token.
-.LP
-Search preferences are typically used by LDAP-based client programs to
-specify what a user may search for, which attributes are searched, and
-which options are available to the user.
-.LP
-The first non-commment line specifies the version of the template
-information and must contain the token
-.I Version
-followed by an integer version number. E.g.,
-.nf
-.ft B
- Version 1
-.ft
-.fi
-The current version is
-.I 1,
-so the above example is always the correct opening line.
-.LP
-The remainder of the file consists of one or more search preference
-configurations.
-The first line of a search preference is a human-readable name for the
-type of object being searched for, e.g. "People" or "Organizations".
-This name is stored in the
-.I so_objtypeprompt
-member of the
-.I ldap_searchobj
-structure.
-E.g.,
-.nf
-.ft B
- "People"
-.ft
-.fi
-specifies a label for a search preference designed to find X.500
-entries for People.
-.LP
-The next line specifies a list of options for this search object. The
-only option currently allowed is "internal" which means that this search
-object should not be presented directly to a user. Options are placed in the
-.I so_options
-member of the
-.I ldap_searchobj
-structure and can be tested using the LDAP_IS_SEARCHOBJ_OPTION_SET() macro.
-Use "" if no special options are desired.
-.LP
-The next line specifes a label
-to use for "Fewer Choices" (for lack of a better term) searches. "Fewer
-Choices" searches are those where the user's input is fed to the
-ldap_filter routines to determine an appropriate filter to use. This
-contrasts with explicitly-constructed LDAP filters, or "More Choices"
-searches, where the user can explicitly construct an LDAP filter. The
-"Fewer" and "More Choices" terms derive from the maX.500, waX.500 and
-xax500 directory user agents, which offer two configurations of their
-"Find Entry" dialogs - one where the user types a search string, and the
-client code attempts to find reasonable filter(s) to use in searching
-("Fewer Choices"), and one where the user can select from several pop-up
-menus which allow complete specification of the search to be performed
-("More Choices").
-.LP
-For example:
-.nf
-.ft B
- "Search For:"
-.ft
-.fi
-can be used by LDAP client programs to label the field into which the
-user can type a "Fewer Choices" search. This information is stored in
-the
-.I so_prompt
-member of the
-.I ldap_searchobj
-structure.
-
-.LP
-The next line specifies an LDAP filter prefix to append to all "More Choices"
-searched. This is typically used to limit the types of entries returned
-to those containing a specific object class. For example:
-.nf
-.ft B
- "(&(objectClass=person)"
-.ft
-.fi
-would cause only entries containing the object class "person" to be
-returned by a search. Note that parentheses may be unbalanced here, since
-this is a filter prefix, not an entire filter. This information is
-stored in the
-.I so_filterprefix
-member of the
-.I ldap_searchobj
-structure.
-
-.LP
-The next line is an LDAP filter tag (see ldap-filter(3)) which specifies
-the set of LDAP filters to be applied for "Fewer Choices" searching.
-The line
-.nf
-.ft B
- "xax500-People"
-.ft
-.fi
-would tell the client program to use the set of LDAP filters from the
-ldap filter configuration file tagged "xax500-People". This information is
-stored in the
-.I so_filtertag
-member of the
-.I ldap_searchobj
-structure.
-
-.LP
-The next line specifies an LDAP attribute to retrieve to help the user
-choose when several entries match the search terms specified. For example:
-.nf
-.ft B
- "title"
-.ft
-.fi
-specifies that if more than one entry matches the search criteria, the
-client program should retrieve the "title" attribute that and present
-that to the user to allow them to select the appropriate entry.
-The next line specifies a label for the above attribute, e.g.
-.nf
-.ft B
- "Title:"
-.ft
-.fi
-The above information is stored in the
-.I so_defaultselectattr
-and
-.I so_defaultselecttext
-members of the
-.I ldap_searchobj
-structure. Note that these are defaults, and are intended to be overridden
-by the sa_selectattr and sa_selecttext fields of the ldap_searchattr
-data structure (see below).
-
-.LP
-The next line specifies the scope of the LDAP search to be performed.
-Acceptable values are subtree, onelevel, and base. See ldap(3) for
-more information.
-
-.LP
-The next section is a list of "More Choices" search options, terminated by
-a line containing only the string "END". Example:
-.nf
-.ft B
- "Common Name" cn 11111 "" ""
- "Surname" sn 11111 "" ""
- "Business Phone" "telephoneNumber" 11101 "" ""
- END
-.ft
-.fi
-
-Each line represents one method of searching. In this example, there
-are three ways of searching - by Common Name, by Surname, and by
-Business Phone number. The first field is the text which should be
-displayed to user. The second field is the attribute which will be
-searched. The third field is a bitmap which specifies which of the
-match types (discussed below) are permitted for this search type. A
-"1" value in a given bit position indicates that a particular
-match type is valid, and a "0" indicates that is it not valid. The
-fourth and fifth fields are, respectively, the select attribute name
-(corresponding to the sa_selectattr field of the ldap_searchattr data
-structure) and on-screen name for the select attribute (corresponding
-to the sa_selecttext field). These values are intended to override
-the so_defaultselectattr and so_defaultselecttext values, described
-above. If blank, the client software should use the default values above.
-
-.LP
-The next section is a list of search match options, terminated by a
-a line containing only the string "END". Example:
-.nf
-.ft B
- "exactly matches" "(%a=%v))"
- "approximately matches" "(%a~=%v))"
- "starts with" "(%a=%v*))"
- "ends with" "(%a=*%v))"
- "contains" "(%a=*%v*))"
- END
-.ft
-.fi
-In this example, there are five ways of refining the search. For each method,
-there is an LDAP filter suffix which is appended to the ldap filter thus
-far constructed. The routine ldap_build_filter() may be used to construct
-the whole filter. It substitutes the appropriate attribute for "%a" in the
-filter, and a value (generally, something the user types) for "%v".
-
-.SH EXAMPLE
-The following example illustrates one possible configuration of search
-preferences for "people".
-.LP
-.nf
-# Version number
-Version 1
-# Name for this search object
-People
-# Label to place before text box user types in
-"Search For:"
-# Filter prefix to append to all "More Choices" searches
-"(&(objectClass=person)"
-# Tag to use for "Fewer Choices" searches - from ldapfilter.conf file
-"xax500-People"
-# If a search results in > 1 match, retrieve this attribute to help
-# user disambiguate the entries...
-multilineDescription
-# ...and label it with this string:
-"Description"
-# Search scope to use when searching
-subtree
-# Follows a list of "More Choices" search options. Format is:
-# Label, attribute, select-bitmap, extra attr display name, extra attr ldap name
-# If last two are null, "Fewer Choices" name/attributes used
-"Common Name" cn 11111 "" ""
-"Surname" sn 11111 "" ""
-"Business Phone" "telephoneNumber" 11101 "" ""
-"E-Mail Address" "mail" 11111 "" ""
-"Uniqname" "uid" 11111 "" ""
-END
-# Match types
-"exactly matches" "(%a=%v))"
-"approximately matches" "(%a~=%v))"
-"starts with" "(%a=%v*))"
-"ends with" "(%a=*%v))"
-"contains" "(%a=*%v*))"
-END
-.fi
-.LP
-In this example, the user may search for People. For "fewer choices" searching,
-the tag for the ldap filter config file is "xax500-People".
-.SH FILES
-ETCDIR/ldapsearchprefs.conf
-.SH SEE ALSO
-.BR ldap (3).
-.BR ldap-searchprefs (3)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
+++ /dev/null
-.TH LDAPTEMPLATES.CONF 5 "20 August 2000" "OpenLDAP LDVERSION"
-.\" $OpenLDAP$
-.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
-.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
-.SH NAME
-ldaptemplates.conf \- configuration file for LDAP display template routines
-.SH SYNOPSIS
-ETCDIR/ldaptemplates.conf
-.SH DESCRIPTION
-.LP
-The file ETCDIR/ldaptemplates.conf contains information used by
-the LDAP display templates routines (see ldap-disptmpl(3)). Blank lines
-and lines that have a first character of `#' are treated as comments and
-ignored. Non-comment lines contain one or more tokens. Tokens are
-separated by white space, and double quotes `"' can be used to include
-white space inside a token.
-.LP
-The first non-commment line specifies the version of the template
-information and must contain the token
-.I Version
-followed by an integer version number. E.g.,
-.nf
-.ft B
- Version 1
-.ft
-.fi
-The current version is
-.I 1,
-so the above example is always the correct opening line.
-.LP
-The remainder of the file consists of one or more display templates.
-The first two lines of the display template should each contain a single
-token that specifies singular and plural names for the template that are
-suitable for human consumption. These names are stored in the
-.I dt_name
-and
-.I dt_pluralname
-members of the
-.I ldap_disptmpl
-structure.
-E.g.,
-.nf
-.ft B
- "Person"
- "People"
-.ft
-.fi
-specifies appropriate names for a template designed to display X.500
-person information.
-.LP
-The next line specifies the name of the icon or similar element that is
-associated with this template. E.g.,
-.nf
-.ft B
- "person icon"
-.ft
-.fi
-.LP
-The next line is a blank-separated list of template options. "" can be
-used if no options are desired. Available options are: "addable" (it
-is appropriate to allow entries of this type to be added), "modrdn" (it
-is appropriate to offer the "modify rdn" operation), "altview" (this
-template is merely an alternate view of another template, typically
-used for templates pointed to be a linkaction item). E.g.,
-.nf
-.ft B
- "addable" "modrdn"
-.ft
-.fi
-.LP
-The next portion of the template is a list of X.500 object classes that
-is used to determine whether the template should be used to display a
-given entry. The object class information consists of one or more lines,
-followed by a terminating line that contains the single token
-.I END.
-Each line contains one or more object class names, all of which must be
-present in an X.500 entry for the
-.I ldap_oc2template(3)
-routine to return a pointer to this template.
-The object class information is stored in the
-.I dt_oclist
-member of the
-.I ldap_disptmpl
-structure. Multiple lines can be used to associate more than one set
-of object classes with a given template. E.g.,
-.nf
-.ft B
- umichPerson
- lblPerson
- END
-.ft
-.fi
-means that the template is appropriate for display of umichPerson entries or
-lblPerson entries.
-.LP
-Next next line after the object class list is the name of the attribute
-to authenticate as to make changes (use "" if it is appropriate to
-authenticate as the entry itself). E.g.,
-.nf
-.ft B
- "owner"
-.ft
-.fi
-.LP
-The next line is the default attribute to use when naming a new entry.
-E.g.,
-.nf
-.ft B
- "cn"
-.ft
-.fi
-.LP
-The next line is the default location under which new entries are created.
-It should be a string-represented Distringuished Name. E.g.,
-.nf
-.ft B
- "dc=example,dc=com"
-.ft
-.fi
-.LP
-The next section is a list of rules used to assign default values to new
-entries. The list should be terminated with a line that contains the
-single token
-.I END.
-Each line in this section should either begin with the token
-.I constant
-and be followed by the name of the attribute and a constant value to
-assign, or the line should begin with
-.I addersdn
-followed by the name of an attribute whose value will be the DN of the
-person who has authenticated to add the entry.
-E.g.,
-.nf
-.ft B
- constant associatedDomain umich.edu
- addersdn seeAlso
- END
-.ft
-.fi
-.LP
-The last portion of the template is a list of items to display. It
-consists of one or more lines, followed by a terminating line that
-contains the single token
-.I END.
-Each line is must begin with the token
-.I samerow
-or the token
-.I item
-.LP
-It is assumed that each item appears on a row by itself unless it was
-preceded by a
-.I samerow
-line (in which case it should be displayed on the same line as the
-previous item, if possible). Lines that begin with
-.I samerow
-should not have any other tokens on them.
-.LP
-Lines that begin with
-.I item
-must have at least three more tokens on them: an item type, a label,
-and an attribute name. Any extra tokens are taken as extra arguments
-and are stored in the
-.I ti_args
-member of the
-.I ldap_tmplitem
-structure.
-.LP
-The item type token must be one of the following strings:
-.I cis
-(for case ignore string attributes),
-.I mls
-(for multiline string attributes),
-.I mail
-(for RFC-822 conformant mail address attributes),
-.I dn
-(for distinguished name pointer attributes),
-.I bool
-(for Boolean attributes),
-.I jpeg
-(for JPEG photo attributes),
-.I jpegbtn
-(for a button that will retrieve and show a JPEG photo attribute),
-.I fax
-(for FAX T.4 format image attributes),
-.I faxbtn
-(for a button that will retrieve and show a FAX photo attribute),
-.I audiobtn
-(for audio attributes),
-.I time
-(for UTC time attributes),
-.I date
-(for UTC time attributes where only the date portion should be shown),
-.I url
-(for labeled Uniform Resource Locator attributes),
-.I searchact
-(to define an action that will do a directory search for other entries),
-.I linkact
-(to define an action which is a link to another display template). See
-the ACTIONS section below for more information on search and link actions.
-.LP
-An example of an item line for the drink attribute (displayed with
-label "Favorite Beverage"):
-.nf
-.ft B
- item cis "Favorite Beverage" drink
-.ft
-.fi
-.SH ACTIONS
-This section has not been written yet. Sorry!
-.SH EXAMPLE
-The following template configuration file contains two templates, one
-for display of people entries and one for display of contries.
-.nf
-.ft B
- #
- # LDAP display templates
- #
- # Version must be 1 for now
- #
- Version 1
-
- #
- # Person template
- "Person"
- "People"
-
- # name of the icon that is associated with this template
- "person icon"
-
- # blank-separated list of template options ("" for none)
- "addable"
-
- #
- # objectclass list
- person
- END
-
- #
- # name of attribute to authenticate as ("" means auth as this entry)
- ""
-
- #
- # default attribute name to use when forming RDN of a new entry
- #
- cn
-
- #
- # default location when adding new entries (DN; "" means no default)
- "dc=example,dc=com"
-
- #
- # rules used to define default values for new entries
- END
-
- #
- # list of items for display
- item jpegbtn "View Photo" jpegPhoto "Next Photo"
- item audiobtn "Play Sound" audio
- item cis "Also Known As" cn
- item cis "Title" title
- item mls "Work Address" postalAddress
- item cis "Work Phone" telephoneNumber
- item cis "Fax Number" facsimileTelephoneNumber
- item mls "Home Address" homePostalAddress
- item cis "Home Phone" homePhone
- item cis "User ID" uid
- item mail "E-Mail Address" mail
- item cis "Description" description
- item cis "Favorite Beverage" drink
- item dn "See Also" seeAlso
- END
-.ft
-.fi
-.SH FILES
-ETCDIR/ldaptemplates.conf
-.SH SEE ALSO
-.BR ldap (3),
-.BR ldap_disptmpl (3)
-.SH ACKNOWLEDGEMENTS
-.B OpenLDAP
-is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
-.B OpenLDAP
-is derived from University of Michigan LDAP 3.3 Release.
projects / openldap / commitdiff