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

   1 .TH LBER_ENCODE 3 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ber_alloc_t, ber_flush, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- LBER simplified Basic Encoding Rules library routines for encoding
   7 .SH SYNOPSIS
   8 .B #include <lber.h>
   9 .LP
  10 .BI "BerElement *ber_alloc_t(int " options ");"
  11 .LP
  12 .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");"
  13 .LP
  14 .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);"
  15 .LP
  16 .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
  17 .LP
  18 .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");"
  19 .LP
  20 .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");"
  21 .LP
  22 .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");"
  23 .LP
  24 .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");"
  25 .LP
  26 .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");"
  27 .LP
  28 .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");"
  29 .LP
  30 .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");"
  31 .LP
  32 .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");"
  33 .LP
  34 .BI "int ber_put_seq(BerElement *" ber ");"
  35 .LP
  36 .BI "int ber_put_set(BerElement *" ber ");"
  37 .SH DESCRIPTION
  38 .LP
  39 These routines provide a subroutine interface to a simplified
  40 implementation of the Basic Encoding Rules of ASN.1.  The version
  41 of BER these routines support is the one defined for the LDAP
  42 protocol.  The encoding rules are the same as BER, except that
  43 only definite form lengths are used, and bitstrings and octet strings
  44 are always encoded in primitive form.  This
  45 man page describes the encoding routines in the lber library.  See
  46 .BR lber-decode (3)
  47 for details on the corresponding decoding routines.  Consult
  48 .BR lber-types (3)
  49 for information about types, allocators, and deallocators.
  50 .LP
  51 Normally, the only routines that need to be called by an application
  52 are
  53 .BR ber_alloc_t ()
  54 to allocate a BER element for encoding,
  55 .BR ber_printf ()
  56 to do the actual encoding, and
  57 .BR ber_flush ()
  58 to actually write the element.  The other routines are provided for those
  59 applications that need more control than
  60 .BR ber_printf ()
  61 provides.  In
  62 general, these routines return the length of the element encoded, or
  63 LBER_ERROR if an error occurred.
  64 .LP
  65 The
  66 .BR ber_alloc_t ()
  67 routine is used to allocate a new BER element.  It
  68 should be called with an argument of LBER_USE_DER.
  69 .LP
  70 The
  71 .BR ber_flush ()
  72 routine is used to actually write the element to a socket
  73 (or file) descriptor, once it has been fully encoded (using
  74 .BR ber_printf ()
  75 and friends).  See
  76 .BR lber-sockbuf (3)
  77 for more details on the Sockbuf implementation of the \fIsb\fP parameter.
  78 If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will
  79 be freed after its contents have been flushed.
  80 .LP
  81 The
  82 .BR ber_printf ()
  83 routine is used to encode a BER element in much the same way that
  84 .BR sprintf (3)
  85 works.  One important difference, though, is
  86 that some state information is kept with the \fIber\fP parameter so
  87 that multiple calls can be made to
  88 .BR ber_printf ()
  89 to append things to the end of the BER element.
  90 .BR Ber_printf ()
  91 writes to \fIber\fP, a pointer to a BerElement such as returned by
  92 .BR ber_alloc_t ().
  93 It interprets and
  94 formats its arguments according to the format string \fIfmt\fP.
  95 The format string can contain the following characters:
  96 .RS
  97 .LP
  98 .TP 3
  99 .B b
 100 Boolean.  An ber_int_t parameter should be supplied.  A boolean element
 101 is output.
 102 .TP
 103 .B e
 104 Enumeration.  An ber_int_t parameter should be supplied.  An
 105 enumeration element is output.
 106 .TP
 107 .B i
 108 Integer.  An ber_int_t parameter should be supplied.  An integer element
 109 is output.
 110 .TP
 111 .B B
 112 Bitstring.  A char * pointer to the start of the bitstring is supplied,
 113 followed by the number of bits in the bitstring.  A bitstring element
 114 is output.
 115 .TP
 116 .B n
 117 Null.  No parameter is required.  A null element is output.
 118 .TP
 119 .B o
 120 Octet string.  A char * is supplied, followed by the length of the
 121 string pointed to.  An octet string element is output.
 122 .TP
 123 .B O
 124 Octet string.  A struct berval * is supplied.
 125 An octet string element is output.
 126 .TP
 127 .B s
 128 Octet string.  A null-terminated string is supplied.  An octet string
 129 element is output, not including the trailing NULL octet.
 130 .TP
 131 .B t
 132 Tag.  A ber_tag_t specifying the tag to give the next element
 133 is provided.  This works across calls.
 134 .TP
 135 .B v
 136 Several octet strings.  A null-terminated array of char *'s is
 137 supplied.  Note that a construct like '{v}' is required to get
 138 an actual SEQUENCE OF octet strings.
 139 .TP
 140 .B V
 141 Several octet strings.  A null-terminated array of struct berval *'s
 142 is supplied.  Note that a construct like '{V}' is required to get
 143 an actual SEQUENCE OF octet strings.
 144 .TP
 145 .B W
 146 Several octet strings.  An array of struct berval's is supplied.  The
 147 array is terminated by a struct berval with a NULL bv_val.
 148 Note that a construct like '{W}' is required to get
 149 an actual SEQUENCE OF octet strings.
 150 .TP
 151 .B {
 152 Begin sequence.  No parameter is required.
 153 .TP
 154 .B }
 155 End sequence.  No parameter is required.
 156 .TP
 157 .B [
 158 Begin set.  No parameter is required.
 159 .TP
 160 .B ]
 161 End set.  No parameter is required.
 162 .RE
 163 .LP
 164 The
 165 .BR ber_put_int ()
 166 routine writes the integer element \fInum\fP to the BER element \fIber\fP.
 167 .LP
 168 The
 169 .BR ber_put_enum ()
 170 routine writes the enumeration element \fInum\fP to the BER element \fIber\fP.
 171 .LP
 172 The
 173 .BR ber_put_boolean ()
 174 routine writes the boolean value given by \fIbool\fP to the BER element.
 175 .LP
 176 The
 177 .BR ber_put_bitstring ()
 178 routine writes \fIblen\fP bits starting
 179 at \fIstr\fP as a bitstring value to the given BER element.  Note
 180 that \fIblen\fP is the length \fIin bits\fP of the bitstring.
 181 .LP
 182 The
 183 .BR ber_put_ostring ()
 184 routine writes \fIlen\fP bytes starting at
 185 \fIstr\fP to the BER element as an octet string.
 186 .LP
 187 The
 188 .BR ber_put_string ()
 189 routine writes the null-terminated string (minus
 190 the terminating '\0') to the BER element as an octet string.
 191 .LP
 192 The
 193 .BR ber_put_null ()
 194 routine writes a NULL element to the BER element.
 195 .LP
 196 The
 197 .BR ber_start_seq ()
 198 routine is used to start a sequence in the BER element.  The
 199 .BR ber_start_set ()
 200 routine works similarly.
 201 The end of the sequence or set is marked by the nearest matching call to
 202 .BR ber_put_seq ()
 203 or
 204 .BR ber_put_set (),
 205 respectively.
 206 .SH EXAMPLES
 207 Assuming the following variable declarations, and that the variables
 208 have been assigned appropriately, an lber encoding of
 209 the following ASN.1 object:
 210 .LP
 211 .nf
 212       AlmostASearchRequest := SEQUENCE {
 213           baseObject      DistinguishedName,
 214           scope           ENUMERATED {
 215               baseObject    (0),
 216               singleLevel   (1),
 217               wholeSubtree  (2)
 218           },
 219           derefAliases    ENUMERATED {
 220               neverDerefaliases   (0),
 221               derefInSearching    (1),
 222               derefFindingBaseObj (2),
 223               alwaysDerefAliases  (3)
 224           },
 225           sizelimit       INTEGER (0 .. 65535),
 226           timelimit       INTEGER (0 .. 65535),
 227           attrsOnly       BOOLEAN,
 228           attributes      SEQUENCE OF AttributeType
 229       }
 230 .fi
 231 .LP
 232 can be achieved like so:
 233 .LP
 234 .nf
 235       int rc;
 236       ber_int_t    scope, ali, size, time, attrsonly;
 237       char   *dn, **attrs;
 238       BerElement *ber;
 239
 240       /* ... fill in values ... */
 241
 242       ber = ber_alloc_t( LBER_USE_DER );
 243
 244       if ( ber == NULL ) {
 245                 /* error */
 246       }
 247
 248       rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali,
 249           size, time, attrsonly, attrs );
 250
 251       if( rc == LBER_ERROR ) {
 252               /* error */
 253       } else {
 254               /* success */
 255       }
 256 .fi
 257 .SH ERRORS
 258 If an error occurs during encoding, generally these routines return LBER_ERROR.
 259 .LP
 260 .SH NOTES
 261 .LP
 262 The return values for all of these functions are declared in the
 263 <lber.h> header file.
 264 .SH SEE ALSO
 265 .BR lber-decode (3),
 266 .BR lber-memory (3),
 267 .BR lber-sockbuf (3),
 268 .BR lber-types (3)
 269 .SH ACKNOWLEDGEMENTS
 270 .B      OpenLDAP
 271 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 272 .B      OpenLDAP
 273 is derived from University of Michigan LDAP 3.3 Release.