Commit 7f70fe56 authored by Lev Walkin's avatar Lev Walkin

different layout

parent fb1cf701
...@@ -41,110 +41,110 @@ Contents</A> ...@@ -41,110 +41,110 @@ Contents</A>
<!--Table of Contents--> <!--Table of Contents-->
<UL> <UL>
<LI><A NAME="tex2html53" <LI><A NAME="tex2html51"
HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A> HREF="asn1c-usage.html#SECTION02000000000000000000">Using the ASN.1 Compiler</A>
<UL> <UL>
<LI><A NAME="tex2html54" <LI><A NAME="tex2html52"
HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A> HREF="asn1c-usage.html#SECTION02100000000000000000">Introduction to the ASN.1 Compiler</A>
<UL> <UL>
<LI><A NAME="tex2html53"
HREF="asn1c-usage.html#SECTION02110000000000000000">Quick start with asn1c</A>
<LI><A NAME="tex2html54"
HREF="asn1c-usage.html#SECTION02120000000000000000">Recognizing compiler output</A>
<LI><A NAME="tex2html55" <LI><A NAME="tex2html55"
HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A> HREF="asn1c-usage.html#SECTION02130000000000000000">Command line options</A>
<UL> </UL>
<LI><A NAME="tex2html56" <LI><A NAME="tex2html56"
HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A> HREF="asn1c-usage.html#SECTION02200000000000000000">Using the ASN.1 Compiler</A>
<UL>
<LI><A NAME="tex2html57" <LI><A NAME="tex2html57"
HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A> HREF="asn1c-usage.html#SECTION02210000000000000000">Invoking the ASN.1 helper code</A>
<UL>
<LI><A NAME="tex2html58" <LI><A NAME="tex2html58"
HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A> HREF="asn1c-usage.html#SECTION02211000000000000000">Decoding BER</A>
<LI><A NAME="tex2html59" <LI><A NAME="tex2html59"
HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A> HREF="asn1c-usage.html#SECTION02212000000000000000">Encoding DER</A>
<LI><A NAME="tex2html60" <LI><A NAME="tex2html60"
HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A> HREF="asn1c-usage.html#SECTION02213000000000000000">Encoding XER</A>
<LI><A NAME="tex2html61" <LI><A NAME="tex2html61"
HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A> HREF="asn1c-usage.html#SECTION02214000000000000000">Decoding XER</A>
</UL>
<LI><A NAME="tex2html62" <LI><A NAME="tex2html62"
HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A> HREF="asn1c-usage.html#SECTION02215000000000000000">Validating the target structure</A>
<UL>
<LI><A NAME="tex2html63" <LI><A NAME="tex2html63"
HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A> HREF="asn1c-usage.html#SECTION02216000000000000000">Printing the target structure</A>
<LI><A NAME="tex2html64" <LI><A NAME="tex2html64"
HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A> HREF="asn1c-usage.html#SECTION02217000000000000000">Freeing the target structure</A>
</UL>
</UL>
<LI><A NAME="tex2html65" <LI><A NAME="tex2html65"
HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A> HREF="asn1c-usage.html#SECTION02300000000000000000">Step by step examples</A>
<UL>
<LI><A NAME="tex2html66" <LI><A NAME="tex2html66"
HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A> HREF="asn1c-usage.html#SECTION02310000000000000000">A ''Rectangle'' Encoder</A>
<LI><A NAME="tex2html67" <LI><A NAME="tex2html67"
HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A> HREF="asn1c-usage.html#SECTION02320000000000000000">A ''Rectangle'' Decoder</A>
</UL> </UL>
<LI><A NAME="tex2html68" <LI><A NAME="tex2html68"
HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A> HREF="asn1c-usage.html#SECTION02400000000000000000">Constraint validation examples</A>
<UL> <UL>
<LI><A NAME="tex2html69" <LI><A NAME="tex2html69"
HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A> HREF="asn1c-usage.html#SECTION02410000000000000000">Adding constraints into ''Rectangle'' type</A>
</UL>
</UL><BR>
<LI><A NAME="tex2html70" <LI><A NAME="tex2html70"
HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A> HREF="asn1c-usage.html#SECTION03000000000000000000">ASN.1 Basics</A>
<UL>
<LI><A NAME="tex2html71" <LI><A NAME="tex2html71"
HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A> HREF="asn1c-usage.html#SECTION03100000000000000000">Abstract Syntax Notation: ASN.1</A>
<UL>
<LI><A NAME="tex2html72" <LI><A NAME="tex2html72"
HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A> HREF="asn1c-usage.html#SECTION03110000000000000000">Some of the ASN.1 Basic Types</A>
<UL>
<LI><A NAME="tex2html73" <LI><A NAME="tex2html73"
HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A> HREF="asn1c-usage.html#SECTION03111000000000000000">The BOOLEAN type</A>
</UL>
</UL>
</UL><BR>
<LI><A NAME="tex2html74" <LI><A NAME="tex2html74"
HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A> HREF="asn1c-usage.html#SECTION03112000000000000000">The INTEGER type</A>
<UL>
<LI><A NAME="tex2html75" <LI><A NAME="tex2html75"
HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A> HREF="asn1c-usage.html#SECTION03113000000000000000">The ENUMERATED type</A>
<LI><A NAME="tex2html76" <LI><A NAME="tex2html76"
HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A> HREF="asn1c-usage.html#SECTION03114000000000000000">The OCTET STRING type</A>
<LI><A NAME="tex2html77" <LI><A NAME="tex2html77"
HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A> HREF="asn1c-usage.html#SECTION03115000000000000000">The OBJECT IDENTIFIER type</A>
<UL>
<LI><A NAME="tex2html78" <LI><A NAME="tex2html78"
HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A> HREF="asn1c-usage.html#SECTION03116000000000000000">The RELATIVE-OID type</A>
</UL>
<LI><A NAME="tex2html79" <LI><A NAME="tex2html79"
HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A> HREF="asn1c-usage.html#SECTION03120000000000000000">Some of the ASN.1 String Types</A>
<LI><A NAME="tex2html80"
HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from an application</A>
<UL> <UL>
<LI><A NAME="tex2html80"
HREF="asn1c-usage.html#SECTION03121000000000000000">The IA5String type</A>
<LI><A NAME="tex2html81" <LI><A NAME="tex2html81"
HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A> HREF="asn1c-usage.html#SECTION03122000000000000000">The UTF8String type</A>
<LI><A NAME="tex2html82" <LI><A NAME="tex2html82"
HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A> HREF="asn1c-usage.html#SECTION03123000000000000000">The NumericString type</A>
<LI><A NAME="tex2html83" <LI><A NAME="tex2html83"
HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A> HREF="asn1c-usage.html#SECTION03124000000000000000">The PrintableString type</A>
<LI><A NAME="tex2html84" <LI><A NAME="tex2html84"
HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A> HREF="asn1c-usage.html#SECTION03125000000000000000">The VisibleString type</A>
</UL>
<LI><A NAME="tex2html85" <LI><A NAME="tex2html85"
HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A> HREF="asn1c-usage.html#SECTION03130000000000000000">ASN.1 Constructed Types</A>
<UL>
<LI><A NAME="tex2html86" <LI><A NAME="tex2html86"
HREF="asn1c-usage.html#SECTION03336000000000000000">Freeing the target structure</A> HREF="asn1c-usage.html#SECTION03131000000000000000">The SEQUENCE type</A>
</UL>
</UL>
</UL><BR>
<LI><A NAME="tex2html87" <LI><A NAME="tex2html87"
HREF="asn1c-usage.html#SECTION04000000000000000000">Examples</A> HREF="asn1c-usage.html#SECTION03132000000000000000">The SET type</A>
<UL>
<LI><A NAME="tex2html88" <LI><A NAME="tex2html88"
HREF="asn1c-usage.html#SECTION04100000000000000000">Step by step examples</A> HREF="asn1c-usage.html#SECTION03133000000000000000">The CHOICE type</A>
<UL>
<LI><A NAME="tex2html89" <LI><A NAME="tex2html89"
HREF="asn1c-usage.html#SECTION04110000000000000000">A ''Rectangle'' Encoder</A> HREF="asn1c-usage.html#SECTION03134000000000000000">The SEQUENCE OF type</A>
<LI><A NAME="tex2html90" <LI><A NAME="tex2html90"
HREF="asn1c-usage.html#SECTION04120000000000000000">A ''Rectangle'' Decoder</A> HREF="asn1c-usage.html#SECTION03135000000000000000">The SET OF type</A>
</UL> </UL>
<LI><A NAME="tex2html91"
HREF="asn1c-usage.html#SECTION04200000000000000000">Constraint validation examples</A>
<UL>
<LI><A NAME="tex2html92"
HREF="asn1c-usage.html#SECTION04210000000000000000">Adding constraints into ''Rectangle'' type</A>
</UL> </UL>
</UL><BR> </UL><BR>
<LI><A NAME="tex2html93" <LI><A NAME="tex2html91"
HREF="asn1c-usage.html#SECTION05000000000000000000">Bibliography</A> HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
</UL> </UL>
<!--End of Table of Contents--> <!--End of Table of Contents-->
...@@ -153,82 +153,38 @@ Contents</A> ...@@ -153,82 +153,38 @@ Contents</A>
<P> <P>
<H1><A NAME="SECTION02000000000000000000"> <H1><A NAME="SECTION02000000000000000000">
ASN.1 Basics</A> Using the ASN.1 Compiler</A>
</H1> </H1>
<P> <P>
<H1><A NAME="SECTION02100000000000000000"> <H1><A NAME="SECTION02100000000000000000">
Abstract Syntax Notation: ASN.1</A> Introduction to the ASN.1 Compiler</A>
</H1> </H1>
<P> <P>
<I>This chapter defines some basic ASN.1 concepts and describes The purpose of the ASN.1 compiler, of which this document is part,
several most widely used types. It is by no means an authoritative is to convert the specifications in ASN.1 notation into some other
or complete reference. For more complete ASN.1 description, please language. At this moment, only C and C++ target languages are supported,
refer to Olivier Dubuisson's book [<A the latter is in upward compatibility mode.
HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
of standards itself [<A
HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
<P>
The Abstract Syntax Notation One is used to formally describe the
semantics of data transmitted across the network. Two communicating
parties may have different formats of their native data types (i.e.
number of bits in the integer type), thus it is important to have
a way to describe the data in a manner which is independent from the
particular machine's representation. The ASN.1 specifications are
used to achieve the following:
<P>
<UL>
<LI>The specification expressed in the ASN.1 notation is a formal and
precise way to communicate the data semantics to human readers;
</LI>
<LI>The ASN.1 specifications may be used as input for automatic compilers
which produce the code for some target language (C, C++, Java, etc)
to encode and decode the data according to some encoding rules (which
are also defined by the ASN.1 standard).
</LI>
</UL>
Consider the following example:
<P> <P>
The compiler reads the specification and emits a series of target
<BLOCKQUOTE><PRE> language structures (C's structs, unions, enums) describing the corresponding
Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{ ASN.1 types. The compiler also creates the code which allows automatic
&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER, serialization and deserialization of these structures using several
&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER standardized encoding rules (BER, DER, XER).
}
</PRE>
</BLOCKQUOTE>
This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
containing two integer fields. This specification may tell the reader
that there exists this kind of data structure and that some entity
may be prepared to send or receive it. The question on <I>how</I>
that entity is going to send or receive the <I>encoded data</I> is
outside the scope of ASN.1. For example, this data structure may be
encoded according to some encoding rules and sent to the destination
using the TCP protocol. The ASN.1 specifies several ways of encoding
(or ''serializing'', or ''marshaling'') the data: BER, CER, DER
and XER, some of them which will be outlined later.
<P> <P>
The complete specification must be wrapped in a module, which looks For example, suppose the following ASN.1 module is given<A NAME="tex2html1"
like this: HREF="#foot818"><SUP>1.1</SUP></A>:
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
RectangleModule1 RectangleTest&nbsp;DEFINITIONS&nbsp;::=
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;iso&nbsp;org(3)&nbsp;dod(6)&nbsp;internet(1)&nbsp;private(4)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enterprise(1)&nbsp;spelio(9363)&nbsp;software(1)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1c(5)&nbsp;docs(2)&nbsp;rectangle(1)&nbsp;1&nbsp;}&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;DEFINITIONS&nbsp;AUTOMATIC&nbsp;TAGS&nbsp;::=
BEGIN BEGIN
&nbsp; &nbsp;
--&nbsp;This&nbsp;is&nbsp;a&nbsp;comment&nbsp;which&nbsp;describes&nbsp;nothing.
Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{ Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle &nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Width&nbsp;of&nbsp;the&nbsp;rectangle &nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Width&nbsp;of&nbsp;the&nbsp;rectangle
...@@ -237,441 +193,134 @@ Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{ ...@@ -237,441 +193,134 @@ Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
END END
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
The module header consists of module name (RectangleModule1), the The compiler would read this ASN.1 definition and produce the following
module object identifier ({...}), a keyword ''DEFINITIONS'', a C type<A NAME="tex2html2"
set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module HREF="#foot819"><SUP>1.2</SUP></A>:
ends with an ''END'' statement.
<P>
<H1><A NAME="SECTION02110000000000000000">
Some of the ASN.1 Basic Types</A>
</H1>
<P>
<H2><A NAME="SECTION02111000000000000000">
The BOOLEAN type</A>
</H2>
<P>
The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
or a similar kind of two-way choice.
<P>
<H2><A NAME="SECTION02112000000000000000">
The INTEGER type</A>
</H2>
<P>
The INTEGER type is a signed natural number type without any restrictions
on its size. If the automatic checking on INTEGER value bounds are
necessary, the subtype constraints must be used.
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
SimpleInteger&nbsp;::=&nbsp;INTEGER typedef&nbsp;struct&nbsp;Rectangle_s&nbsp;{
&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;height;
--&nbsp;An&nbsp;integer&nbsp;with&nbsp;a&nbsp;very&nbsp;limited&nbsp;range &nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;width;
SmallPositiveInt&nbsp;::=&nbsp;INTEGER&nbsp;(0..127) }&nbsp;Rectangle_t;
&nbsp;
--&nbsp;Integer,&nbsp;negative
NegativeInt&nbsp;::=&nbsp;INTEGER&nbsp;(MIN..0)
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
It would also create the code for converting this structure into platform-independent
wire representation (a serializer API) and the decoder of such wire
representation back into local, machine-specific type (a deserializer
API).
<P> <P>
<H2><A NAME="SECTION02113000000000000000"> <H1><A NAME="SECTION02110000000000000000">
The ENUMERATED type</A> Quick start with asn1c</A>
</H2> </H1>
<P> <P>
The ENUMERATED type is semantically equivalent to the INTEGER type After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html3"
with some integer values explicitly named. HREF="#foot820"><SUP>1.3</SUP></A> command may be used to compile the ASN.1 module<A NAME="tex2html4"
HREF="#foot821"><SUP>1.4</SUP></A>:
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
FruitId&nbsp;::=&nbsp;ENUMERATED&nbsp;{&nbsp;apple(1),&nbsp;orange(2)&nbsp;} asn1c&nbsp;<I>&lt;module.asn1&gt;</I>
&nbsp;
--&nbsp;The&nbsp;numbers&nbsp;in&nbsp;braces&nbsp;are&nbsp;optional,
--&nbsp;the&nbsp;enumeration&nbsp;can&nbsp;be&nbsp;performed
--&nbsp;automatically&nbsp;by&nbsp;the&nbsp;compiler
ComputerOSType&nbsp;::=&nbsp;ENUMERATED&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;FreeBSD,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;0
&nbsp;&nbsp;&nbsp;&nbsp;Windows,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;1
&nbsp;&nbsp;&nbsp;&nbsp;Solaris(5),&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;remains&nbsp;5
&nbsp;&nbsp;&nbsp;&nbsp;Linux,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;6
&nbsp;&nbsp;&nbsp;&nbsp;MacOS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;7
}
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
If several ASN.1 modules contain interdependencies, all of the files
<P> must be specified altogether:
<H2><A NAME="SECTION02114000000000000000">
The OCTET STRING type</A>
</H2>
<P>
This type models the sequence of 8-bit bytes. This may be used to
transmit some opaque data or data serialized by other types of encoders
(i.e. video file, photo picture, etc).
<P>
<H2><A NAME="SECTION02115000000000000000">
The OBJECT IDENTIFIER type</A>
</H2>
<P>
The OBJECT IDENTIFIER is used to represent the unique identifier of
any object, starting from the very root of the registration tree.
If your organization needs to uniquely identify something (a router,
a room, a person, a standard, or whatever), you are encouraged to
get your own identification subtree at <A HREF=http://www.iana.org/protocols/forms.htm>http://www.iana.org/protocols/forms.htm</A>.
<P>
For example, the very first ASN.1 module in this document has the
following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
ExampleOID&nbsp;::=&nbsp;OBJECT&nbsp;IDENTIFIER asn1c&nbsp;<I>&lt;module1.asn1&gt;&nbsp;&lt;module2.asn1&gt;&nbsp;...</I>
&nbsp;
rectangleModule1-oid&nbsp;ExampleOID
&nbsp;&nbsp;::=&nbsp;{&nbsp;1&nbsp;3&nbsp;6&nbsp;1&nbsp;4&nbsp;1&nbsp;9363&nbsp;1&nbsp;5&nbsp;2&nbsp;1&nbsp;1&nbsp;}
&nbsp;
--&nbsp;An&nbsp;identifier&nbsp;of&nbsp;the&nbsp;Internet.
internet-id&nbsp;OBJECT&nbsp;IDENTIFIER
&nbsp;&nbsp;::=&nbsp;{&nbsp;iso(1)&nbsp;identified-organization(3)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dod(6)&nbsp;internet(1)&nbsp;}
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
As you see, names are optional. The compiler <B>-E</B> and <B>-EF</B> options are used for testing
the parser and the semantic fixer, respectively. These options will
instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
is involved) ASN.1 specification as it was &#34;understood&#34;
by the compiler. It might be useful to check whether a particular
syntactic construction is properly supported by the compiler.
<P> <P>
<H2><A NAME="SECTION02116000000000000000"> <BLOCKQUOTE><PRE>
The RELATIVE-OID type</A> asn1c&nbsp;<B>-EF</B>&nbsp;<I>&lt;module-to-test.asn1&gt;</I>
</H2> </PRE>
</BLOCKQUOTE>
The <B>-P</B> option is used to dump the compiled output on the
screen instead of creating a bunch of .c and .h files on disk in the
current directory. You would probably want to start with <B>-P</B>
option instead of creating a mess in your current directory. Another
option, <B>-R</B>, asks compiler to only generate the files which
need to be generated, and supress linking in the numerous support
files.
<P> <P>
The RELATIVE-OID type has the semantics of a subtree of an OBJECT Print the compiled output instead of creating multiple source files:
IDENTIFIER. There may be no need to repeat the whole sequence of numbers
from the root of the registration tree where the only thing of interest
is some of the tree's subsequence.
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
this-document&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{&nbsp;docs(2)&nbsp;usage(1)&nbsp;} asn1c&nbsp;<B>-P</B>&nbsp;<I>&lt;module-to-compile-and-print.asn1&gt;</I>
&nbsp;
this-example&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;this-document&nbsp;assorted-examples(0)&nbsp;this-example(1)&nbsp;}
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
<P> <P>
<H1><A NAME="SECTION02120000000000000000"> <H1><A NAME="SECTION02120000000000000000">
Some of the ASN.1 String Types</A> Recognizing compiler output</A>
</H1> </H1>
<P> <P>
After compiling, the following entities will be created in your current
<H2><A NAME="SECTION02121000000000000000"> directory:
The IA5String type</A>
</H2>
<P>
This is essentially the ASCII, with 128 character codes available
(7 lower bits of an 8-bit byte).
<P> <P>
<H2><A NAME="SECTION02122000000000000000"> <UL>
The UTF8String type</A> <LI>A set of .c and .h files, generally a single pair for each type defined
</H2> in the ASN.1 specifications. These files will be named similarly to
the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
RectangleTest ASN.1 module defined in the beginning of this document).
</LI>
<LI>A set of helper .c and .h files which contain generic encoders, decoders
and other useful routines. There will be quite a few of them, some
of them even are not always necessary, but the overall amount of code
after compilation will be rather small anyway.
</LI>
<LI>A <I>Makefile.am.sample</I> file mentioning all the files created
at the earlier steps. This file is suitable for either automake suite
or the plain `make` utility.
</LI>
</UL>
It is your responsibility to create .c file with the <I>int main()</I>
routine.
<P> <P>
This is the character string which encodes the full Unicode range In other words, after compiling the Rectangle module, you have the
(4 bytes) using multibyte character sequences. following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
<B>...</B> }, where <B>''...''</B> stands for the
set of additional ''helper'' files created by the compiler. If you
add a simple file with the <I>int main()</I> routine, it would even
be possible to compile everything with the single instruction:
<P> <P>
<H2><A NAME="SECTION02123000000000000000"> <BLOCKQUOTE><PRE>
The NumericString type</A> cc&nbsp;-I.&nbsp;-o&nbsp;rectangle.exe&nbsp;*.c&nbsp;&nbsp;&nbsp;#&nbsp;It&nbsp;could&nbsp;be&nbsp;<I>that</I>&nbsp;simple
</H2> </PRE>
</BLOCKQUOTE>
Refer to the Chapter cha:Step-by-step-examples for a sample
<I>int main()</I> routine.
<P> <P>
This type represents the character string with the alphabet consisting
of numbers (''0'' to ''9'') and a space.
<P> <H1><A NAME="SECTION02130000000000000000">
Command line options</A>
<H2><A NAME="SECTION02124000000000000000"> </H1>
The PrintableString type</A>
</H2>
<P>
The character string with the following alphabet: space, ''<B>'</B>''
(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
''<B>,</B>'' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
upper-case and lower-case letters (''A'' to ''Z'' and ''a''
to ''z'').
<P>
<H2><A NAME="SECTION02125000000000000000">
The VisibleString type</A>
</H2>
<P>
The character string with the alphabet which is more or less a subset
of ASCII between the space and the ''<B>~</B>''
symbol (tilde).
<P>
Alternatively, the alphabet may be described as the PrintableString
alphabet presented earlier, plus the following characters: ''<B>!</B>'',
''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
''<B>&amp;</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B>&lt;</B>'',
''<B>&gt;</B>'', ''<B>[</B>'', ''<B>&#92;</B>'',
''<B>]</B>'', ''<B>&#94;</B>'', ''<B>_</B>'',
''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>|</B>'',
''<B>}</B>'', ''<B>~</B>''.
<P>
<H1><A NAME="SECTION02130000000000000000">
ASN.1 Constructed Types</A>
</H1>
<P>
<H2><A NAME="SECTION02131000000000000000">
The SEQUENCE type</A>
</H2>
<P>
This is an ordered collection of other simple or constructed types.
The SEQUENCE constructed type resembles the C ''struct'' statement.
<P>
<BLOCKQUOTE><PRE>
Address&nbsp;::=&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;The&nbsp;apartment&nbsp;number&nbsp;may&nbsp;be&nbsp;omitted
&nbsp;&nbsp;&nbsp;&nbsp;apartmentNumber&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL,
&nbsp;&nbsp;&nbsp;&nbsp;streetName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;cityName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;stateName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;This&nbsp;one&nbsp;may&nbsp;be&nbsp;omitted&nbsp;too
&nbsp;&nbsp;&nbsp;&nbsp;zipNo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL
}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION02132000000000000000">
The SET type</A>
</H2>
<P>
This is a collection of other simple or constructed types. Ordering
is not important. The data may arrive in the order which is different
from the order of specification. Data is encoded in the order not
necessarily corresponding to the order of specification.
<P>
<H2><A NAME="SECTION02133000000000000000">
The CHOICE type</A>
</H2>
<P>
This type is just a choice between the subtypes specified in it. The
CHOICE type contains at most one of the subtypes specified, and it
is always implicitly known which choice is being decoded or encoded.
This one resembles the C ''union'' statement.
<P>
The following type defines a response code, which may be either an
integer code or a boolean ''true''/''false'' code.
<P>
<BLOCKQUOTE><PRE>
ResponseCode&nbsp;::=&nbsp;CHOICE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;intCode&nbsp;&nbsp;&nbsp;&nbsp;INTEGER,
&nbsp;&nbsp;&nbsp;&nbsp;boolCode&nbsp;&nbsp;&nbsp;BOOLEAN
}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION02134000000000000000">
The SEQUENCE OF type</A>
</H2>
<P>
This one is the list (array) of simple or constructed types:
<P>
<BLOCKQUOTE><PRE>
--&nbsp;Example&nbsp;1
ManyIntegers&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;INTEGER
&nbsp;
--&nbsp;Example&nbsp;2
ManyRectangles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;Rectangle
&nbsp;
--&nbsp;More&nbsp;complex&nbsp;example:
--&nbsp;an&nbsp;array&nbsp;of&nbsp;structures&nbsp;defined&nbsp;in&nbsp;place.
ManyCircles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;radius&nbsp;INTEGER
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION02135000000000000000">
The SET OF type</A>
</H2>
<P>
The SET OF type models the bag of structures. It resembles the SEQUENCE
OF type, but the order is not important: i.e. the elements may arrive
in the order which is not necessarily the same as the in-memory order
on the remote machines.
<P>
<BLOCKQUOTE><PRE>
--&nbsp;A&nbsp;set&nbsp;of&nbsp;structures&nbsp;defined&nbsp;elsewhere
SetOfApples&nbsp;::&nbsp;SET&nbsp;OF&nbsp;Apple
&nbsp;
--&nbsp;Set&nbsp;of&nbsp;integers&nbsp;encoding&nbsp;the&nbsp;kind&nbsp;of&nbsp;a&nbsp;fruit
FruitBag&nbsp;::=&nbsp;SET&nbsp;OF&nbsp;ENUMERATED&nbsp;{&nbsp;apple,&nbsp;orange&nbsp;}
</PRE>
</BLOCKQUOTE>
<P>
<H1><A NAME="SECTION03000000000000000000">
Using the ASN.1 Compiler</A>
</H1>
<P>
<H1><A NAME="SECTION03100000000000000000">
Introduction to the ASN.1 Compiler</A>
</H1>
<P>
The purpose of the ASN.1 compiler, of which this document is part,
is to convert the ASN.1 specifications to some other target language
(currently, only C is supported<A NAME="tex2html1"
HREF="#foot159"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
language structures and surrounding maintenance code. For example,
the C structure which may be created by compiler to represent the
simple <I>Rectangle</I> specification defined earlier in this document,
may look like this<A NAME="tex2html2"
HREF="#foot803"><SUP>2.2</SUP></A>:
<P>
<BLOCKQUOTE><PRE>
typedef&nbsp;struct&nbsp;Rectangle_s&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;height;
&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;width;
}&nbsp;Rectangle_t;
</PRE>
</BLOCKQUOTE>
This would not be of much value for such a simple specification, so
the compiler goes further and actually produces the code which fills
in this structure by parsing the opaque binary<A NAME="tex2html3"
HREF="#foot166"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
this structure as an argument and performs structure serialization
by emitting a series of bytes.
<P>
<H1><A NAME="SECTION03200000000000000000">
Quick start</A>
</H1>
<P>
After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
HREF="#foot804"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
HREF="#foot805"><SUP>3.2</SUP></A>:
<P>
<BLOCKQUOTE><PRE>
asn1c&nbsp;<I>&lt;spec.asn1&gt;</I>
</PRE>
</BLOCKQUOTE>
If several specifications contain interdependencies, all of the files
must be specified altogether:
<P>
<BLOCKQUOTE><PRE>
asn1c&nbsp;<I>&lt;spec1.asn1&gt;&nbsp;&lt;spec2.asn1&gt;&nbsp;...</I>
</PRE>
</BLOCKQUOTE>
The compiler <B>-E</B> and <B>-EF</B> options are used for testing
the parser and the semantic fixer, respectively. These options will
instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
is involved) ASN.1 specification as it was &#34;understood&#34;
by the compiler. It might be useful to check whether a particular
syntactic construction is properly supported by the compiler.
<P>
<BLOCKQUOTE><PRE>
asn1c&nbsp;<B>-EF</B>&nbsp;<I>&lt;spec-to-test.asn1&gt;</I>
</PRE>
</BLOCKQUOTE>
The <B>-P</B> option is used to dump the compiled output on the
screen instead of creating a bunch of .c and .h files on disk in the
current directory. You would probably want to start with <B>-P</B>
option instead of creating a mess in your current directory. Another
option, <B>-R</B>, asks compiler to only generate the files which
need to be generated, and supress linking in the numerous support
files.
<P>
Print the compiled output instead of creating multiple source files:
<P>
<BLOCKQUOTE><PRE>
asn1c&nbsp;<B>-P</B>&nbsp;<I>&lt;spec-to-compile-and-print.asn1&gt;</I>
</PRE>
</BLOCKQUOTE>
<P>
<H1><A NAME="SECTION03300000000000000000">
Using the ASN.1 Compiler</A>
</H1>
<P>
<H1><A NAME="SECTION03310000000000000000">
Command-line options</A>
</H1>
<P> <P>
The <A HREF=#Table1>Table 1</A> summarizes various options affecting The <A HREF=#Table1>Table 1</A> summarizes various options affecting
...@@ -679,7 +328,7 @@ the compiler's behavior. ...@@ -679,7 +328,7 @@ the compiler's behavior.
<P> <P>
<BR><P></P> <BR><P></P>
<DIV ALIGN="CENTER"><A NAME="808"></A> <DIV ALIGN="CENTER"><A NAME="826"></A>
<TABLE> <TABLE>
<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG> <CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
The list of asn1c command line options</CAPTION> The list of asn1c command line options</CAPTION>
...@@ -784,59 +433,21 @@ to explain its internal understanding of subtype constraints.</FONT></TD></TR> ...@@ -784,59 +433,21 @@ to explain its internal understanding of subtype constraints.</FONT></TD></TR>
<P> <P>
<H1><A NAME="SECTION03320000000000000000"> <H1><A NAME="SECTION02200000000000000000">
Recognizing compiler output</A> Using the ASN.1 Compiler</A>
</H1> </H1>
<P>
After compiling, the following entities will be created in your current
directory:
<P>
<UL>
<LI>A set of .c and .h files, generally a single pair for each type defined
in the ASN.1 specifications. These files will be named similarly to
the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
specification defined in the beginning of this document).
</LI>
<LI>A set of helper .c and .h files which contain generic encoders, decoders
and other useful routines. There will be quite a few of them, some
of them even are not always necessary, but the overall amount of code
after compiling will be rather small anyway.
</LI>
</UL>
It is your responsibility to create .c file with the <I>int main()</I>
routine and the Makefile (if needed). Compiler helps you with the
latter by creating the Makefile.am.sample, containing the skeleton
definition for the automake, should you want to use autotools.
<P>
In other words, after compiling the Rectangle module, you have the
following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
<B>...</B> }, where <B>''...''</B> stands for the
set of additional ''helper'' files created by the compiler. If you
add the simple file with the <I>int main()</I> routine, it would even
be possible to compile everything with the single instruction:
<P>
<BLOCKQUOTE><PRE>
cc&nbsp;-o&nbsp;rectangle&nbsp;*.c&nbsp;&nbsp;&nbsp;#&nbsp;It&nbsp;could&nbsp;be&nbsp;<I>that</I>&nbsp;simple<A NAME="tex2html7"
HREF="#foot811"><SUP>4.1</SUP></A>
</PRE>
</BLOCKQUOTE>
<P> <P>
<H1><A NAME="SECTION03330000000000000000"> <H1><A NAME="SECTION02210000000000000000">
Invoking the ASN.1 helper code from an application</A> Invoking the ASN.1 helper code</A>
</H1> </H1>
<P> <P>
First of all, you should to include one or more header files into First of all, you should include one or more header files into your
your application. For our Rectangle module, including the Rectangle.h application. Typically, it is enough to include the header file of
file is enough: the main PDU type. For our Rectangle module, including the Rectangle.h
file is sufficient:
<P> <P>
...@@ -861,30 +472,38 @@ asn_DEF_Rectangle-&gt;free_struct(&amp;asn_DEF_Rectangle, ...@@ -861,30 +472,38 @@ asn_DEF_Rectangle-&gt;free_struct(&amp;asn_DEF_Rectangle,
</BLOCKQUOTE> </BLOCKQUOTE>
This code defines a <I>rect</I> pointer which points to the Rectangle_t This code defines a <I>rect</I> pointer which points to the Rectangle_t
structure which needs to be freed. The second line invokes the generic structure which needs to be freed. The second line invokes the generic
free_struct routine created specifically for this Rectangle_t structure. <I>free_struct()</I> routine created specifically for this Rectangle_t
The <I>asn_DEF_Rectangle</I> is the type descriptor, which holds structure. The <I>asn_DEF_Rectangle</I> is the type descriptor,
a collection of generic routines to deal with the Rectangle_t structure. which holds a collection of routines to deal with the Rectangle_t
structure.
<P> <P>
There are several generic functions available: The following member functions of the asn_DEF_Rectangle type descriptor
are of interest:
<P> <P>
<DL> <DL>
<DT><STRONG>ber_decoder</STRONG></DT> <DT><STRONG>ber_decoder</STRONG></DT>
<DD>This is the generic <I>restartable</I><A NAME="tex2html8" <DD>This is the generic <I>restartable</I><A NAME="tex2html6"
HREF="#foot253"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create HREF="#foot156"><SUP>2.1</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
and/or fill the target structure for you. Please refer to Section and/or fill the target structure for you. Please refer to Section
[<A HREF="#sub:Decoding-BER">Decoding BER</A>]. sub:Decoding-BER.
</DD> </DD>
<DT><STRONG>der_encoder</STRONG></DT> <DT><STRONG>der_encoder</STRONG></DT>
<DD>This is the generic DER encoder (Distinguished Encoding <DD>This is the generic DER encoder (Distinguished Encoding
Rules). This encoder will take the target structure and encode it Rules). This encoder will take the target structure and encode it
into a series of bytes. Please refer to Section [<A HREF="#sub:Encoding-DER">Encoding DER</A>]. into a series of bytes. Please refer to Section <A HREF="#sub:Encoding-DER">Encoding DER</A>.
</DD> </DD>
<DT><STRONG>xer_encoder</STRONG></DT> <DT><STRONG>xer_encoder</STRONG></DT>
<DD>This is the generic XER encoder (XML Encoding Rules). <DD>This is the XER encoder (XML Encoding Rules). This
This encoder will take the target structure and represent it as an encoder will take the target structure and represent it as an XML
XML (text) document. Please refer to Section [<A HREF="#sub:Encoding-XER">Encoding XER</A>]. (text) document using either BASIC-XER or CANONICAL-XER encoding rules.
Please refer to Section <A HREF="#sub:Encoding-XER">Encoding XER</A>.
</DD>
<DT><STRONG>xer_decoder</STRONG></DT>
<DD>This is the generic XER decoder. It takes both BASIC-XER
or CANONICAL-XER encodings and deserializes the data into a local,
machine-dependent representation. Please refer to Section <A HREF="#sub:Decoding-XER">Decoding XER</A>.
</DD> </DD>
<DT><STRONG>check_constraints</STRONG></DT> <DT><STRONG>check_constraints</STRONG></DT>
<DD>Check that the contents of the target structure <DD>Check that the contents of the target structure
...@@ -895,94 +514,39 @@ explicit subtype constraints. Please refer to Section <A HREF="#sub:Validating-t ...@@ -895,94 +514,39 @@ explicit subtype constraints. Please refer to Section <A HREF="#sub:Validating-t
<DD>This function convert the contents of the passed target <DD>This function convert the contents of the passed target
structure into human readable form. This form is not formal and cannot structure into human readable form. This form is not formal and cannot
be converted back into the structure, but it may turn out to be useful be converted back into the structure, but it may turn out to be useful
for debugging or quick-n-dirty printing. Please refer to Section [<A HREF="#sub:Printing-the-target">Printing the target</A>]. for debugging or quick-n-dirty printing. Please refer to Section <A HREF="#sub:Printing-the-target">Printing the target</A>.
</DD> </DD>
<DT><STRONG>free_struct</STRONG></DT> <DT><STRONG>free_struct</STRONG></DT>
<DD>This is a generic disposal which frees the target structure. <DD>This is a generic disposal which frees the target structure.
Please refer to Section [<A HREF="#sub:Freeing-the-target">Freeing the target</A>]. Please refer to Section <A HREF="#sub:Freeing-the-target">Freeing the target</A>.
</DD> </DD>
</DL> </DL>
check_constraints Check that the contents of the target structure
are semantically valid and constrained to appropriate implicit or
explicit subtype constraints. Please refer to Section <A HREF="#sub:Validating-the-target">Validating the target</A>.
<P>
Each of the above function takes the type descriptor (<I>asn_DEF_...</I>) Each of the above function takes the type descriptor (<I>asn_DEF_...</I>)
and the target structure (<I>rect</I>, in the above example). The and the target structure (<I>rect</I>, in the above example).
target structure is typically created by the generic BER decoder or
by the application itself.
<P>
Here is how the buffer can be deserialized into the structure:
<P>
<BLOCKQUOTE><PRE>
Rectangle_t&nbsp;*
simple_deserializer(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;asn_DEF_Rectangle-&gt;ber_decoder(0,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rect,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0);
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rect;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Decoding&nbsp;succeeded&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn_DEF_Rectangle-&gt;free_struct(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;0);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
&nbsp;&nbsp;&nbsp;&nbsp;}
}
</PRE>
</BLOCKQUOTE>
The code above defines a function, <I>simple_deserializer</I>, which
takes a buffer and its length and expected to return a pointer to
the Rectangle_t structure. Inside, it tries to convert the bytes
passed into the target structure (rect) using the generic BER decoder
and returns the rect pointer afterwards. If the structure cannot be
deserialized, it frees the memory which might be left allocated by
the unfinished <I>ber_decoder</I> routine and returns NULL. <B>This
freeing is necessary</B> because the ber_decoder is a restartable procedure,
and may fail just because there is more data needs to be provided
before decoding could be finalized. The code above obviously does
not take into account the way the <I>ber_decoder</I> failed, so the
freeing is necessary because the part of the buffer may already be
decoded into the structure by the time something goes wrong.
<P>
Restartable decoding is a little bit trickier: you need to provide
the old target structure pointer (which might be already half-decoded)
and react on RC_WMORE return code. This will be explained later in
Section <A HREF="#sub:Decoding-BER">Decoding BER</A>
<P> <P>
<H2><A NAME="SECTION03331000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR> <H2><A NAME="SECTION02211000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
Decoding BER Decoding BER
</H2> </H2>
<P> <P>
The Basic Encoding Rules describe the basic way how the structure The Basic Encoding Rules describe the most widely used (by the ASN.1
can be encoded and decoded. Several other encoding rules (CER, DER) community) way to encode and decode a given structure in a machine-independent
define a more restrictive versions of BER, so the generic BER parser way. Several other encoding rules (CER, DER) define a more restrictive
is also capable of decoding the data encoded by CER and DER encoders. versions of BER, so the generic BER parser is also capable of decoding
The opposite is not true. the data encoded by CER and DER encoders. The opposite is not true.
<P> <P>
The ASN.1 compiler provides the generic BER decoder which is implicitly <I>The ASN.1 compiler provides the generic BER decoder which is
capable of decoding BER, CER and DER encoded data. implicitly capable of decoding BER, CER and DER encoded data.</I>
<P> <P>
The decoder is restartable (stream-oriented), which means that in The decoder is restartable (stream-oriented), which means that in
case the buffer has less data than it is expected, the decoder will case the buffer has less data than it is expected, the decoder will
process whatever it is available and ask for more data to be provided. process whatever there is available and ask for more data to be provided.
Please note that the decoder may actually process less data than it Please note that the decoder may actually process less data than it
is given in the buffer, which means that you should be able to make was given in the buffer, which means that you must be able to make
the next buffer contain the unprocessed part of the previous buffer. the next buffer contain the unprocessed part of the previous buffer.
<P> <P>
...@@ -997,20 +561,60 @@ bytes of data, or ...@@ -997,20 +561,60 @@ bytes of data, or
<LI>You may feed it the first buffer of 100 bytes of data, realize that <LI>You may feed it the first buffer of 100 bytes of data, realize that
the ber_decoder consumed only 95 bytes from it and later feed the the ber_decoder consumed only 95 bytes from it and later feed the
decoder with 205 bytes buffer which consists of 5 unprocessed bytes decoder with 205 bytes buffer which consists of 5 unprocessed bytes
from the first buffer and the latter 200 bytes from the second buffer. from the first buffer and the additional 200 bytes from the second
buffer.
</LI> </LI>
</UL> </UL>
This is not as convenient as it could be (like, the BER encoder would This is not as convenient as it could be (like, the BER encoder could
consume the whole 100 bytes and keep these 5 bytes in some temporary consume the whole 100 bytes and keep these 5 bytes in some temporary
storage), but in case of stream-based processing it might actually storage), but in case of existing stream based processing it might
be OK. Suggestions are welcome. actually fit well into existing algorithm. Suggestions are welcome.
<P>
Here is the simplest example of BER decoding.
<P>
<BLOCKQUOTE><PRE>
Rectangle_t&nbsp;*
simple_deserializer(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;<B>asn_DEF_Rectangle-&gt;ber_decoder</B>(0,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rect,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0);
&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rect;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Decoding&nbsp;succeeded&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn_DEF_Rectangle-&gt;free_struct(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;0);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
&nbsp;&nbsp;&nbsp;&nbsp;}
}
</PRE>
</BLOCKQUOTE>
The code above defines a function, <I>simple_deserializer</I>, which
takes a buffer and its length and is expected to return a pointer
to the Rectangle_t structure. Inside, it tries to convert the bytes
passed into the target structure (rect) using the BER decoder and
returns the rect pointer afterwards. If the structure cannot be deserialized,
it frees the memory which might be left allocated by the unfinished
<I>ber_decoder</I> routine and returns 0 (no data). (This <B>freeing
is necessary</B> because the ber_decoder is a restartable procedure,
and may fail just because there is more data needs to be provided
before decoding could be finalized). The code above obviously does
not take into account the way the <I>ber_decoder()</I> failed, so
the freeing is necessary because the part of the buffer may already
be decoded into the structure by the time something goes wrong.
<P> <P>
There are two ways to invoke a BER decoder. The first one is a direct A little less wordy would be to invoke a globally available <I>ber_decode()</I>
reference of the type-specific decoder. This way was shown in the function instead of dereferencing the asn_DEF_Rectangle type descriptor:
previous example of <I>simple_deserializer</I> function. The second
way is to invoke a <I>ber_decode</I> function, which is just a simple
wrapper of the former approach into a less wordy notation:
<P> <P>
...@@ -1023,7 +627,7 @@ Note that the initial (asn_DEF_Rectangle-&gt;ber_decoder) reference ...@@ -1023,7 +627,7 @@ Note that the initial (asn_DEF_Rectangle-&gt;ber_decoder) reference
is gone, and also the last argument (0) is no longer necessary. is gone, and also the last argument (0) is no longer necessary.
<P> <P>
These two ways of invocations are fully equivalent. These two ways of BER decoder invocations are fully equivalent.
<P> <P>
The BER de<I>coder</I> may fail because of (<I>the following RC_... The BER de<I>coder</I> may fail because of (<I>the following RC_...
...@@ -1054,7 +658,7 @@ and related types. ...@@ -1054,7 +658,7 @@ and related types.
<P> <P>
<H2><A NAME="SECTION03332000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR> <H2><A NAME="SECTION02212000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
Encoding DER Encoding DER
</H2> </H2>
...@@ -1064,8 +668,8 @@ BER encoding rules. The DER is best suited to encode the structures ...@@ -1064,8 +668,8 @@ BER encoding rules. The DER is best suited to encode the structures
where all the lengths are known beforehand. This is probably exactly where all the lengths are known beforehand. This is probably exactly
how you want to encode: either after a BER decoding or after a manual how you want to encode: either after a BER decoding or after a manual
fill-up, the target structure contains the data which size is implicitly fill-up, the target structure contains the data which size is implicitly
known before encoding. The DER encoding is used, for example, to encode known before encoding. Among other uses, the DER encoding is used
X.509 certificates. to encode X.509 certificates.
<P> <P>
As with BER decoder, the DER encoder may be invoked either directly As with BER decoder, the DER encoder may be invoked either directly
...@@ -1114,8 +718,8 @@ If the custom write function is not given (passed as 0), then the ...@@ -1114,8 +718,8 @@ If the custom write function is not given (passed as 0), then the
DER encoder will essentially do the same thing (i.e., encode the data) DER encoder will essentially do the same thing (i.e., encode the data)
but no callbacks will be invoked (so the data goes nowhere). It may but no callbacks will be invoked (so the data goes nowhere). It may
prove useful to determine the size of the structure's encoding before prove useful to determine the size of the structure's encoding before
actually doing the encoding<A NAME="tex2html9" actually doing the encoding<A NAME="tex2html7"
HREF="#foot322"><SUP>4.3</SUP></A>. HREF="#foot225"><SUP>2.2</SUP></A>.
<P> <P>
Please look into der_encoder.h for the precise definition of der_encode() Please look into der_encoder.h for the precise definition of der_encode()
...@@ -1123,7 +727,7 @@ and related types. ...@@ -1123,7 +727,7 @@ and related types.
<P> <P>
<H2><A NAME="SECTION03333000000000000000"></A><A NAME="sub:Encoding-XER"></A><BR> <H2><A NAME="SECTION02213000000000000000"></A><A NAME="sub:Encoding-XER"></A><BR>
Encoding XER Encoding XER
</H2> </H2>
...@@ -1150,7 +754,7 @@ int ...@@ -1150,7 +754,7 @@ int
print_as_XML(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{ print_as_XML(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;asn_enc_rval_t&nbsp;er;&nbsp;&nbsp;/*&nbsp;Encoder&nbsp;return&nbsp;value&nbsp;*/ &nbsp;&nbsp;&nbsp;&nbsp;asn_enc_rval_t&nbsp;er;&nbsp;&nbsp;/*&nbsp;Encoder&nbsp;return&nbsp;value&nbsp;*/
&nbsp; &nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;er&nbsp;=&nbsp;xer_encode(&amp;asn_DEF_Rect,&nbsp;rect, &nbsp;&nbsp;&nbsp;&nbsp;er&nbsp;=&nbsp;xer_encode(&amp;asn_DEF_Rectangle,&nbsp;rect,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;XER_F_BASIC,&nbsp;/*&nbsp;BASIC-XER&nbsp;or&nbsp;CANONICAL-XER&nbsp;*/ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;XER_F_BASIC,&nbsp;/*&nbsp;BASIC-XER&nbsp;or&nbsp;CANONICAL-XER&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;write_stream,&nbsp;ostream); &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;write_stream,&nbsp;ostream);
&nbsp; &nbsp;
...@@ -1167,7 +771,48 @@ XML encoder and other pretty-printing suggestions. ...@@ -1167,7 +771,48 @@ XML encoder and other pretty-printing suggestions.
<P> <P>
<H2><A NAME="SECTION03334000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR> <H2><A NAME="SECTION02214000000000000000"></A><A NAME="sub:Decoding-XER"></A><BR>
Decoding XER
</H2>
<P>
The data encoded using the XER rules can be subsequently decoded using
the xer_decode() API call:
<P>
<BLOCKQUOTE><PRE>
Rectangle_t&nbsp;*
XML_to_Rectangle(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;
&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;xer_decode(0,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;(void&nbsp;**)&amp;rect,
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size);
&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rect;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Decoding&nbsp;succeeded&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn_DEF_Rectangle-&gt;free_struct(
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;0);
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
&nbsp;&nbsp;&nbsp;&nbsp;}
}
</PRE>
</BLOCKQUOTE>
The decoder takes both BASIC-XER and CANONICAL-XER encodings.
<P>
The decoder shares its data consumption properties with BER decoder;
please read the Section <A HREF="#sub:Decoding-BER">Decoding BER</A> to know more.
<P>
Please look into xer_decoder.h for the precise definition of xer_decode()
and related types.
<P>
<H2><A NAME="SECTION02215000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
Validating the target structure Validating the target structure
</H2> </H2>
...@@ -1195,7 +840,7 @@ and related types. ...@@ -1195,7 +840,7 @@ and related types.
<P> <P>
<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR> <H2><A NAME="SECTION02216000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
Printing the target structure Printing the target structure
</H2> </H2>
...@@ -1230,7 +875,7 @@ See Section <A HREF="#sub:Encoding-XER">Encoding XER</A> for XML-related details ...@@ -1230,7 +875,7 @@ See Section <A HREF="#sub:Encoding-XER">Encoding XER</A> for XML-related details
<P> <P>
<H2><A NAME="SECTION03336000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR> <H2><A NAME="SECTION02217000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
Freeing the target structure Freeing the target structure
</H2> </H2>
...@@ -1257,13 +902,13 @@ with one ASN.1-derived member (rect). This member is not a reference ...@@ -1257,13 +902,13 @@ with one ASN.1-derived member (rect). This member is not a reference
to the Rectangle_t, but an in-place inclusion of the Rectangle_t to the Rectangle_t, but an in-place inclusion of the Rectangle_t
structure. If the freeing is necessary, the usual procedure of freeing structure. If the freeing is necessary, the usual procedure of freeing
everything must not be applied to the &amp;rect pointer itself, because everything must not be applied to the &amp;rect pointer itself, because
it does not point to the memory block directly allocated by memory it does not point to the memory block directly allocated by the memory
allocation routine, but instead lies within such a block allocated allocation routine, but instead lies within a block allocated for
for my_figure structure. the my_figure structure.
<P> <P>
To solve this problem, the free_struct routine has the additional To solve this problem, the free_struct routine has the additional
argument (besides the intuitive type descriptor and target structure argument (besides the obvious type descriptor and target structure
pointers), which is the flag specifying whether the outer pointer pointers), which is the flag specifying whether the outer pointer
itself must be freed (0, default) or it should be left intact (non-zero itself must be freed (0, default) or it should be left intact (non-zero
value). value).
...@@ -1271,23 +916,26 @@ value). ...@@ -1271,23 +916,26 @@ value).
<P> <P>
<BLOCKQUOTE><PRE> <BLOCKQUOTE><PRE>
/*&nbsp;Rectangle_t&nbsp;is&nbsp;defined&nbsp;within&nbsp;my_figure&nbsp;*/ <B>/*&nbsp;1.&nbsp;Rectangle_t&nbsp;is&nbsp;defined&nbsp;within&nbsp;my_figure&nbsp;*/</B>
struct&nbsp;my_figure&nbsp;*mf&nbsp;=&nbsp;<B>...</B>; struct&nbsp;my_figure&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;rect;
}&nbsp;*mf&nbsp;=&nbsp;<B>...</B>;
/* /*
&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_td &nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
&nbsp;*&nbsp;without&nbsp;freeing&nbsp;the&nbsp;mf-&gt;rect&nbsp;pointer &nbsp;*&nbsp;without&nbsp;freeing&nbsp;the&nbsp;mf-&gt;rect&nbsp;area
&nbsp;*/ &nbsp;*/
asn_DEF_Rectangle-&gt;free_struct( asn_DEF_Rectangle-&gt;free_struct(
&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;&amp;mf-&gt;rect,&nbsp;<I>1</I>&nbsp;/*&nbsp;!free&nbsp;*/); &nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;&amp;mf-&gt;rect,&nbsp;<B>1</B>&nbsp;<B>/*&nbsp;!free&nbsp;*/</B>);
&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;
/*&nbsp;Rectangle_t&nbsp;is&nbsp;a&nbsp;stand-alone&nbsp;pointer&nbsp;*/ &nbsp;&nbsp;
<B>/*&nbsp;2.&nbsp;Rectangle_t&nbsp;is&nbsp;a&nbsp;stand-alone&nbsp;pointer&nbsp;*/</B>
Rectangle_t&nbsp;*rect&nbsp;=&nbsp;<B>...</B>; Rectangle_t&nbsp;*rect&nbsp;=&nbsp;<B>...</B>;
/* /*
&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t &nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
&nbsp;*&nbsp;and&nbsp;freeing&nbsp;the&nbsp;rect&nbsp;pointer &nbsp;*&nbsp;and&nbsp;freeing&nbsp;the&nbsp;rect&nbsp;pointer
&nbsp;*/ &nbsp;*/
asn_DEF_Rectangle-&gt;free_struct( asn_DEF_Rectangle-&gt;free_struct(
&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;<I>0</I>&nbsp;/*&nbsp;free&nbsp;the&nbsp;pointer&nbsp;too&nbsp;*/); &nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;<B>0</B>&nbsp;<B>/*&nbsp;free&nbsp;the&nbsp;pointer&nbsp;too&nbsp;*/</B>);
</PRE> </PRE>
</BLOCKQUOTE> </BLOCKQUOTE>
It is safe to invoke the <I>free_struct</I> function with the target It is safe to invoke the <I>free_struct</I> function with the target
...@@ -1295,19 +943,13 @@ structure pointer set to 0 (NULL), the function will do nothing. ...@@ -1295,19 +943,13 @@ structure pointer set to 0 (NULL), the function will do nothing.
<P> <P>
<H1><A NAME="SECTION04000000000000000000"> <H1><A NAME="SECTION02300000000000000000"></A><A NAME="cha:Step-by-step-examples"></A><BR>
Examples</A>
</H1>
<P>
<H1><A NAME="SECTION04100000000000000000"></A><A NAME="cha:Step-by-step-examples"></A><BR>
Step by step examples Step by step examples
</H1> </H1>
<P> <P>
<H1><A NAME="SECTION04110000000000000000"> <H1><A NAME="SECTION02310000000000000000">
A ''Rectangle'' Encoder</A> A ''Rectangle'' Encoder</A>
</H1> </H1>
...@@ -1449,7 +1091,7 @@ type, named <B>rencode</B>! ...@@ -1449,7 +1091,7 @@ type, named <B>rencode</B>!
<P> <P>
<H1><A NAME="SECTION04120000000000000000"></A><A NAME="sec:A-Rectangle-Decoder"></A><BR> <H1><A NAME="SECTION02320000000000000000"></A><A NAME="sec:A-Rectangle-Decoder"></A><BR>
A ''Rectangle'' Decoder A ''Rectangle'' Decoder
</H1> </H1>
...@@ -1575,7 +1217,7 @@ named <B>rdecode</B>! ...@@ -1575,7 +1217,7 @@ named <B>rdecode</B>!
<P> <P>
<H1><A NAME="SECTION04200000000000000000"> <H1><A NAME="SECTION02400000000000000000">
Constraint validation examples</A> Constraint validation examples</A>
</H1> </H1>
...@@ -1585,7 +1227,7 @@ validation code. ...@@ -1585,7 +1227,7 @@ validation code.
<P> <P>
<H1><A NAME="SECTION04210000000000000000"> <H1><A NAME="SECTION02410000000000000000">
Adding constraints into ''Rectangle'' type</A> Adding constraints into ''Rectangle'' type</A>
</H1> </H1>
...@@ -1619,8 +1261,8 @@ END ...@@ -1619,8 +1261,8 @@ END
<LI>Modify the Rectangle type processing routine (you can start with the <LI>Modify the Rectangle type processing routine (you can start with the
main() routine shown in the Section <A HREF="#sec:A-Rectangle-Decoder">A Rectangle Decoder</A>) main() routine shown in the Section <A HREF="#sec:A-Rectangle-Decoder">A Rectangle Decoder</A>)
by placing the following snippet of code <I>before</I> encoding and/or by placing the following snippet of code <I>before</I> encoding and/or
<I>after</I> decoding the Rectangle type<A NAME="tex2html10" <I>after</I> decoding the Rectangle type<A NAME="tex2html8"
HREF="#foot876"><SUP>6.1</SUP></A>: HREF="#foot898"><SUP>4.1</SUP></A>:
<P> <P>
...@@ -1657,7 +1299,423 @@ by the short explanation why validation did not succeed. ...@@ -1657,7 +1299,423 @@ by the short explanation why validation did not succeed.
<LI>Done. <LI>Done.
</LI> </LI>
</OL> </OL>
<H2><A NAME="SECTION05000000000000000000">
<P>
<H1><A NAME="SECTION03000000000000000000"></A><A NAME="par:ASN.1-Basics"></A><BR>
ASN.1 Basics
</H1>
<P>
<H1><A NAME="SECTION03100000000000000000"></A><A NAME="cha:Abstract-Syntax-Notation:"></A><BR>
Abstract Syntax Notation: ASN.1
</H1>
<P>
<I>This chapter defines some basic ASN.1 concepts and describes
several most widely used types. It is by no means an authoritative
or complete reference. For more complete ASN.1 description, please
refer to Olivier Dubuisson's book [<A
HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
of standards itself [<A
HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
<P>
The Abstract Syntax Notation One is used to formally describe the
semantics of data transmitted across the network. Two communicating
parties may have different formats of their native data types (i.e.
number of bits in the integer type), thus it is important to have
a way to describe the data in a manner which is independent from the
particular machine's representation. The ASN.1 specifications are
used to achieve the following:
<P>
<UL>
<LI>The specification expressed in the ASN.1 notation is a formal and
precise way to communicate the data semantics to human readers;
</LI>
<LI>The ASN.1 specifications may be used as input for automatic compilers
which produce the code for some target language (C, C++, Java, etc)
to encode and decode the data according to some encoding rules (which
are also defined by the ASN.1 standard).
</LI>
</UL>
Consider the following example:
<P>
<BLOCKQUOTE><PRE>
Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
}
</PRE>
</BLOCKQUOTE>
This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
containing two integer fields. This specification may tell the reader
that there exists this kind of data structure and that some entity
may be prepared to send or receive it. The question on <I>how</I>
that entity is going to send or receive the <I>encoded data</I> is
outside the scope of ASN.1. For example, this data structure may be
encoded according to some encoding rules and sent to the destination
using the TCP protocol. The ASN.1 specifies several ways of encoding
(or ''serializing'', or ''marshaling'') the data: BER, PER, XER
and others, including CER and DER derivatives from BER.
<P>
The complete specification must be wrapped in a module, which looks
like this:
<P>
<BLOCKQUOTE><PRE>
RectangleModule1
&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;iso&nbsp;org(3)&nbsp;dod(6)&nbsp;internet(1)&nbsp;private(4)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enterprise(1)&nbsp;spelio(9363)&nbsp;software(1)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1c(5)&nbsp;docs(2)&nbsp;rectangle(1)&nbsp;1&nbsp;}&nbsp;
&nbsp;&nbsp;&nbsp;&nbsp;DEFINITIONS&nbsp;AUTOMATIC&nbsp;TAGS&nbsp;::=
BEGIN
&nbsp;
--&nbsp;This&nbsp;is&nbsp;a&nbsp;comment&nbsp;which&nbsp;describes&nbsp;nothing.
Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Width&nbsp;of&nbsp;the&nbsp;rectangle
}
&nbsp;
END
</PRE>
</BLOCKQUOTE>
The module header consists of module name (RectangleModule1), the
module object identifier ({...}), a keyword ''DEFINITIONS'', a
set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
ends with an ''END'' statement.
<P>
<H1><A NAME="SECTION03110000000000000000">
Some of the ASN.1 Basic Types</A>
</H1>
<P>
<H2><A NAME="SECTION03111000000000000000">
The BOOLEAN type</A>
</H2>
<P>
The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
or a similar kind of two-way choice.
<P>
<H2><A NAME="SECTION03112000000000000000">
The INTEGER type</A>
</H2>
<P>
The INTEGER type is a signed natural number type without any restrictions
on its size. If the automatic checking on INTEGER value bounds are
necessary, the subtype constraints must be used.
<P>
<BLOCKQUOTE><PRE>
SimpleInteger&nbsp;::=&nbsp;INTEGER
&nbsp;
--&nbsp;An&nbsp;integer&nbsp;with&nbsp;a&nbsp;very&nbsp;limited&nbsp;range
SmallPositiveInt&nbsp;::=&nbsp;INTEGER&nbsp;(0..127)
&nbsp;
--&nbsp;Integer,&nbsp;negative
NegativeInt&nbsp;::=&nbsp;INTEGER&nbsp;(MIN..0)
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION03113000000000000000">
The ENUMERATED type</A>
</H2>
<P>
The ENUMERATED type is semantically equivalent to the INTEGER type
with some integer values explicitly named.
<P>
<BLOCKQUOTE><PRE>
FruitId&nbsp;::=&nbsp;ENUMERATED&nbsp;{&nbsp;apple(1),&nbsp;orange(2)&nbsp;}
&nbsp;
--&nbsp;The&nbsp;numbers&nbsp;in&nbsp;braces&nbsp;are&nbsp;optional,
--&nbsp;the&nbsp;enumeration&nbsp;can&nbsp;be&nbsp;performed
--&nbsp;automatically&nbsp;by&nbsp;the&nbsp;compiler
ComputerOSType&nbsp;::=&nbsp;ENUMERATED&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;FreeBSD,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;0
&nbsp;&nbsp;&nbsp;&nbsp;Windows,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;1
&nbsp;&nbsp;&nbsp;&nbsp;Solaris(5),&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;remains&nbsp;5
&nbsp;&nbsp;&nbsp;&nbsp;Linux,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;6
&nbsp;&nbsp;&nbsp;&nbsp;MacOS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;7
}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION03114000000000000000">
The OCTET STRING type</A>
</H2>
<P>
This type models the sequence of 8-bit bytes. This may be used to
transmit some opaque data or data serialized by other types of encoders
(i.e. video file, photo picture, etc).
<P>
<H2><A NAME="SECTION03115000000000000000">
The OBJECT IDENTIFIER type</A>
</H2>
<P>
The OBJECT IDENTIFIER is used to represent the unique identifier of
any object, starting from the very root of the registration tree.
If your organization needs to uniquely identify something (a router,
a room, a person, a standard, or whatever), you are encouraged to
get your own identification subtree at <A HREF=http://www.iana.org/protocols/forms.htm>http://www.iana.org/protocols/forms.htm</A>.
<P>
For example, the very first ASN.1 module in this Chapter (RectangleModule1)
has the following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
<P>
<BLOCKQUOTE><PRE>
ExampleOID&nbsp;::=&nbsp;OBJECT&nbsp;IDENTIFIER
&nbsp;
rectangleModule1-oid&nbsp;ExampleOID
&nbsp;&nbsp;::=&nbsp;{&nbsp;1&nbsp;3&nbsp;6&nbsp;1&nbsp;4&nbsp;1&nbsp;9363&nbsp;1&nbsp;5&nbsp;2&nbsp;1&nbsp;1&nbsp;}
&nbsp;
--&nbsp;An&nbsp;identifier&nbsp;of&nbsp;the&nbsp;Internet.
internet-id&nbsp;OBJECT&nbsp;IDENTIFIER
&nbsp;&nbsp;::=&nbsp;{&nbsp;iso(1)&nbsp;identified-organization(3)
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dod(6)&nbsp;internet(1)&nbsp;}
</PRE>
</BLOCKQUOTE>
As you see, names are optional.
<P>
<H2><A NAME="SECTION03116000000000000000">
The RELATIVE-OID type</A>
</H2>
<P>
The RELATIVE-OID type has the semantics of a subtree of an OBJECT
IDENTIFIER. There may be no need to repeat the whole sequence of numbers
from the root of the registration tree where the only thing of interest
is some of the tree's subsequence.
<P>
<BLOCKQUOTE><PRE>
this-document&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{&nbsp;docs(2)&nbsp;usage(1)&nbsp;}
&nbsp;
this-example&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;this-document&nbsp;assorted-examples(0)&nbsp;this-example(1)&nbsp;}
</PRE>
</BLOCKQUOTE>
<P>
<H1><A NAME="SECTION03120000000000000000">
Some of the ASN.1 String Types</A>
</H1>
<P>
<H2><A NAME="SECTION03121000000000000000">
The IA5String type</A>
</H2>
<P>
This is essentially the ASCII, with 128 character codes available
(7 lower bits of an 8-bit byte).
<P>
<H2><A NAME="SECTION03122000000000000000">
The UTF8String type</A>
</H2>
<P>
This is the character string which encodes the full Unicode range
(4 bytes) using multibyte character sequences.
<P>
<H2><A NAME="SECTION03123000000000000000">
The NumericString type</A>
</H2>
<P>
This type represents the character string with the alphabet consisting
of numbers (''0'' to ''9'') and a space.
<P>
<H2><A NAME="SECTION03124000000000000000">
The PrintableString type</A>
</H2>
<P>
The character string with the following alphabet: space, ''<B>'</B>''
(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
''<B>,</B>'' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
upper-case and lower-case letters (''A'' to ''Z'' and ''a''
to ''z'').
<P>
<H2><A NAME="SECTION03125000000000000000">
The VisibleString type</A>
</H2>
<P>
The character string with the alphabet which is more or less a subset
of ASCII between the space and the ''<B>~</B>''
symbol (tilde).
<P>
Alternatively, the alphabet may be described as the PrintableString
alphabet presented earlier, plus the following characters: ''<B>!</B>'',
''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
''<B>&amp;</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B>&lt;</B>'',
''<B>&gt;</B>'', ''<B>[</B>'', ''<B>&#92;</B>'',
''<B>]</B>'', ''<B>&#94;</B>'', ''<B>_</B>'',
''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>|</B>'',
''<B>}</B>'', ''<B>~</B>''.
<P>
<H1><A NAME="SECTION03130000000000000000">
ASN.1 Constructed Types</A>
</H1>
<P>
<H2><A NAME="SECTION03131000000000000000">
The SEQUENCE type</A>
</H2>
<P>
This is an ordered collection of other simple or constructed types.
The SEQUENCE constructed type resembles the C ''struct'' statement.
<P>
<BLOCKQUOTE><PRE>
Address&nbsp;::=&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;The&nbsp;apartment&nbsp;number&nbsp;may&nbsp;be&nbsp;omitted
&nbsp;&nbsp;&nbsp;&nbsp;apartmentNumber&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL,
&nbsp;&nbsp;&nbsp;&nbsp;streetName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;cityName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;stateName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;This&nbsp;one&nbsp;may&nbsp;be&nbsp;omitted&nbsp;too
&nbsp;&nbsp;&nbsp;&nbsp;zipNo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL
}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION03132000000000000000">
The SET type</A>
</H2>
<P>
This is a collection of other simple or constructed types. Ordering
is not important. The data may arrive in the order which is different
from the order of specification. Data is encoded in the order not
necessarily corresponding to the order of specification.
<P>
<H2><A NAME="SECTION03133000000000000000">
The CHOICE type</A>
</H2>
<P>
This type is just a choice between the subtypes specified in it. The
CHOICE type contains at most one of the subtypes specified, and it
is always implicitly known which choice is being decoded or encoded.
This one resembles the C ''union'' statement.
<P>
The following type defines a response code, which may be either an
integer code or a boolean ''true''/''false'' code.
<P>
<BLOCKQUOTE><PRE>
ResponseCode&nbsp;::=&nbsp;CHOICE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;intCode&nbsp;&nbsp;&nbsp;&nbsp;INTEGER,
&nbsp;&nbsp;&nbsp;&nbsp;boolCode&nbsp;&nbsp;&nbsp;BOOLEAN
}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION03134000000000000000">
The SEQUENCE OF type</A>
</H2>
<P>
This one is the list (array) of simple or constructed types:
<P>
<BLOCKQUOTE><PRE>
--&nbsp;Example&nbsp;1
ManyIntegers&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;INTEGER
&nbsp;
--&nbsp;Example&nbsp;2
ManyRectangles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;Rectangle
&nbsp;
--&nbsp;More&nbsp;complex&nbsp;example:
--&nbsp;an&nbsp;array&nbsp;of&nbsp;structures&nbsp;defined&nbsp;in&nbsp;place.
ManyCircles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;SEQUENCE&nbsp;{
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;radius&nbsp;INTEGER
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}
</PRE>
</BLOCKQUOTE>
<P>
<H2><A NAME="SECTION03135000000000000000">
The SET OF type</A>
</H2>
<P>
The SET OF type models the bag of structures. It resembles the SEQUENCE
OF type, but the order is not important: i.e. the elements may arrive
in the order which is not necessarily the same as the in-memory order
on the remote machines.
<P>
<BLOCKQUOTE><PRE>
--&nbsp;A&nbsp;set&nbsp;of&nbsp;structures&nbsp;defined&nbsp;elsewhere
SetOfApples&nbsp;::&nbsp;SET&nbsp;OF&nbsp;Apple
&nbsp;
--&nbsp;Set&nbsp;of&nbsp;integers&nbsp;encoding&nbsp;the&nbsp;kind&nbsp;of&nbsp;a&nbsp;fruit
FruitBag&nbsp;::=&nbsp;SET&nbsp;OF&nbsp;ENUMERATED&nbsp;{&nbsp;apple,&nbsp;orange&nbsp;}
</PRE>
</BLOCKQUOTE>
<H2><A NAME="SECTION04000000000000000000">
Bibliography</A> Bibliography</A>
</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A> </H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
<DD>The Open Source ASN.1 Compiler. <A HREF=http://lionet.info/asn1c>http://lionet.info/asn1c</A> <DD>The Open Source ASN.1 Compiler. <A HREF=http://lionet.info/asn1c>http://lionet.info/asn1c</A>
...@@ -1674,57 +1732,45 @@ ISBN:0-12-6333361-0. ...@@ -1674,57 +1732,45 @@ ISBN:0-12-6333361-0.
<P> <P>
<BR><HR><H4>Footnotes</H4> <BR><HR><H4>Footnotes</H4>
<DL> <DL>
<DT><A NAME="foot159">... supported</A><A <DT><A NAME="foot818">... given</A><A
HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT> HREF="asn1c-usage.html#tex2html1"><SUP>1.1</SUP></A></DT>
<DD>C++ is ''supported'' too, as long as an class-based approach is <DD>Please look into Part par:ASN.1-Basics for a quick reference
not a definitive factor. on how to understand the ASN.1 notation.
</DD> </DD>
<DT><A NAME="foot803">... this</A><A <DT><A NAME="foot819">... type</A><A
HREF="asn1c-usage.html#tex2html2"><SUP>2.2</SUP></A></DT> HREF="asn1c-usage.html#tex2html2"><SUP>1.2</SUP></A></DT>
<DD><I>-fnative-types</I> compiler option is used to produce basic C <I>int</I> <DD><I>-fnative-types</I> compiler option is used to produce basic C <I>int</I>
types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table 1</A>. types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table 1</A>.
</DD> </DD>
<DT><A NAME="foot166">... binary</A><A <DT><A NAME="foot820">...asn1c</A><A
HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT> HREF="asn1c-usage.html#tex2html3"><SUP>1.3</SUP></A></DT>
<DD>BER, CER and DER encodings are binary. However, the XER encoding is
text (XML) based.
</DD>
<DT><A NAME="foot804">...asn1c</A><A
HREF="asn1c-usage.html#tex2html4"><SUP>3.1</SUP></A></DT>
<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter. <DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
</DD> </DD>
<DT><A NAME="foot805">... specification</A><A <DT><A NAME="foot821">... module</A><A
HREF="asn1c-usage.html#tex2html5"><SUP>3.2</SUP></A></DT> HREF="asn1c-usage.html#tex2html4"><SUP>1.4</SUP></A></DT>
<DD>This is probably <B>not</B> what you want to try out right now - <DD>This is probably <B>not</B> what you want to try out right now -
read through the rest of this chapter to find out about <B>-P</B> read through the rest of this chapter and check the <A HREF=#Table1>Table 1</A>
and <B>-R</B> options. to find out about <B>-P</B> and <B>-R</B> options.
</DD>
<DT><A NAME="foot811">...that&nbsp;simple</A><A
HREF="asn1c-usage.html#tex2html7"><SUP>4.1</SUP></A></DT>
<DD>Provided that you've also created a .c file with the <I>int main()</I>
routine.
</DD> </DD>
<DT><A NAME="foot253">...restartable</A><A <DT><A NAME="foot156">...restartable</A><A
HREF="asn1c-usage.html#tex2html8"><SUP>4.2</SUP></A></DT> HREF="asn1c-usage.html#tex2html6"><SUP>2.1</SUP></A></DT>
<DD>Restartable means that if the decoder encounters the end of the buffer, <DD>Restartable means that if the decoder encounters the end of the buffer,
it will fail, but may later be invoked again with the rest of the it will fail, but may later be invoked again with the rest of the
buffer to continue decoding. buffer to continue decoding.
</DD> </DD>
<DT><A NAME="foot322">... encoding</A><A <DT><A NAME="foot225">... encoding</A><A
HREF="asn1c-usage.html#tex2html9"><SUP>4.3</SUP></A></DT> HREF="asn1c-usage.html#tex2html7"><SUP>2.2</SUP></A></DT>
<DD>It is actually faster too: the encoder might skip over some computations <DD>It is actually faster too: the encoder might skip over some computations
which aren't important for the size determination. which aren't important for the size determination.
</DD> </DD>
<DT><A NAME="foot876">... type</A><A <DT><A NAME="foot898">... type</A><A
HREF="asn1c-usage.html#tex2html10"><SUP>6.1</SUP></A></DT> HREF="asn1c-usage.html#tex2html8"><SUP>4.1</SUP></A></DT>
<DD>Placing the constraint checking code <I>before</I> encoding helps <DD>Placing the constraint checking code <I>before</I> encoding helps
to make sure you know the data is correct and within constraints before to make sure you know the data is correct and within constraints before
sharing the data with anyone else. sharing the data with anyone else.
...@@ -1738,7 +1784,7 @@ the application got the valid contents before making use of it. ...@@ -1738,7 +1784,7 @@ the application got the valid contents before making use of it.
</DL><BR><HR> </DL><BR><HR>
<ADDRESS> <ADDRESS>
Lev Walkin Lev Walkin
2005-02-02 2005-02-21
</ADDRESS> </ADDRESS>
</BODY> </BODY>
</HTML> </HTML>
...@@ -69,7 +69,7 @@ status Open ...@@ -69,7 +69,7 @@ status Open
\layout Standard \layout Standard
\backslash \backslash
lhead{Document describes lhead{This document describes
\backslash \backslash
href{http://lionet.info/asn1c}{asn1c-0.9.9}} href{http://lionet.info/asn1c}{asn1c-0.9.9}}
\layout Standard \layout Standard
...@@ -109,17 +109,17 @@ Introduction to the ASN.1 Compiler ...@@ -109,17 +109,17 @@ Introduction to the ASN.1 Compiler
\layout Standard \layout Standard
The purpose of the ASN.1 compiler, of which this document is part, is to The purpose of the ASN.1 compiler, of which this document is part, is to
convert the ASN.1 specifications into some other target language. convert the specifications in ASN.1 notation into some other language.
At this moment, only C and C++ target languages are supported, the latter At this moment, only C and C++ target languages are supported, the latter
in upward compatibility mode. is in upward compatibility mode.
\layout Standard \layout Standard
The compiler reads the specification and emits a series of target language The compiler reads the specification and emits a series of target language
structures (C's structs, unions, enums) describing the corresponding ASN.1 structures (C's structs, unions, enums) describing the corresponding ASN.1
types. types.
Also, it creates the code which allows automatic serialization and deserializat The compiler also creates the code which allows automatic serialization
ion of these structures using several standardized encoding rules (BER, and deserialization of these structures using several standardized encoding
DER, XER). rules (BER, DER, XER).
\layout Standard \layout Standard
For example, suppose the following ASN.1 module is given For example, suppose the following ASN.1 module is given
...@@ -249,7 +249,7 @@ This is probably ...@@ -249,7 +249,7 @@ This is probably
not not
\series default \series default
what you want to try out right now -- read through the rest of this chapter what you want to try out right now -- read through the rest of this chapter
and check the table and check the Table
\begin_inset LatexCommand \vref{cap:asn1c-cmdopts} \begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
\end_inset \end_inset
...@@ -959,9 +959,9 @@ Invoking the helper code ...@@ -959,9 +959,9 @@ Invoking the helper code
\layout Standard \layout Standard
First of all, you should to include one or more header files into your applicati First of all, you should include one or more header files into your application.
on. Typically, it is enough to include the header file of the main PDU type.
For our Rectangle module, including the Rectangle.h file is enough: For our Rectangle module, including the Rectangle.h file is sufficient:
\layout LyX-Code \layout LyX-Code
#include <Rectangle.h> #include <Rectangle.h>
...@@ -990,17 +990,21 @@ This code defines a ...@@ -990,17 +990,21 @@ This code defines a
rect rect
\emph default \emph default
pointer which points to the Rectangle_t structure which needs to be freed. pointer which points to the Rectangle_t structure which needs to be freed.
The second line invokes the generic free_struct routine created specifically The second line invokes the generic
for this Rectangle_t structure. \emph on
free_struct()
\emph default
routine created specifically for this Rectangle_t structure.
The The
\emph on \emph on
asn_DEF_Rectangle asn_DEF_Rectangle
\emph default \emph default
is the type descriptor, which holds a collection of generic routines to is the type descriptor, which holds a collection of routines to deal with
deal with the Rectangle_t structure. the Rectangle_t structure.
\layout Standard \layout Standard
There are several generic functions available: The following member functions of the asn_DEF_Rectangle type descriptor
are of interest:
\layout Description \layout Description
ber_decoder This is the generic ber_decoder This is the generic
...@@ -1113,13 +1117,15 @@ Decoding BER ...@@ -1113,13 +1117,15 @@ Decoding BER
\layout Standard \layout Standard
The Basic Encoding Rules describe the most widely used (by the ASN.1 community) The Basic Encoding Rules describe the most widely used (by the ASN.1 community)
way how the structure can be encoded and decoded. way to encode and decode a given structure in a machine-independent way.
Several other encoding rules (CER, DER) define a more restrictive versions Several other encoding rules (CER, DER) define a more restrictive versions
of BER, so the generic BER parser is also capable of decoding the data of BER, so the generic BER parser is also capable of decoding the data
encoded by CER and DER encoders. encoded by CER and DER encoders.
The opposite is not true. The opposite is not true.
\layout Standard \layout Standard
\emph on
The ASN.1 compiler provides the generic BER decoder which is implicitly capable The ASN.1 compiler provides the generic BER decoder which is implicitly capable
of decoding BER, CER and DER encoded data. of decoding BER, CER and DER encoded data.
\layout Standard \layout Standard
...@@ -1142,16 +1148,17 @@ You may concatenate these buffers and feed the BER decoder with 300 bytes ...@@ -1142,16 +1148,17 @@ You may concatenate these buffers and feed the BER decoder with 300 bytes
You may feed it the first buffer of 100 bytes of data, realize that the You may feed it the first buffer of 100 bytes of data, realize that the
ber_decoder consumed only 95 bytes from it and later feed the decoder with ber_decoder consumed only 95 bytes from it and later feed the decoder with
205 bytes buffer which consists of 5 unprocessed bytes from the first buffer 205 bytes buffer which consists of 5 unprocessed bytes from the first buffer
and the latter 200 bytes from the second buffer. and the additional 200 bytes from the second buffer.
\layout Standard \layout Standard
This is not as convenient as it could be (like, the BER encoder would consume This is not as convenient as it could be (like, the BER encoder could consume
the whole 100 bytes and keep these 5 bytes in some temporary storage), the whole 100 bytes and keep these 5 bytes in some temporary storage),
but in case of stream-based processing it might actually be OK. but in case of existing stream based processing it might actually fit well
into existing algorithm.
Suggestions are welcome. Suggestions are welcome.
\layout Standard \layout Standard
Here is the simplest example which shows how to invoke a BER decoder. Here is the simplest example of BER decoding.
\layout LyX-Code \layout LyX-Code
Rectangle_t * Rectangle_t *
...@@ -1226,35 +1233,35 @@ The code above defines a function, ...@@ -1226,35 +1233,35 @@ The code above defines a function,
\emph on \emph on
simple_deserializer simple_deserializer
\emph default \emph default
, which takes a buffer and its length and expected to return a pointer to , which takes a buffer and its length and is expected to return a pointer
the Rectangle_t structure. to the Rectangle_t structure.
Inside, it tries to convert the bytes passed into the target structure Inside, it tries to convert the bytes passed into the target structure
(rect) using the generic BER decoder and returns the rect pointer afterwards. (rect) using the BER decoder and returns the rect pointer afterwards.
If the structure cannot be deserialized, it frees the memory which might If the structure cannot be deserialized, it frees the memory which might
be left allocated by the unfinished be left allocated by the unfinished
\emph on \emph on
ber_decoder ber_decoder
\emph default \emph default
routine and returns 0 (no data). routine and returns 0 (no data).
This (This
\series bold \series bold
freeing is necessary freeing is necessary
\series default \series default
because the ber_decoder is a restartable procedure, and may fail just because because the ber_decoder is a restartable procedure, and may fail just because
there is more data needs to be provided before decoding could be finalized. there is more data needs to be provided before decoding could be finalized).
The code above obviously does not take into account the way the The code above obviously does not take into account the way the
\emph on \emph on
ber_decoder ber_decoder()
\emph default \emph default
failed, so the freeing is necessary because the part of the buffer may failed, so the freeing is necessary because the part of the buffer may
already be decoded into the structure by the time something goes wrong. already be decoded into the structure by the time something goes wrong.
\layout Standard \layout Standard
A little less wordy would be to invoke a A little less wordy would be to invoke a globally available
\emph on \emph on
ber_decode ber_decode()
\emph default \emph default
function instead of dereferencing the asn_DEF_Rectangle: function instead of dereferencing the asn_DEF_Rectangle type descriptor:
\layout LyX-Code \layout LyX-Code
rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect, rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
...@@ -1623,6 +1630,15 @@ XML_to_Rectangle(const void *buffer, size_t buf_size) { ...@@ -1623,6 +1630,15 @@ XML_to_Rectangle(const void *buffer, size_t buf_size) {
The decoder takes both BASIC-XER and CANONICAL-XER encodings. The decoder takes both BASIC-XER and CANONICAL-XER encodings.
\layout Standard \layout Standard
The decoder shares its data consumption properties with BER decoder; please
read the Section
\begin_inset LatexCommand \vref{sub:Decoding-BER}
\end_inset
to know more.
\layout Standard
Please look into xer_decoder.h for the precise definition of xer_decode() Please look into xer_decoder.h for the precise definition of xer_decode()
and related types. and related types.
\layout Subsection \layout Subsection
...@@ -1738,14 +1754,14 @@ In this example, the application programmer defined a custom structure with ...@@ -1738,14 +1754,14 @@ In this example, the application programmer defined a custom structure with
of the Rectangle_t structure. of the Rectangle_t structure.
If the freeing is necessary, the usual procedure of freeing everything If the freeing is necessary, the usual procedure of freeing everything
must not be applied to the &rect pointer itself, because it does not point must not be applied to the &rect pointer itself, because it does not point
to the memory block directly allocated by memory allocation routine, but to the memory block directly allocated by the memory allocation routine,
instead lies within such a block allocated for my_figure structure. but instead lies within a block allocated for the my_figure structure.
\layout Standard \layout Standard
To solve this problem, the free_struct routine has the additional argument To solve this problem, the free_struct routine has the additional argument
(besides the intuitive type descriptor and target structure pointers), (besides the obvious type descriptor and target structure pointers), which
which is the flag specifying whether the outer pointer itself must be freed is the flag specifying whether the outer pointer itself must be freed (0,
(0, default) or it should be left intact (non-zero value). default) or it should be left intact (non-zero value).
\layout LyX-Code \layout LyX-Code
......
No preview for this file type
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment