git.sur5r.net Git - openldap/blob - doc/man/man3/ldap_entry2text.3

   1 .TH LDAP_ENTRY2TEXT 3 "22 September 1998" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-1999 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldap_entry2text, ldap_entry2text_search, ldap_vals2text \- LDAP entry display routines
   7 .SH SYNOPSIS
   8 .nf
   9 .ft B
  10 #include <ldap.h>
  11 #include <disptmpl.h>
  12 .ft
  13 .LP
  14 .ft B
  15 int ldap_entry2text( ld, buf, entry, tmpl, defattrs, defvals, writeproc,
  16     writeparm, eol, rdncount, opts )
  17 .ft
  18         LDAP                    *ld;
  19         char                    *buf;
  20         LDAPMessage             *entry;
  21         struct ldap_disptmpl    *tmpl;
  22         char                    **defattrs;
  23         char                    ***defvals;
  24         int                     (*writeproc)();
  25         void                    *writeparm;
  26         char                    *eol;
  27         int                     rdncount;
  28         unsigned long           opts;
  29 .LP
  30 .ft B
  31 int ldap_entry2text_search( ld, entry, tmpllist, defattrs, defvals,
  32     writeproc, writeparm, eol, rdncount, opts )
  33 .ft
  34         LDAP                    *ld;
  35         char                    *dn;
  36         char                    *base;
  37         LDAPMessage             *entry;
  38         struct ldap_disptmpl    *tmpllist;
  39         char                    **defattrs;
  40         char                    ***defvals;
  41         int                     (*writeproc)();
  42         void                    *writeparm;
  43         char                    *eol;
  44         int                     rdncount;
  45         unsigned long           opts;
  46 .LP
  47 .ft B
  48 int ldap_vals2text( ld, buf, vals, label, labelwidth, syntaxid, writeproc,
  49     writeparm, eol, rdncount )
  50 .ft
  51         LDAP                    *ld;
  52         char                    *buf;
  53         char                    **vals;
  54         char                    *label;
  55         int                     labelwidth;
  56         unsigned long           syntaxid;
  57         int                     (*writeproc)();
  58         void                    *writeparm;
  59         char                    *eol;
  60         int                     rdncount;
  61 .LP
  62 .ft B
  63 int ldap_entry2html( ld, buf, entry, tmpl, defattrs, defvals, writeproc,
  64     writeparm, eol, rdncount, opts )
  65 .ft
  66         LDAP                    *ld;
  67         char                    *buf;
  68         LDAPMessage             *entry;
  69         struct ldap_disptmpl    *tmpl;
  70         char                    **defattrs;
  71         char                    ***defvals;
  72         int                     (*writeproc)();
  73         void                    *writeparm;
  74         char                    *eol;
  75         int                     rdncount;
  76         unsigned long           opts;
  77         char                    *urlprefix;
  78         char                    *base;
  79 .LP
  80 .ft B
  81 int ldap_entry2html_search( ld, entry, tmpllist, defattrs, defvals,
  82     writeproc, writeparm, eol, rdncount, opts )
  83 .ft
  84         LDAP                    *ld;
  85         char                    *dn;
  86         LDAPMessage             *entry;
  87         struct ldap_disptmpl    *tmpllist;
  88         char                    **defattrs;
  89         char                    ***defvals;
  90         int                     (*writeproc)();
  91         void                    *writeparm;
  92         char                    *eol;
  93         int                     rdncount;
  94         unsigned long           opts;
  95         char                    *urlprefix;
  96 .LP
  97 .ft B
  98 int ldap_vals2html( ld, buf, vals, label, labelwidth, syntaxid, writeproc,
  99     writeparm, eol, rdncount )
 100 .ft
 101         LDAP                    *ld;
 102         char                    *buf;
 103         char                    **vals;
 104         char                    *label;
 105         int                     labelwidth;
 106         unsigned long           syntaxid;
 107         int                     (*writeproc)();
 108         void                    *writeparm;
 109         char                    *eol;
 110         int                     rdncount;
 111         char                    *urlprefix;
 112 .LP
 113 .ft B
 114
 115
 116 #define LDAP_DISP_OPT_AUTOLABELWIDTH    0x00000001
 117 #define LDAP_DISP_OPT_HTMLBODYONLY      0x00000002
 118
 119 #define LDAP_DTMPL_BUFSIZ               2048
 120 .ft
 121 .fi
 122 .SH DESCRIPTION
 123 These functions use the LDAP display template routines (see
 124 ldap_disptmpl(3) and ldap_templates.conf(5)) to produce a plain text
 125 or an HyperText Markup Language (HTML) display of an entry or a set of
 126 values.  Typical plain text output produced for an entry might look like:
 127 .nf
 128
 129     "Barbara J Jensen, Information Technology Division"
 130      Also Known As:
 131                    Babs Jensen
 132                    Barbara Jensen
 133                    Barbara J Jensen
 134      E-Mail Address:
 135                    bjensen@terminator.rs.itd.umich.edu
 136      Work Address:
 137                    535 W. William
 138                    Ann Arbor, MI 48103
 139      Title:
 140                    Mythical Manager, Research Systems
 141      ...
 142 .fi
 143 The exact output produced will depend on the display template configuration.
 144 HTML output is similar to the plain text output, but more richly formatted.
 145 .LP
 146 .B ldap_entry2text(\|)
 147 produces a text representation of
 148 .I entry
 149 and writes the text by calling the
 150 .I writeproc
 151 function.  All of the attributes values to be displayed must be present
 152 in
 153 .I entry;
 154 no interaction with the LDAP server will be performed within
 155 .B ldap_entry2text.
 156 .I ld
 157 is the LDAP pointer obtained by a previous call to
 158 .B ldap_open.
 159 .I writeproc
 160 should be declared as:
 161 .LP
 162 .ft B
 163 .nf
 164 int writeproc( writeparm, p, len )
 165 .ft
 166         void            *writeparm;
 167         char            *p;
 168         int             len;
 169 .fi
 170 .LP
 171 where
 172 .I p
 173 is a pointer to text to be written and
 174 .I len
 175 is the length of the text.
 176 .I p
 177 is guaranteed to be zero-terminated.  Lines of text are terminated
 178 with the string
 179 .I eol.
 180 .I buf
 181 is a pointer to a buffer of size
 182 .B LDAP_DTMPL_BUFSIZ
 183 or larger.  If
 184 .I buf is
 185 .B NULL
 186 then a buffer is allocated and freed internally.
 187 .I tmpl
 188 is a pointer to the display template to be used (usually obtained by calling
 189 .B ldap_oc2template).
 190 If
 191 .I tmpl
 192 is NULL,
 193 no template is used and a generic display is produced.
 194 .I defattrs
 195 is a NULL-terminated array of LDAP attribute names which you wish to
 196 provide default values for (only used if
 197 .I entry
 198 contains no values for the attribute).  An array of NULL-terminated arrays of
 199 default values corresponding to the attributes should be passed in
 200 .I defvals.  The
 201 .I rdncount
 202 parameter is used to limit the number of Distinguished Name (DN) components
 203 that are actually displayed for DN attributes.  If
 204 .I rdncount
 205 is zero, all components are shown.
 206 .I opts
 207 is used to specify output options.  The only values currently allowed
 208 are zero (default output),
 209 .B LDAP_DISP_OPT_AUTOLABELWIDTH
 210 which causes the width for labels to be determined based on the longest
 211 label in
 212 .I tmpl, and
 213 .B LDAP_DISP_OPT_HTMLBODYONLY.
 214 The
 215 .B LDAP_DISP_OPT_HTMLBODYONLY
 216 option instructs the library not to include <HTML>, <HEAD>, <TITLE>, and
 217 <BODY> tags.  In other words, an HTML fragment is generated, and the
 218 caller is responsible for prepending and appending the appropriate HTML
 219 tags to construct a correct HTML document.
 220 .LP
 221 .B ldap_entry2text_search(\|)
 222 is similar to
 223 .B ldap_entry2text,
 224 and all of the like-named parameters have the same meaning except as noted
 225 below.
 226 If
 227 .I base
 228 is not NULL, it is the search base to use when executing search actions.  If
 229 it is NULL, search action template items are ignored.  If
 230 .I entry
 231 is not NULL, it should contain the
 232 .I objectClass
 233 attribute values for the entry to be displayed.  If
 234 .I entry
 235 is NULL,
 236 .I dn
 237 must not be NULL, and
 238 .B ldap_entry2text_search
 239 will retrieve the objectClass values itself by calling
 240 .B ldap_search_s.
 241 .B ldap_entry2text_search
 242 will determine the appropriate display template to use by calling
 243 .B ldap_oc2template,
 244 and will call
 245 .B ldap_search_s
 246 to retrieve any attribute values to be displayed.  The
 247 .I tmpllist
 248 parameter is a pointer to the entire list of templates available (usually
 249 obtained by calling
 250 .B ldap_init_templates
 251 or
 252 .B ldap_init_templates_buf).
 253 If
 254 .I tmpllist
 255 is NULL,
 256 .B ldap_entry2text_search
 257 will attempt to read a load templates from the default template configuration
 258 file ETCDIR/ldaptemplates.conf.
 259 .LP
 260 .B ldap_vals2text
 261 produces a text representation of a single set of LDAP attribute values.  The
 262 .I ld,
 263 .I buf,
 264 .I writeproc,
 265 .I writeparm,
 266 .I eol,
 267 and
 268 .I rdncount
 269 parameters are the same as the like-named parameters for
 270 .B ldap_entry2text.
 271 .I vals
 272 is a NULL-terminated list of values, usually obtained by a call to
 273 .B ldap_get_values.
 274 .I label
 275 is a string shown next to the values (usually a friendly form of an
 276 LDAP attribute name).
 277 .I labelwidth
 278 specifies the label margin, which is the number of blank spaces displayed
 279 to the left of the values.  If zero is passed, a default label width is
 280 used.
 281 .I syntaxid
 282 is a display template attribute syntax identifier (see ldap_disptmpl(3)
 283 for a list of the pre-defined
 284 .B LDAP_SYN_...
 285 values).
 286 .LP
 287 .B ldap_entry2html
 288 produces an HTML representation of
 289 .I entry.
 290 It behaves exactly like ldap_entry2text(3), except for the formatted output
 291 and the addition of two parameters.
 292 .I urlprefix
 293 is the starting text to use when constructing an LDAP URL.  The default is
 294 the string
 295 .I ldap:///
 296 The second additional parameter,
 297 .I base,
 298 the search base to use when executing search actions.  If it is NULL, search
 299 action template items are ignored.
 300 .LP
 301 .B ldap_entry2html_search
 302 behaves exactly like ldap_entry2text_search(3), except HTML output is produced
 303 and one additional parameter is required.
 304 .I urlprefix
 305 is the starting text to use when constructing an LDAP URL.  The default is
 306 the string
 307 .I ldap:///
 308 .LP
 309 .B ldap_vals2html
 310 behaves exactly like ldap_vals2text, except HTML output is produced
 311 and one additional parameter is required.
 312 .I urlprefix
 313 is the starting text to use when constructing an LDAP URL.  The default is
 314 the string
 315 .I ldap:///
 316 .SH ERRORS
 317 These routines all return an LDAP error code (LDAP_SUCCESS is returned
 318 if no error occurs).  See ldap_error(3) for details. The
 319 .I ld_errno
 320 field of the
 321 .I ld
 322 parameter is also set to indicate the error.
 323 .SH FILES
 324 ETCDIR/ldaptemplates.conf
 325 .SH SEE ALSO
 326 .BR ldap (3),
 327 .BR ldap_disptmpl (3),
 328 .BR ldaptemplates.conf (5)
 329 .SH ACKNOWLEDGEMENTS
 330 .B      OpenLDAP
 331 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 332 .B      OpenLDAP
 333 is derived from University of Michigan LDAP 3.3 Release.