LDAP Library Functions berencode(3LDAP)
NAME
berencode, beralloc, berprintf, berputint,
berputostring, berputstring, berputnull,
berputboolean, berputbitstring, berstartseq,
berstartset, berputseq, berputset - simplified Basic
Encoding Rules library encoding functions
SYNOPSIS
cc[ flag... ] file... -lldap[ library... ]
#include
BerElement *beralloc();
berprintf(BerElement *ber, char **fmt[, arg... ]);
berputint(BerElement *ber, long num, char tag);
berputostring(BerElement *ber, char **str, unsigned long len,
char tag);
berputstring(BerElement *ber, char **str, char tag);
berputnull(BerElement *ber, char tag);
berputboolean(BerElement *ber, int bool, char tag);
berputbitstring(BerElement *ber, char *str, int blen, char tag);
berstartseq(BerElement *ber, char tag);
berstartset(BerElement *ber, char tag);
berputseq(BerElement *ber);
berputset(BerElement *ber);
DESCRIPTION
These functions provide a subfunction interface to a simpli-
fied implementation of the Basic Encoding Rules of ASN.1.
The version of BER these functions support is the one
SunOS 5.11 Last change: 6 Oct 2008 1
LDAP Library Functions berencode(3LDAP)
defined for the LDAP protocol. The encoding rules are the
same as BER, except that only definite form lengths are
used, and bitstrings and octet strings are always encoded in
primitive form. In addition, these lightweight BER func-
tions restrict tags and class to fit in a single octet (this
means the actual tag must be less than 31). When a "tag"is
specified in the descriptions below, it refers to the tag,
class, and primitive or constructed bit in the first octet
of the encoding. This man page describes the encoding func-
tions in the lber library. See berdecode(3LDAP) for
details on the corresponding decoding functions.
Normally, the only functions that need be called by an
application are beralloc(), to allocate a BER element, and
berprintf() to do the actual encoding. The other functions
are provided for those applications that need more control
than berprintf() provides. In general, these functions
return the length of the element encoded, or -1 if an error
occurred.
The beralloc() function is used to allocate a new BER ele-
ment.
The berprintf() function is used to encode a BER element
in much the same way that sprintf(3S) works. One important
difference, though, is that some state information is kept
with the ber parameter so that multiple 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 beralloc(). It interprets and formats its
arguments according to the format string fmt. The format
string can contain the following characters:
b Boolean. An integer parameter should be supplied. A
boolean element is output.
B Bitstring. A char * pointer to the start of the bit-
string is supplied, followed by the number of bits in
the bitstring. A bitstring element is output.
i Integer. An integer parameter should be supplied. An
integer element is output.
n Null. No parameter is required. A null element is
output.
SunOS 5.11 Last change: 6 Oct 2008 2
LDAP Library Functions berencode(3LDAP)
o Octet string. A char * is supplied, followed by the
length of the string pointed to. An octet string ele-
ment 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 null octet.
t Tag. An int specifying the tag to give the next ele-
ment is provided. This works across calls.
v Several octet strings. A null-terminated array of char
* is supplied. Note that a construct like '{v}' 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() function writes the integer element num
to the BER element ber.
The berputboolean() function writes the boolean value
given by bool to the BER element.
The berputbitstring() function 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() function writes len bytes starting at
str to the BER element as an octet string.
SunOS 5.11 Last change: 6 Oct 2008 3
LDAP Library Functions berencode(3LDAP)
The berputstring() function writes the null-terminated
string (minus the terminating '') to the BER element as an
octet string.
The berputnull() function writes a NUL element to the
BER element.
The berstartseq() function is used to start a sequence in
the BER element. The berstartset() function works simi-
larly. The end of the sequence or set is marked by the
nearest matching call to berputseq() or berputset(),
respectively.
The berfirstelement() function is used to return the tag
and length of the first element in a set or sequence. It
also returns in cookie a magic cookie parameter that should
be passed to subsequent calls to bernextelement(), which
returns similar information.
EXAMPLES
Example 1 Assuming the following variable declarations, and
that the variables have been assigned appropriately, an BER
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 (3N)
},
sizelimit INTEGER (0 .. 65535),
timelimit INTEGER (0 .. 65535),
attrsOnly BOLEAN,
attributes SEQUENCE OF AttributeType
}
can be achieved like so:
int scope, ali, size, time, attrsonly;
char *dn, **attrs;
SunOS 5.11 Last change: 6 Oct 2008 4
LDAP Library Functions berencode(3LDAP)
/* ... fill in values ... */
if ( (ber = beralloc()) == NULBER )
/* error */
if ( berprintf( ber, "{siiiib{v}}", dn, scope, ali,
size, time, attrsonly, attrs ) == -1 )
/* error */
else
/* success */
RETURN VALUES
If an error occurs during encoding, beralloc() returns
NUL; other functions generally return -1.
ATRIBUTES
See attributes(5) for a description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsl (32-bit)
SUNWcslx (64-bit)
Interface Stability Committed
SEE ALSO
berdecode(3LDAP), attributes(5)
Yeong, W., Howes, T., and Hardcastle-Kille, S., "Lightweight
Directory Access Protocol", OSI-DS-26, April 1992.
Information Processing - Open Systems Interconnection -
Model and Notation - Service Definition - Specification of
Basic Encoding Rules for Abstract Syntax Notation One,
International Organization for Standardization, Interna-
tional Standard 8825.
NOTES
The return values for all of these functions are declared in
.
SunOS 5.11 Last change: 6 Oct 2008 5
|
