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

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