Copyright Digital Equipment Corp. All rights reserved.
Encoding
The following is an example of encoding:
BerElement *ber_alloc_t(int options);
The ber_alloc_t() function constructs and returns BerElement.
The null pointer is returned on error. The options field contains
a bitwise-or of options which are to be used when generating
the encoding of this BerElement. One option is defined and must
always be supplied:
#define LBER_USE_DER 0x01
When this option is present, lengths will always be encoded
in the minimum number of octets. Note that this option does
not cause values of sets and sequences to be rearranged in
tag and byte order, so these functions are not sufficient for
generating DER output as defined in X.509 and X.680. If the
caller takes responsibility for ordering values of sets and
sequences correctly, DER output as defined in X.509 and X.680
can be produced.
Unrecognized option bits are ignored.
The BerElement returned by ber_alloc_t() is initially empty.
Calls to ber_printf() will append bytes to the end of the
BerElement.
int ber_printf(BerElement *ber, char *fmt, ... )
The ber_printf() function is used to encode a BER element in
much the same way that sprintf() works. One important difference,
though, is that state information is kept in the BER argument so
that multiple calls can be made to ber_printf() to append to the
end of the BER element. BER must be a pointer to a BerElement
returned by ber_alloc_t(). The ber_printf() function interprets
and formats its arguments according to the format string fmt.
The ber_printf() function returns -1 if there is an error during
encoding and a positive number if successful. As with sprintf(),
each character in fmt refers to an argument to ber_printf().
The format string can contain the following format characters:
t Tag. The next argument is a ber_tag_t specifying the tag
to override the next element to be written to the ber. This
works across calls. The value must contain the tag class,
constructed bit, and tag value. The tag value must fit in
a single octet (tag value is less than 32). For example, a
tag of "[3]" for a constructed type is 0xA3.
b Boolean. The next argument is a ber_int_t, containing
either 0 for FALSE or 0xff for TRUE. A boolean element
is output. If this format character is not preceded by the
't' format modifier, the tag 0x01 is used for the element.
e Enumerated. The next argument is a ber_int_t, containing
the enumerated value in the host's byte order. An
enumerated element is output. If this format character
is not preceded by the 't' format modifier, the tag 0x0A is
used for the element.
i Integer. The next argument is a ber_int_t, containing the
integer in the host's byte order. An integer element is
output. If this format character is not preceded by the 't'
format modifier, the tag 0x02 is used for the element.
B Bitstring. The next two arguments are a char * pointer
to the start of the bitstring, followed by a ber_len_t
containing the number of bits in the bitstring. A bitstring
element is output, in primitive form. If this format
character is not preceded by the 't' format modifier, the
tag 0x03 is used for the element.
n Null. No argument is required. An ASN.1 NULL element is
output. If this format character is not preceded by the 't'
format modifier, the tag 0x05 is used for the element.
o Octet string. The next two arguments are a char *, followed
by a ber_len_t with the length of the string. The string
may contain null bytes and need not by zero-terminated.
An octet string element is output, in primitive form. If
this format character is not preceded by the 't' format
modifier, the tag 0x04 is used for the element.
s Octet string. The next argument is a char * pointing
to a zero-terminated string. An octet string element
in primitive form is output, which does not include
the trailing '\0' byte. If this format character is not
preceded by the 't' format modifier, the tag 0x04 is used
for the element.
v Several octet strings. The next argument is a char **,
an array of char * pointers to zero-terminated strings.
The last element in the array must be a null pointer. The
octet strings do not include the leading SEQUENCE OF octet
strings. The 't' format modifier cannot be used with this
format character.
V Several octet strings. A NULL-terminated array of struct
berval *'s is supplied. Note that a construct like '{V}'
is required to get an actual SEQUENCE OF octet strings.
The 't' format modifier cannot be used with this format
character.
{ Begin sequence. No argument is required. If this format
character is not preceded by the 't' format modifier, the
tag 0x30 is used.
} End sequence. No argument is required. The 't' format
modifier cannot be used with this format character.
[ Begin set. No argument is required. If this format
character is not preceded by the 't' format modifier, the
tag 0x31 is used.
] End set. No argument is required. The 't' format modifier
cannot be used with this format character.
Each use of a '{' format character must be matched by a '}'
character, either later in the format string, or in the format
string of a subsequent call to ber_printf() for that BerElement.
The same applies to the '[' and ']'.
Sequences and sets nest, and implementations of this API must
maintain internal state to be able to properly calculate the
lengths.
int ber_flatten (BerElement *ber, struct berval **bvPtr);
The ber_flatten() function allocates a struct berval whose
contents are a BER encoding taken from the ber argument. The
bvPtr pointer points to the returned berval, which must be freed
using ber_bvfree(). This function returns 0 on success and -1 on
error.
The ber_flatten() API call is not present in U-M LDAP 3.3.
The use of ber_flatten() on a BerElement in which all '{' and '}'
format modifiers have not been properly matched is an error (that
is, -1 will be returned by ber_flatten() if this situation is
exists).