Convert-BER

 view release on metacpan or  search on metacpan

BER.pod  view on Meta::CPAN

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
=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.

BER.pod  view on Meta::CPAN

152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
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

BER.pod  view on Meta::CPAN

179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
=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.

BER.pod  view on Meta::CPAN

325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
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

BER.pod  view on Meta::CPAN

350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
=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>.

BER.pod  view on Meta::CPAN

479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
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.pod  view on Meta::CPAN

640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
    );
    $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

BER.pod  view on Meta::CPAN

709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
            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

BER.pod  view on Meta::CPAN

750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
            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,

BER.pod  view on Meta::CPAN

927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
    );
 
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.408 second using v1.01-cache-2.11-cpan-8d75d55dd25 )