Copyright Digital Equipment Corp. All rights reserved.
Decoding
The following two symbols are available to applications.
#define LBER_ERROR 0xffffffffL
#define LBER_DEFAULT 0xffffffffL
BerElement *ber_init (struct berval *bv);
The ber_init() function constructs a BerElement and returns a new
BerElement containing a copy of the data in the bv argument. The
ber_init() function returns the null pointer on error.
ber_tag_t ber_scanf (BerElement *ber, char *fmt, ... );
The ber_scanf() function is used to decode a BER element in much
the same way that sscanf() works. One important difference,
though, is that some state information is kept with the ber
argument so that multiple calls can be made to ber_scanf() to
sequentially read from the BER element. The ber argument must
be a pointer to a BerElement returned by ber_init(). The ber_
scanf() function interprets function the bytes according to
the format string fmt, and stores the results in its additional
arguments. The ber_scanf() function returns LBER_ERROR on error,
and a different value on success.
The format string contains conversion specifications which are
used to direct the interpretation of the BER element. The format
string can contain the following characters:
a Octet string. A char ** argument should be supplied. Memory
is allocated, filled with the contents of the octet string,
null- terminated, and the pointer to the string is stored
in the argument. The returned value must be freed using
ldap_memfree(). The tag of the element must indicate the
primitive form (constructed strings are not supported) but
is otherwise ignored and discarded during the decoding.
This format cannot be used with octet strings which could
contain null bytes.
O Octet string. A struct berval ** argument should be
supplied, which upon return points to a allocated struct
berval containing the octet string and its length. The
ber_bvfree() function must be called to free the allocated
memory. The tag of the element must indicate the primitive
form (constructed strings are not supported) but is
otherwise ignored during the decoding.
b Boolean. A pointer to a ber_int_t should be supplied. The
value stored will be 0 for FALSE or nonzero for TRUE. The
tag of the element must indicate the primitive form but is
otherwise ignored during the decoding.
e Enumerated value stored will be in host byte order. The
tag of the element must indicate the primitive form but is
otherwise ignored during the decoding. The ber_scanf()
function will return an error if the enumerated value
cannot be stored in a ber_int_t.
i Integer. A pointer to a ber_int_t should be supplied. The
value stored will be in host byte order. The tag of the
element must indicate the primitive form but is otherwise
ignored during the decoding. The ber_scanf() function will
return an error if the integer cannot be stored in a ber_
int_t.
B Bitstring. A char ** argument should be supplied which
will point to the allocated bits, followed by a ber_len_t *
argument, which will point to the length (in bits) of the
bit-string returned. The ldap_memfree() function must be
called to free the bit-string. The tag of the element must
indicate the primitive form (constructed bitstrings are not
supported) but is otherwise ignored during the decoding.
n Null. No argument is required. The element is simply
skipped if it is recognized as a zero-length element. The
tag is ignored.
v Several octet strings. A char *** argument should be
supplied, which upon return points to a allocated null-
terminated array of char *'s containing the octet strings.
NULL is stored if the sequence is empty. The ldap_
memfree() function must be called to free each element
of the array and the array itself. The tag of the sequence
and of the octet strings are ignored.
V Several octet strings (which could contain null bytes).
A struct berval *** should be supplied, which upon
return points to a allocated null-terminated array of
struct berval *'s containing the octet strings and their
lengths. NULL is stored if the sequence is empty. The ber_
bvecfree() function can be called to free the allocated
memory. The tag of the sequence and of the octet strings
are ignored.
x Skip element. The next element is skipped. No argument is
required.
{ Begin sequence. No argument is required. The initial
sequence tag and length are skipped.
} End sequence. No argument is required.
[ Begin set. No argument is required. The initial set tag and
length are skipped.
] End set. No argument is required.
ber_tag_t ber_peek_tag (BerElement *ber, ber_len_t *lenPtr);
The ber_peek_tag() function returns the tag of the next element
to be parsed in the BerElement argument. The length of this
element is stored in the *lenPtr argument. LBER_DEFAULT is
returned if there is no further data to be read. The ber argument
is not modified.
ber_tag_t ber_skip_tag (BerElement *ber, ber_len_t *lenPtr);
The ber_skip_tag() function is similar to ber_peek_tag(), except
that the state pointer in the BerElement argument is advanced
past the first tag and length, and is pointed to the value part
of the next element. This function should only be used with
constructed types and situations when a BER encoding is used as
the value of an OCTET STRING. The length of the value is stored
in *lenPtr.
ber_tag_t ber_first_element(BerElement *ber,
ber_len_t *lenPtr, char **opaquePtr);
ber_tag_t ber_next_element (BerElement *ber,
ber_len_t *lenPtr, char *opaque);
The ber_first_element() and ber_next_element() functions are
used to traverse a SET, SET OF, SEQUENCE or SEQUENCE OF data
value. The ber_first_element() function calls ber_skip_tag(),
stores internal information in *lenPtr and *opaquePtr, and calls
ber_peek_tag() for the first element inside the constructed
value. LBER_DEFAULT is returned if the constructed value is
empty. The ber_next_element() function positions the state at the
start of the next element in the constructed type. LBER_DEFAULT
is returned if there are no further values.
The len and opaque values should not be used by applications
other than as arguments to ber_next_element(). (Refer to the VSI
OpenVMS Utility Routines Manual for an example of this usage.)