usr/src/man/man3ldap/ldap_entry2text.3ldap

   1 '\" te
   2 .\" Copyright (C) 1990, Regents of the University of Michigan.  All Rights Reserved.
   3 .\" Portions Copyright (C) 2002, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH LDAP_ENTRY2TEXT 3LDAP "Jan 27, 2002"
   8 .SH NAME
   9 ldap_entry2text, ldap_entry2text_search, ldap_entry2html,
  10 ldap_entry2html_search, ldap_vals2html, ldap_vals2text \- LDAP entry display
  11 functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc[ \fIflag\fR... ] \fIfile\fR... -lldap[ \fIlibrary\fR... ]
  16 #include <lber.h>
  17 #include <ldap.h>
  18
  19 \fBint\fR \fBldap_entry2text\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBLDAPMessage\fR \fI*entry\fR,
  20      \fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR,
  21      \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR,
  22      \fBunsigned long\fR \fIopts\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBint\fR \fBldap_entry2text_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBchar\fR \fI*base\fR,
  28      \fBLDAPMessage\fR \fI*entry\fR, \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR,
  29      \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR, \fBint (\fR\fI*writeproc\fR)(),
  30      \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR,\fBint\fR \fIrdncount\fR,
  31      \fBunsigned long\fR \fIopts\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBldap_vals2text\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBchar\fR \fI**vals\fR, \fBchar\fR \fI*label\fR,
  37      \fBint\fR \fIlabelwidth\fR, \fBunsigned long\fR\fIsyntaxid\fR, \fBint (\fR\fI*writeproc\fR)(),
  38      \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBldap_entry2html\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBLDAPMessage\fR \fI*entry\fR,
  44      \fBstruct ldap_disptmpl\fR \fI*tmpl\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR,
  45      \fBint (\fR\fI*writeproc\fR)(),\fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR,
  46      \fBunsigned long\fR \fIopts\fR, \fBchar\fR \fI*urlprefix\fR, \fBchar\fR \fI*base\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBint\fR \fBldap_entry2html_search\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*dn\fR, \fBLDAPMessage\fR \fI*entry\fR,
  52      \fBstruct ldap_disptmpl\fR \fI*tmpllist\fR, \fBchar\fR \fI**defattrs\fR, \fBchar\fR \fI***defvals\fR,
  53      \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR,
  54      \fBunsigned long\fR \fIopts\fR, \fBchar\fR \fI*urlprefix\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBint\fR \fBldap_vals2html\fR(\fBLDAP\fR \fI*ld\fR, \fBchar\fR \fI*buf\fR, \fBchar\fR \fI**vals\fR,
  60      \fBchar\fR \fI*label\fR, \fBint\fR \fIlabelwidth\fR, \fBunsigned long\fR \fIsyntaxid\fR,
  61      \fBint (\fR\fI*writeproc\fR)(), \fBvoid\fR \fI*writeparm\fR, \fBchar\fR \fI*eol\fR, \fBint\fR \fIrdncount\fR,
  62      \fBchar\fR \fI*urlprefix\fR);
  63 .fi
  64
  65 .LP
  66 .nf
  67 #define LDAP_DISP_OPT_AUTOLABELWIDTH 0x00000001
  68 .fi
  69
  70 .LP
  71 .nf
  72 #define LDAP_DISP_OPT_HTMLBODYONLY      0x00000002
  73 .fi
  74
  75 .LP
  76 .nf
  77 #define LDAP_DTMPL_BUFSIZ  2048
  78 .fi
  79
  80 .SH DESCRIPTION
  81 .sp
  82 .LP
  83 These functions use the LDAP display template functions (see
  84 \fBldap_disptmpl\fR(3LDAP) and  \fBldap_templates.conf(4))\fR to produce a
  85 plain text or an HyperText Markup Language (HTML) display of an entry or a set
  86 of values.  Typical plain text output produced for an entry might look like:
  87 .sp
  88 .in +2
  89 .nf
  90     "Barbara J Jensen, Information Technology Division"
  91      Also Known As:
  92      Babs Jensen
  93      Barbara Jensen
  94      Barbara J Jensen
  95      E-Mail Address:
  96      bjensen@terminator.rs.itd.umich.edu
  97      Work Address:
  98      535 W. William
  99      Ann Arbor, MI 48103
 100      Title:
 101      Mythical Manager, Research Systems
 102      ...
 103 .fi
 104 .in -2
 105
 106 .sp
 107 .LP
 108 The exact output produced will depend on the display template configuration.
 109 HTML output is similar to the plain text output, but more richly formatted.
 110 .sp
 111 .LP
 112 \fBldap_entry2text()\fR produces a text representation of \fIentry\fR and
 113 writes the text by calling the \fIwriteproc\fR function.  All of the attributes
 114 values to be displayed must be present in \fIentry;\fR no interaction with the
 115 LDAP server will be performed within \fBldap_entry2text\fR. \fBld\fR is the
 116 LDAP pointer obtained by a previous call to \fBldap_open.\fR \fIwriteproc\fR
 117 should be declared as:
 118 .sp
 119 .in +2
 120 .nf
 121 int writeproc( writeparm, p, len )
 122  void  *writeparm;
 123  char  *p;
 124  int  len;
 125 .fi
 126 .in -2
 127
 128 .sp
 129 .LP
 130 where \fIp\fR is a pointer to text to be written and \fIlen\fR is the length of
 131 the text. \fIp\fR is guaranteed to be zero-terminated.  Lines of text are
 132 terminated with the string \fIeol.\fR \fIbuf\fR is a pointer to a buffer of
 133 size \fBLDAP_DTMPL_BUFSIZ\fR or larger.  If \fIbuf\fR \fIis\fR \fINULL\fR then
 134 a buffer is allocated and freed internally. \fItmpl\fR is a pointer to the
 135 display template to be used (usually obtained by calling
 136 \fBldap_oc2template\fR). If \fItmpl\fR is \fINULL\fR, no template is used and a
 137 generic display is produced. \fIdefattrs\fR is a NULL-terminated array of LDAP
 138 attribute names which you wish to provide default values for (only used if
 139 \fIentry\fR contains no values for the attribute).  An array of NULL-terminated
 140 arrays of default values corresponding to the attributes should be passed in
 141 \fIdefvals.\fR \fIThe\fR \fIrdncount\fR parameter is used to limit the number
 142 of Distinguished Name (DN) components that are actually displayed for DN
 143 attributes.  If \fIrdncount\fR is zero, all components are shown. \fIopts\fR is
 144 used to specify output options.  The only values currently allowed are zero
 145 (default output), \fBLDAP_DISP_OPT_AUTOLABELWIDTH\fR which causes the width for
 146 labels to be determined based on the longest label in \fItmpl,\fR \fIand\fR
 147 \fBLDAP_DISP_OPT_HTMLBODYONLY\fR. The \fBLDAP_DISP_OPT_HTMLBODYONLY\fR option
 148 instructs the library not to include <HTML>, <HEAD>, <TITLE>, and <BODY> tags.
 149 In other words, an HTML fragment is generated, and the caller is responsible
 150 for prepending and appending the appropriate HTML tags to construct a correct
 151 HTML document.
 152 .sp
 153 .LP
 154 \fBldap_entry2text_search()\fR is similar to \fBldap_entry2text\fR, and all of
 155 the like-named parameters have the same meaning except as noted below.   If
 156 \fIbase\fR is not \fINULL\fR, it is the search base to use when executing
 157 search actions.  If it is \fINULL\fR, search action template items are ignored.
 158 If \fIentry\fR is not \fINULL\fR, it should contain the \fIobjectClass\fR
 159 attribute values for the entry to be displayed.  If \fIentry\fR is \fINULL\fR,
 160 \fIdn\fR must not be \fINULL\fR, and  \fBldap_entry2text_search\fR will
 161 retrieve the  \fBobjectClass\fR values itself by calling \fBldap_search_s.\fR
 162 \fBldap_entry2text_search\fR will determine the appropriate display template to
 163 use by calling \fBldap_oc2template\fR, and will call \fBldap_search_s\fR to
 164 retrieve any attribute values to be displayed.  The \fItmpllist\fR parameter is
 165 a pointer to the entire list of templates available (usually obtained by
 166 calling \fBldap_init_templates\fR or \fBldap_init_templates_buf\fR). If
 167 \fItmpllist\fR is \fINULL\fR, \fBldap_entry2text_search\fR will attempt to read
 168 a load templates from the default template configuration file
 169 \fBETCDIR/ldaptemplates.conf\fR
 170 .sp
 171 .LP
 172 \fBldap_vals2text\fR produces a text representation of a single set of LDAP
 173 attribute values.  The \fIld,\fR \fIbuf,\fR \fIwriteproc,\fR \fIwriteparm,\fR
 174 \fIeol,\fR and \fIrdncount\fR parameters are the same as the like-named
 175 parameters for \fBldap_entry2text\fR. \fIvals\fR is a NULL-terminated list of
 176 values, usually obtained by a call to \fBldap_get_values\fR. \fIlabel\fR is a
 177 string shown next to the values (usually a friendly form of an LDAP attribute
 178 name). \fIlabelwidth\fR specifies the label margin, which is the number of
 179 blank spaces displayed to the left of the values. If zero is passed, a default
 180 label width is used. \fIsyntaxid\fR is a display template attribute syntax
 181 identifier (see  \fBldap_disptmpl\fR(3LDAP) for a list of the pre-defined
 182 \fBLDAP_SYN_...\fR values).
 183 .sp
 184 .LP
 185 \fBldap_entry2html\fR produces an HTML representation of \fIentry.\fR It
 186 behaves exactly like ldap_entry2text(3LDAP), except for the formatted output
 187 and the addition of two parameters. \fIurlprefix\fR is the starting text to use
 188 when constructing an LDAP URL.  The default is the string \fIldap:///\fR The
 189 second additional parameter, \fIbase,\fR the search base to use when executing
 190 search actions.  If it is  \fINULL\fR, search action template items are
 191 ignored.
 192 .sp
 193 .LP
 194 \fBldap_entry2html_search\fR behaves exactly like
 195 \fBldap_entry2text_search\fR(3LDAP), except HTML output is produced and one
 196 additional parameter is required. \fIurlprefix\fR is the starting text to use
 197 when constructing an LDAP URL.  The default is the string \fIldap:///\fR
 198 .sp
 199 .LP
 200 \fBldap_vals2html\fR behaves exactly like
 201 \fBldap_vals2text\fR,\fBexcept\fRHTML\fBoutput\fRis and one additional
 202 parameter is required. \fIurlprefix\fR is the starting text to use when
 203 constructing an LDAP URL. The default is the string \fIldap:///\fR
 204 .SH ERRORS
 205 .sp
 206 .LP
 207 These functions all return an LDAP error code. \fBLDAP_SUCCESS\fR is returned
 208 if no error occurs. See \fBldap_error\fR(3LDAP) for details. The \fIld_errno\fR
 209 field of the \fIld\fR parameter is also set to indicate the error.
 210 .SH FILES
 211 .sp
 212 .LP
 213 \fBETCDIR/ldaptemplates.conf\fR
 214 .SH ATTRIBUTES
 215 .sp
 216 .LP
 217 See \fBattributes\fR(5) for a description of the following attributes:
 218 .sp
 219
 220 .sp
 221 .TS
 222 box;
 223 c | c
 224 l | l .
 225 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 226 Interface Stability     Evolving
 227 .TE
 228
 229 .SH SEE ALSO
 230 .sp
 231 .LP
 232 \fBldap\fR(3LDAP), \fBldap_disptmpl\fR(3LDAP), \fBldaptemplates.conf\fR(4) ,
 233 \fBattributes\fR(5)