LBERENCODE(3) LBERENCODE(3)
NAME
beralloct, berflush, berprintf, berputint, berputenum,
berputostring, berputstring, berputnull, berputboolean,
berputbitstring, berstartseq, berstartset, berputseq,
berputset - LBER simplified Basic Encoding Rules library routines for
encoding
LIBRARY
OpenLDAP LBER (liblber, -llber)
SYNOPSIS
##include <>
BerElement **beralloct(int options);;
int berflush(Sockbuf **sb,, BerElement **ber,, int freeit);;
int berprintf(BerElement **ber,, const char **fmt,, ...);;
int berputint(BerElement **ber,, berintt num,, bertagt tag);;
int berputenum(BerElement **ber,, berintt num,, bertagt tag);;
int berputostring(BerElement **ber,, const char **str,, berlent len,,
bertagt tag);;
int berputstring(BerElement **ber,, const char **str,, bertagt tag);;
int berputnull(BerElement **ber,, bertagt tag);;
int berputboolean(BerElement **ber,, berintt bool,, bertagt tag);;
int berputbitstring(BerElement **ber,, const char **str,, berlent blen,,
bertagt tag);;
int berstartseq(BerElement **ber,, bertagt tag);;
int berstartset(BerElement **ber,, bertagt tag);;
int berputseq(BerElement **ber);;
int berputset(BerElement **ber);;
DESCRIPTION
These routines provide a subroutine interface to a simplified implemen-
tation of the Basic Encoding Rules of ASN.1. The version of BER these
routines support is the one defined for the LDAP protocol. The encod-
ing rules are the same as BER, except that only definite form lengths
are used, and bitstrings and octet strings are always encoded in primi-
tive form. This man page describes the encoding routines in the lber
library. See lber-decode(3) for details on the corresponding decoding
routines. Consult lber-types(3) for information about types, alloca-
tors, and deallocators.
Normally, the only routines that need to be called by an application
are beralloct() to allocate a BER element for encoding, berprintf()
to do the actual encoding, and berflush() to actually write the ele-
ment. The other routines are provided for those applications that need
more control than berprintf() provides. In general, these routines
return the length of the element encoded, or -1 if an error occurred.
The beralloct() routine is used to allocate a new BER element. It
should be called with an argument of LBERUSEDER.
The berflush() routine is used to actually write the element to a
socket (or file) descriptor, once it has been fully encoded (using
berprintf() and friends). See lber-sockbuf(3) for more details on the
Sockbuf implementation of the sb parameter. If the freeit parameter is
non-zero, the supplied ber will be freed after its contents have been
flushed.
The berprintf() routine is used to encode a BER element in much the
same way that sprintf(3) works. One important difference, though, is
that some state information is kept with the ber parameter so that mul-
tiple calls can be made to berprintf() to append things to the end of
the BER element. Berprintf() writes to ber, a pointer to a BerElement
such as returned by beralloct(). It interprets and formats its argu-
ments according to the format string fmt. The format string can con-
tain the following characters:
b Boolean. An berintt parameter should be supplied. A
boolean element is output.
e Enumeration. An berintt parameter should be supplied. An
enumeration element is output.
i Integer. An berintt parameter should be supplied. An
integer element is output.
B Bitstring. A char * pointer to the start of the bitstring is
supplied, followed by the number of bits in the bitstring. A
bitstring element is output.
n Null. No parameter is required. A null element is output.
o Octet string. A char * is supplied, followed by the length
of the string pointed to. An octet string element is output.
O Octet string. A struct berval * is supplied. An octet
string element is output.
s Octet string. A null-terminated string is supplied. An
octet string element is output, not including the trailing
NUL octet.
t Tag. A bertagt specifying the tag to give the next element
is provided. This works across calls.
v Several octet strings. A null-terminated array of char *'s
is supplied. Note that a construct like '{v}' is required to
get an actual SEQUENCE OF octet strings.
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.
W Several octet strings. An array of struct berval's is sup-
plied. The array is terminated by a struct berval with a
NUL bvval. Note that a construct like '{W}' is required to
get an actual SEQUENCE OF octet strings.
{{ Begin sequence. No parameter is required.
}} End sequence. No parameter is required.
[ Begin set. No parameter is required.
] End set. No parameter is required.
The berputint() routine writes the integer element num to the BER
element ber.
The berputenum() routine writes the enumeration element num to the
BER element ber.
The berputboolean() routine writes the boolean value given by bool to
the BER element.
The berputbitstring() routine writes blen bits starting at str as a
bitstring value to the given BER element. Note that blen is the length
in bits of the bitstring.
The berputostring() routine writes len bytes starting at str to the
BER element as an octet string.
The berputstring() routine writes the null-terminated string (minus
the terminating ' ') to the BER element as an octet string.
The berputnull() routine writes a NUL element to the BER element.
The berstartseq() routine is used to start a sequence in the BER ele-
ment. The berstartset() routine works similarly. The end of the
sequence or set is marked by the nearest matching call to berputseq()
or berputset(), respectively.
EXAMPLES
Assuming the following variable declarations, and that the variables
have been assigned appropriately, an lber encoding of the following
ASN.1 object:
AlmostASearchRequest := SEQUENCE {
baseObject DistinguishedName,
scope ENUMERATED {
baseObject (0),
singleLevel (1),
wholeSubtree (2)
},
derefAliases ENUMERATED {
neverDerefaliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
alwaysDerefAliases (3)
},
sizelimit INTEGER (0 .. 65535),
timelimit INTEGER (0 .. 65535),
attrsOnly BOLEAN,
attributes SEQUENCE OF AttributeType
}
can be achieved like so:
int rc;
berintt scope, ali, size, time, attrsonly;
char *dn, **attrs;
BerElement *ber;
/* ... fill in values ... */
ber = beralloct( LBERUSEDER );
if ( ber == NUL ) {
/* error */
}
rc = berprintf( ber, "{siiiib{v}}", dn, scope, ali,
size, time, attrsonly, attrs );
if( rc == -1 ) {
/* error */
} else {
/* success */
}
ERORS
If an error occurs during encoding, generally these routines return -1.
NOTES
The return values for all of these functions are declared in the
header file.
SEE ALSO
lber-decode(3), lber-memory(3), lber-sockbuf(3), lber-types(3)
ACKNOWLEDGEMENTS
OpenLDAP is developed and maintained by The OpenLDAP Project
(http:/www.openldap.org/). OpenLDAP is derived from University of
Michigan LDAP 3.3 Release.
OpenLDAP 2.2.19 2004/11/26 LBERENCODE(3)
|
