Convert-BER
view release on metacpan or search on metacpan
=back
=head1 OPLIST
An I<opList> is a list of I<operator>-I<value> pairs. An operator can
be any of those defined below, or any defined by sub-classing
C<Convert::BER>, which will probably be derived from the primitives
given here.
The I<value>s depend on whether BER is being encoded or decoded:
=over 4
=item Encoding
If the I<value> is a scalar, just encode it. If the I<value> is a
reference to a list, then encode each item in the list in turn. If the
I<value> is a code reference, then execute the code. If the returned
value is a scalar, encode that value. If the returned value is a
reference to a list, encode each item in the list in turn.
The I<value> is tested for boolean truth, and encoded appropriately.
# Encode a TRUE value
$ber->encode(
BOOLEAN => 1,
) or die;
=item Decoding
The decoded I<value>s will be either 1 or 0.
# Decode a boolean value into $bval
$ber->decode(
BOOLEAN => \$bval,
) or die;
=back
=head2 INTEGER
=item Encoding
The I<value> is the integer value to be encoded.
$ber->encode(
INTEGER => -123456,
) or die;
=item Decoding
The I<value> will be the decoded integer value.
$ber->decode(
INTEGER => \$ival,
) or die;
=back
=head2 STRING
This is an OCTET STRING, which is an arbitrarily long binary value.
The I<value> should be the packed bits to encode, B<not> a string of
C<0> and C<1> characters.
$ber->encode(
BIT_STRING8 => pack('B8', '10110101'),
) or die;
=item Decoding
The I<value> will be the decoded packed bits.
$ber->decode(
BIT_STRING8 => \$bval,
) or die;
=back
=head2 REAL
The REAL type encodes an floating-point number. It requires the POSIX
=item Encoding
The I<value> should be the number to encode.
$ber->encode(
REAL => 3.14159265358979,
) or die;
=item Decoding
The I<value> will be the decoded floating-point value.
$ber->decode(
REAL => \$rval,
);
=head2 ObjectDescriptor
The ObjectDescriptor type encodes an ObjectDescriptor string. It is a
sub-class of C<STRING>.
is 2-bytes wide. It is a sub-class of C<STRING>.
=head1 CONSTRUCTED OPERATORS
These operators are used to build constructed types, which contain
values in different types, like a C structure.
=head2 SEQUENCE
A SEQUENCE is a complex type that contains other types, a bit like a C
structure. Elements inside a SEQUENCE are encoded and decoded in the
order given.
=over 4
=item Encoding
The I<value> should be a reference to an array containing another
I<opList> which defines the elements inside the SEQUENCE.
$ber->encode(
);
$ber->encode(
BER => $tmp,
BOOLEAN => 1
);
=item Decoding
I<value> should be a reference to a scalar, which will contain a
C<Convert::BER> object. This object will contain the remainder of the
current sequence or set being decoded.
# After this, ber2 will contain the encoded INTEGER B<and> STRING.
# sval will be ignored and left undefined, but bval will be decoded. The
# decode of ber2 will return the integer and string values.
$ber->decode(
SEQUENCE => [
BER => \$ber2,
STRING => \$sval,
],
BOOLEAN => \$bval,
);
$ber2->decode(
INTEGER => \$ival,
STRING => \$sval2,
);
=back
=head2 ANY
This is like the C<BER> operator except that when decoding only the
next item is decoded and placed into the C<Convert::BER> object
returned. There is no difference when encoding.
=over 4
=item Decoding
I<value> should be a reference to a scalar, which will contain a
C<Convert::BER> object. This object will only contain the next single
item in the current sequence being decoded.
# After this, ber2 will decode further, and ival and sval
# will be decoded.
$ber->decode(
INTEGER = \$ival,
ANY => \$ber2,
STRING => \$sval,
);
=back
=head2 OPTIONAL
INTEGER => 16, # Will be encoded
OPTIONAL => [
INTEGER => undef, # Will not be encoded
],
STRING => 'Foo', # Will be encoded
]
);
=item Decoding
The contents of I<value> are decoded if possible, if not then decode
continues at the next I<operator>-I<value> pair.
$ber->decode(
SEQUENCE => [
INTEGER => \$ival1,
OPTIONAL => [
INTEGER => \$ival2,
],
STRING => \$sval,
]
);
=back
=head2 CHOICE
The I<opList> is a list of alternate I<operator>-I<value> pairs. Only
one will be encoded, and only one will be decoded.
=over 4
=item Encoding
A scalar at the start of the I<opList> identifies which I<opList>
alternative to use for encoding the value. A value of 0 means the
first one is used, 1 means the second one, etc.
# Encode the BMPString alternate of the CHOICE
PrintableString => 'Printable',
TeletexString => 'Teletex/T61',
BMPString => 'BMP/Unicode',
UniversalString => 'Universal/ISO10646',
]
) or die;
=item Decoding
A reference to a scalar at the start of the I<opList> is used to store
which alternative is decoded (0 for the first one, 1 for the second
one, etc.) Pass undef instead of the ref if you don't care about this,
or you store all the alternate values in different variables.
# Decode the above.
# Afterwards, $alt will be set to 2, $str will be set to 'BMP/Unicode'.
$ber->decode(
CHOICE => [ \$alt,
PrintableString => \$str,
TeletexString => \$str,
BMPString => \$str,
);
Which will encode or decode the data using the formats and tags
defined in the C<Net::LDAP::BER> sub-class. It also helps to make the
code more readable.
=head2 DEFINING NEW PACKING OPERATORS
As well as defining new operators which inherit from existing
operators it is also possible to define a new operator and how data is
encoded and decoded. The interface for doing this is still changing
but will be documented here when it is done. To be continued ...
=head1 LIMITATIONS
Convert::BER cannot support tags that contain more bits than can be
stored in a scalar variable, typically this is 32 bits.
Convert::BER cannot support items that have a packed length which
cannot be stored in 32 bits.
( run in 0.263 second using v1.01-cache-2.11-cpan-26ccb49234f )