Chip 2000 May

home *** CD-ROM | disk | FTP | other *** search

/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _6becfcd6cc811fd714bfcac7331208e4 < prev next >

Wrap

Text File | 2000-03-23 | 14KB | 387 lines

<HTML> <HEAD> <TITLE>Convert::BER - ASN.1 Basic Encoding Rules</TITLE> <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css"> <LINK REV="made" HREF="mailto:"> </HEAD> <BODY> <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Convert::BER - ASN.1 Basic Encoding Rules </TD></TR> </TABLE> <A NAME="__index__"></A>  <UL> <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI> <LI><A HREF="#synopsis">SYNOPSIS</A></LI> <LI><A HREF="#note">NOTE</A></LI> <LI><A HREF="#description">DESCRIPTION</A></LI> <LI><A HREF="#methods">METHODS</A></LI> <UL> <LI><A HREF="#io methods">IO METHODS</A></LI> </UL> <LI><A HREF="#oplist">OPLIST</A></LI> <LI><A HREF="#special operators">SPECIAL OPERATORS</A></LI> <LI><A HREF="#tags">TAGS</A></LI> <LI><A HREF="#subclassing">SUB-CLASSING</A></LI> <UL> <LI><A HREF="#defining new packing operators">DEFINING NEW PACKING OPERATORS</A></LI> </UL> <LI><A HREF="#limitations">LIMITATIONS</A></LI> <LI><A HREF="#bugs">BUGS</A></LI> <LI><A HREF="#author">AUTHOR</A></LI> <LI><A HREF="#copyright">COPYRIGHT</A></LI> </UL>  <HR> <H1><A NAME="name">NAME</A></H1> Convert::BER - ASN.1 Basic Encoding Rules <HR> <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1> <UL> <LI>Linux</LI> <LI>Solaris</LI> <LI>Windows</LI> </UL> <HR> <H1><A NAME="synopsis">SYNOPSIS</A></H1> <PRE> use Convert::BER; </PRE> <PRE> $ber = new Convert::BER;</PRE> <PRE> $ber->encode( INTEGER => 1, SEQUENCE => [ STRING => [ qw(a b c) ] ] );</PRE> <PRE> $ber->decode( INTEGER => \$i, SEQUENCE => [ STRING => \@str ] );</PRE> <PRE> $ber->buffer("");</PRE> <PRE> $ber->encode( SEQUENCE_OF => [ \%hash STRING => sub { $_[0] }, INTEGER => sub { $hash{ $_[0] } } ] );</PRE> <PRE> $ber->decode( SEQUENCE_OF => [ \$count STRING => sub { push @keys, undef; \$keys[-1] }, INTEGER => sub { push @values, undef; \$values[-1] } ] );</PRE> <HR> <H1><A NAME="note">NOTE</A></H1> This documentation is still under construction. Convert::BER is a a very flexable package that supports a lot of options. see the tests in t/ for examples <HR> <H1><A NAME="description">DESCRIPTION</A></H1> <CODE>Convert::BER</CODE> provides an OO interface to encoding and decoding data into packets using the ASN.1 Basic Encoding Rules (BER) <HR> <H1><A NAME="methods">METHODS</A></H1> <DL> <DT><A NAME="item_new">new</A> <DD> <DT>new ( BUFFER ) <DD> <DT>new ( opList ) <DD> <A HREF="#item_new"><CODE>new</CODE></A> creates a new <CODE>Convert::BER</CODE> object. <DT><A NAME="item_encode">encode ( opList )</A> <DD> Encode data in opList appending to the data in the buffer. <DT><A NAME="item_decode">decode ( opList )</A> <DD> Decode the data in the buffer as described by opList, starting where the last decode finished or position set by <A HREF="#item_pos"><CODE>pos</CODE></A> <DT><A NAME="item_buffer">buffer ( [ BUFFER ] )</A> <DD> Return the buffer contents. If BUFFER is specified the set the buffer contents and reset pos to zero. <DT><A NAME="item_pos">pos ( [ POS ] )</A> <DD> Without any arguments <A HREF="#item_pos"><CODE>pos</CODE></A> returns the offset where the last decode finished, or the last offset set by <A HREF="#item_pos"><CODE>pos</CODE></A>. If POS is specified then POS will be where the next decode starts. </DL> <H2><A NAME="io methods">IO METHODS</A></H2> <DL> <DT><A NAME="item_read">read ( IO )</A> <DD> <DT><A NAME="item_write">write ( IO )</A> <DD> <DT><A NAME="item_recv">recv ( SOCK )</A> <DD> <DT><A NAME="item_send">send ( SOCK [, ADDR ] )</A> <DD> </DL> <HR> <H1><A NAME="oplist">OPLIST</A></H1> An opList is a list of operator-value pairs. An operator can be any defined below, or any defined by a sub-class of <CODE>Convert::BER</CODE>, which will probably be derived from the primitives given here. For the following operators if encoding the value is the value of the data to be encoded, if decoding it is a reference to where the decoded will be put. If value is a reference to a list then, for encode each item in the list will be encoded in turn. If decoding then as many a possible items of teh given type will be decoded an placed into the array, but there must be at least one or the whole decode will fail. If value is a CODE reference, then the code will be evaluated and the result used. For encode the code should return either the data to be encoded or a reference to a list of data to be encoded. For decode the code should return a reference to where the decoded data should be placed or a reference to a list. The arguments that are passed to the code are described below in the <A HREF="#item_SEQUENCE_OF"><CODE>SEQUENCE_OF</CODE></A> section. <DL> <DT><A NAME="item_BOOLEAN">BOOLEAN</A> <DD> <DT><A NAME="item_INTEGER">INTEGER</A> <DD> <DT><A NAME="item_STRING">STRING</A> <DD> <DT><A NAME="item_NULL">NULL</A> <DD> <DT><A NAME="item_OBJECT_ID">OBJECT_ID</A> <DD> <DT><A NAME="item_ENUM">ENUM</A> <DD> </DL> Other operators avaliable are <DL> <DT><A NAME="item_BIT_STRING">BIT_STRING</A> <DD> A bit string is represented as a string of <CODE>0</CODE>'s and <CODE>1</CODE>'s, these sequences can be packed using the perl <A HREF="../../../lib/Pod/perlfunc.html#item_pack"><CODE>pack</CODE></A> operator and the character <CODE>B</CODE>, but in doing so the number of bits will be rounded up to a multiple of 8 <DT><A NAME="item_SEQUENCE">SEQUENCE</A> <DD> A SEQUENCE can be encoded .... <DT><A NAME="item_SET">SET</A> <DD> A set it treated in an identical way to a SEQUENCE. <DT><A NAME="item_SEQUENCE_OF">SEQUENCE_OF</A> <DD> </DL> <HR> <H1><A NAME="special operators">SPECIAL OPERATORS</A></H1> <DL> <DT><A NAME="item_BER">BER</A> <DD> Encode: value should be a <CODE>Convert::BER</CODE> object, which will be inserted into the buffer. If value is undefined then nothing is added. Decode: value should be a reference to a scalar, which will contain a <CODE>Convert::BER</CODE> object. This object will contain the remainder of the current sequence. <DT><A NAME="item_ANY">ANY</A> <DD> Like <A HREF="#item_BER"><CODE>BER</CODE></A> except that when decoding only the next item is decoded and placed into the <CODE>Convert::BER</CODE> object returned. <DT><A NAME="item_OPTIONAL">OPTIONAL</A> <DD> The value to this operator must be a reference to an opList. Encode: The contents value are encoded into the buffer, providing no entry in the list is undefined. Decode: The contents of value are decoded if possible, if not then decode continues at the next operator-value pair. </DL> <HR> <H1><A NAME="tags">TAGS</A></H1> Each operator, other than the special operators, has a tag value associated with it. Some applications require these tag values to be different from the default values. <CODE>Convert::BER</CODE> supports two ways of doing this. One method is to sub-class <CODE>Convert::BER</CODE>, which is described in the next section. For small applications or those that think sub-classing is just too much then the operatorm may be passed an arrayref. The array must contain two elements, the first is the usual operator name and the second if the tag value to use, as shown below. <PRE> $ber->encode( [ SEQUENCE => 0x34 ] => [ INTEGER => 10, STRING => "A" ] );</PRE> This will encode a sequence, with a tag value of <CODE>0x34</CODE>, which will contain and integer and a string which will have thier default tag values. <HR> <H1><A NAME="subclassing">SUB-CLASSING</A></H1> For large applications where operators with non default tags are used a lot the above maechanism can be very erroroneous, for this porpose <CODE>Convert::BER</CODE> may be sub-classed. To do this the sub-class must call a method <CODE>define</CODE> as a static method on the sub-class. The arguments to <CODE>define</CODE> is a list if arrayref's. Each arrayref will define one new operator. Each arrayref contains three values, the first is the name of the operator, the second is how the data is encoded and the third is the tag value. To aid with the creation of these arguments <CODE>Convert::BER</CODE> exports some variables and constant subroutines. For each operator defined by <CODE>Convert::BER</CODE>, or a <CODE>Convert::BER</CODE> sub-class, a scalar variable with the same name is avaliable for import, for example <CODE>$INTEGER</CODE> is avaliable from <CODE>Convert::BER</CODE>. And any operators defined by a new sub-class will be avaliable for import from that class. One of these variables may be used as the second element of each arrayref. <CODE>Convert::BER</CODE> also exports some constant subroutines that can be used to create the tag value. The subroutines exported are. <PRE> BER_BOOLEAN BER_INTEGER BER_BIT_STR BER_OCTET_STR BER_NULL BER_OBJECT_ID BER_SEQUENCE BER_SET </PRE> <PRE> BER_UNIVERSAL BER_APPLICATION BER_CONTEXT BER_PRIVATE BER_PRIMITIVE BER_CONSTRUCTOR</PRE> Using this information a sub-class of Convert::BER can be created as shown below. <PRE> package Net::LDAP::BER;</PRE> <PRE> use Convert::BER qw(/^(\$|BER_)/);</PRE> <PRE> use strict; use vars qw($VERSION @ISA);</PRE> <PRE> @ISA = qw(Convert::BER); $VERSION = "1.00";</PRE> <PRE> Net::LDAP::BER->define(</PRE> <PRE> # Name Type Tag ########################################</PRE> <PRE> [ REQ_UNBIND => $NULL, BER_APPLICATION | 0x02 ], </PRE> <PRE> [ REQ_COMPARE => $SEQUENCE, BER_APPLICATION | BER_CONSTRUCTOR | 0x0E ],</PRE> <PRE> [ REQ_ABANDON => $INTEGER, BER_APPLICATION | 0x10 ], );</PRE> This will create a new class <CODE>Net::LDAP::BER</CODE> which has three new operators avaliable. This class then may be used as follows <PRE> $ber = new Net::LDAP::BER; </PRE> <PRE> $ber->encode( REQ_UNBIND => 0, REQ_COMPARE => [ REQ_ABANDON => 123, ] );</PRE> <PRE> $ber->decode( REQ_UNBIND => \$var, REQ_COMPARE => [ REQ_ABANDON => \$num, ] );</PRE> Which will encode or decode the data using the formats and tags defined in the <CODE>Net::LDAP::BER</CODE> sub-class. It also helps to make the code more readable. <H2><A NAME="defining new packing operators">DEFINING NEW PACKING OPERATORS</A></H2> 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 ... <HR> <H1><A NAME="limitations">LIMITATIONS</A></H1> 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 <DL> <DT><A NAME="item_TODO">TODO</A> <DD> CONSTRUCTED operator </DL> <HR> <H1><A NAME="bugs">BUGS</A></H1> None known, but there may be some <HR> <H1><A NAME="author">AUTHOR</A></H1> Graham Barr <<A HREF="mailto:gbarr@pobox.com">gbarr@pobox.com</A>> <HR> <H1><A NAME="copyright">COPYRIGHT</A></H1> Copyright (c) 1995-1999 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%> <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc"> Convert::BER - ASN.1 Basic Encoding Rules </TD></TR> </TABLE> </BODY> </HTML>