Gitiles
Code Review Sign In
gerrit.osmocom.org / asn1c / e4861a66948fd2c583dc9508524f4942c76eeff2 / . / doc / asn1c-usage.html
blob: 8bd76d681125047b8522d8c3d8aae19cc7ac42f5 [file] [log] [blame]
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1
2<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
3original version by: Nikos Drakos, CBLU, University of Leeds
4* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
5* with significant contributions from:
6 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
7<HTML>
8<HEAD>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]9<TITLE>Using the Open Source ASN.1 Compiler</TITLE>
10<META NAME="description" CONTENT="Using the Open Source ASN.1 Compiler">
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]11<META NAME="keywords" CONTENT="ASN.1, asn1c, compiler, BER, DER, XER">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]12
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]13
14
15</HEAD>
16
17<BODY >
18
19<P>
20
21<P>
22
23<P>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]24<H1 ALIGN="CENTER">Using the Open Source ASN.1 Compiler</H1><DIV>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]25
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]26<P ALIGN="CENTER"><STRONG>Lev Walkin &lt;<A HREF=mailto:vlm@lionet.info?Subject=asn1c>vlm@lionet.info</A>&gt;</STRONG></P>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]27</DIV>
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]28
29<P>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]30<!-- MATH
31 $Revision$
32 -->
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]33<FONT COLOR=red><B>Download the <A HREF=asn1c-usage.pdf>PDF</A> version</B></FONT>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]34
35<P>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]36<BR>
37
38<H2><A NAME="SECTION01000000000000000000">
39Contents</A>
40</H2>
41<!--Table of Contents-->
42
43<UL>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]44<LI><A NAME="tex2html51"
45 HREF="asn1c-usage.html#SECTION02000000000000000000">Using the ASN.1 Compiler</A>
46<UL>
47<LI><A NAME="tex2html52"
48 HREF="asn1c-usage.html#SECTION02100000000000000000">Introduction to the ASN.1 Compiler</A>
49<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]50<LI><A NAME="tex2html53"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]51 HREF="asn1c-usage.html#SECTION02110000000000000000">Quick start with asn1c</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]52<LI><A NAME="tex2html54"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]53 HREF="asn1c-usage.html#SECTION02120000000000000000">Recognizing compiler output</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]54<LI><A NAME="tex2html55"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]55 HREF="asn1c-usage.html#SECTION02130000000000000000">Command line options</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]56</UL>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]57<LI><A NAME="tex2html56"
58 HREF="asn1c-usage.html#SECTION02200000000000000000">Using the ASN.1 Compiler</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]59<UL>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]60<LI><A NAME="tex2html57"
61 HREF="asn1c-usage.html#SECTION02210000000000000000">Invoking the ASN.1 helper code</A>
62<UL>
63<LI><A NAME="tex2html58"
64 HREF="asn1c-usage.html#SECTION02211000000000000000">Decoding BER</A>
65<LI><A NAME="tex2html59"
66 HREF="asn1c-usage.html#SECTION02212000000000000000">Encoding DER</A>
67<LI><A NAME="tex2html60"
68 HREF="asn1c-usage.html#SECTION02213000000000000000">Encoding XER</A>
69<LI><A NAME="tex2html61"
70 HREF="asn1c-usage.html#SECTION02214000000000000000">Decoding XER</A>
71<LI><A NAME="tex2html62"
72 HREF="asn1c-usage.html#SECTION02215000000000000000">Validating the target structure</A>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]73<LI><A NAME="tex2html63"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]74 HREF="asn1c-usage.html#SECTION02216000000000000000">Printing the target structure</A>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]75<LI><A NAME="tex2html64"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]76 HREF="asn1c-usage.html#SECTION02217000000000000000">Freeing the target structure</A>
77</UL>
78</UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]79<LI><A NAME="tex2html65"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]80 HREF="asn1c-usage.html#SECTION02300000000000000000">Step by step examples</A>
81<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]82<LI><A NAME="tex2html66"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]83 HREF="asn1c-usage.html#SECTION02310000000000000000">A ''Rectangle'' Encoder</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]84<LI><A NAME="tex2html67"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]85 HREF="asn1c-usage.html#SECTION02320000000000000000">A ''Rectangle'' Decoder</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]86</UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]87<LI><A NAME="tex2html68"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]88 HREF="asn1c-usage.html#SECTION02400000000000000000">Constraint validation examples</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]89<UL>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]90<LI><A NAME="tex2html69"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]91 HREF="asn1c-usage.html#SECTION02410000000000000000">Adding constraints into ''Rectangle'' type</A>
92</UL>
93</UL><BR>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]94<LI><A NAME="tex2html70"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]95 HREF="asn1c-usage.html#SECTION03000000000000000000">ASN.1 Basics</A>
96<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]97<LI><A NAME="tex2html71"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]98 HREF="asn1c-usage.html#SECTION03100000000000000000">Abstract Syntax Notation: ASN.1</A>
99<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]100<LI><A NAME="tex2html72"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]101 HREF="asn1c-usage.html#SECTION03110000000000000000">Some of the ASN.1 Basic Types</A>
102<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]103<LI><A NAME="tex2html73"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]104 HREF="asn1c-usage.html#SECTION03111000000000000000">The BOOLEAN type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]105<LI><A NAME="tex2html74"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]106 HREF="asn1c-usage.html#SECTION03112000000000000000">The INTEGER type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]107<LI><A NAME="tex2html75"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]108 HREF="asn1c-usage.html#SECTION03113000000000000000">The ENUMERATED type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]109<LI><A NAME="tex2html76"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]110 HREF="asn1c-usage.html#SECTION03114000000000000000">The OCTET STRING type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]111<LI><A NAME="tex2html77"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]112 HREF="asn1c-usage.html#SECTION03115000000000000000">The OBJECT IDENTIFIER type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]113<LI><A NAME="tex2html78"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]114 HREF="asn1c-usage.html#SECTION03116000000000000000">The RELATIVE-OID type</A>
115</UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]116<LI><A NAME="tex2html79"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]117 HREF="asn1c-usage.html#SECTION03120000000000000000">Some of the ASN.1 String Types</A>
118<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]119<LI><A NAME="tex2html80"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]120 HREF="asn1c-usage.html#SECTION03121000000000000000">The IA5String type</A>
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]121<LI><A NAME="tex2html81"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]122 HREF="asn1c-usage.html#SECTION03122000000000000000">The UTF8String type</A>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]123<LI><A NAME="tex2html82"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]124 HREF="asn1c-usage.html#SECTION03123000000000000000">The NumericString type</A>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]125<LI><A NAME="tex2html83"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]126 HREF="asn1c-usage.html#SECTION03124000000000000000">The PrintableString type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]127<LI><A NAME="tex2html84"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]128 HREF="asn1c-usage.html#SECTION03125000000000000000">The VisibleString type</A>
129</UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]130<LI><A NAME="tex2html85"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]131 HREF="asn1c-usage.html#SECTION03130000000000000000">ASN.1 Constructed Types</A>
132<UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]133<LI><A NAME="tex2html86"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]134 HREF="asn1c-usage.html#SECTION03131000000000000000">The SEQUENCE type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]135<LI><A NAME="tex2html87"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]136 HREF="asn1c-usage.html#SECTION03132000000000000000">The SET type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]137<LI><A NAME="tex2html88"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]138 HREF="asn1c-usage.html#SECTION03133000000000000000">The CHOICE type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]139<LI><A NAME="tex2html89"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]140 HREF="asn1c-usage.html#SECTION03134000000000000000">The SEQUENCE OF type</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]141<LI><A NAME="tex2html90"
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]142 HREF="asn1c-usage.html#SECTION03135000000000000000">The SET OF type</A>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]143</UL>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]144</UL>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]145</UL><BR>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]146<LI><A NAME="tex2html91"
147 HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]148</UL>
149<!--End of Table of Contents-->
150
151<P>
152
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]153<P>
154
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]155<H1><A NAME="SECTION02000000000000000000">
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]156Using the ASN.1 Compiler</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]157</H1>
158
159<P>
160
161<H1><A NAME="SECTION02100000000000000000">
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]162Introduction to the ASN.1 Compiler</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]163</H1>
164
165<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]166The purpose of the ASN.1 compiler, of which this document is part,
167is to convert the specifications in ASN.1 notation into some other
168language. At this moment, only C and C++ target languages are supported,
169the latter is in upward compatibility mode.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]170
171<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]172The compiler reads the specification and emits a series of target
173language structures (C's structs, unions, enums) describing the corresponding
174ASN.1 types. The compiler also creates the code which allows automatic
175serialization and deserialization of these structures using several
176standardized encoding rules (BER, DER, XER).
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]177
178<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]179For example, suppose the following ASN.1 module is given<A NAME="tex2html1"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]180 HREF="#foot843"><SUP>1.1</SUP></A>:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]181
182<P>
183
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]184<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]185RectangleTest&nbsp;DEFINITIONS&nbsp;::=
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]186BEGIN
187&nbsp;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]188Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
189&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]190&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
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]191}
192&nbsp;
193END
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]194</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]195</BLOCKQUOTE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]196The compiler would read this ASN.1 definition and produce the following
197C type<A NAME="tex2html2"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]198 HREF="#foot844"><SUP>1.2</SUP></A>:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]199
200<P>
201
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]202<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]203typedef&nbsp;struct&nbsp;Rectangle_s&nbsp;{
204&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;height;
205&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;width;
206}&nbsp;Rectangle_t;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]207</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]208</BLOCKQUOTE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]209It would also create the code for converting this structure into platform-independent
210wire representation (a serializer API) and the decoder of such wire
211representation back into local, machine-specific type (a deserializer
212API).
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]213
214<P>
215
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]216<H1><A NAME="SECTION02110000000000000000">
217Quick start with asn1c</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]218</H1>
219
220<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]221After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html3"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]222 HREF="#foot845"><SUP>1.3</SUP></A> command may be used to compile the ASN.1 module<A NAME="tex2html4"
223 HREF="#foot846"><SUP>1.4</SUP></A>:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]224
225<P>
226
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]227<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]228asn1c&nbsp;<I>&lt;module.asn1&gt;</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]229</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]230</BLOCKQUOTE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]231If several ASN.1 modules contain interdependencies, all of the files
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]232must be specified altogether:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]233
234<P>
235
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]236<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]237asn1c&nbsp;<I>&lt;module1.asn1&gt;&nbsp;&lt;module2.asn1&gt;&nbsp;...</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]238</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]239</BLOCKQUOTE>
240The compiler <B>-E</B> and <B>-EF</B> options are used for testing
241the parser and the semantic fixer, respectively. These options will
242instruct the compiler to dump out the parsed (and fixed, if <B>-F</B>
243is involved) ASN.1 specification as it was &#34;understood&#34;
244by the compiler. It might be useful to check whether a particular
245syntactic construction is properly supported by the compiler.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]246
247<P>
248
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]249<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]250asn1c&nbsp;<B>-EF</B>&nbsp;<I>&lt;module-to-test.asn1&gt;</I>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]251</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]252</BLOCKQUOTE>
253The <B>-P</B> option is used to dump the compiled output on the
254screen instead of creating a bunch of .c and .h files on disk in the
255current directory. You would probably want to start with <B>-P</B>
256option instead of creating a mess in your current directory. Another
257option, <B>-R</B>, asks compiler to only generate the files which
258need to be generated, and supress linking in the numerous support
259files.
260
261<P>
262Print the compiled output instead of creating multiple source files:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]263
264<P>
265
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]266<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]267asn1c&nbsp;<B>-P</B>&nbsp;<I>&lt;module-to-compile-and-print.asn1&gt;</I>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]268</PRE>
269</BLOCKQUOTE>
270
271<P>
272
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]273<H1><A NAME="SECTION02120000000000000000">
274Recognizing compiler output</A>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]275</H1>
276
277<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]278After compiling, the following entities will be created in your current
279directory:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]280
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]281<P>
282
283<UL>
284<LI>A set of .c and .h files, generally a single pair for each type defined
285in the ASN.1 specifications. These files will be named similarly to
286the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
287RectangleTest ASN.1 module defined in the beginning of this document).
288</LI>
289<LI>A set of helper .c and .h files which contain generic encoders, decoders
290and other useful routines. There will be quite a few of them, some
291of them even are not always necessary, but the overall amount of code
292after compilation will be rather small anyway.
293</LI>
294<LI>A <I>Makefile.am.sample</I> file mentioning all the files created
295at the earlier steps. This file is suitable for either automake suite
296or the plain `make` utility.
297</LI>
298</UL>
299It is your responsibility to create .c file with the <I>int main()</I>
300routine.
301
302<P>
303In other words, after compiling the Rectangle module, you have the
304following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
305<B>...</B> }, where <B>''...''</B> stands for the
306set of additional ''helper'' files created by the compiler. If you
307add a simple file with the <I>int main()</I> routine, it would even
308be possible to compile everything with the single instruction:
309
310<P>
311
312<BLOCKQUOTE><PRE>
313cc&nbsp;-I.&nbsp;-o&nbsp;rectangle.exe&nbsp;*.c&nbsp;&nbsp;&nbsp;#&nbsp;It&nbsp;could&nbsp;be&nbsp;<I>that</I>&nbsp;simple
314</PRE>
315</BLOCKQUOTE>
316Refer to the Chapter cha:Step-by-step-examples for a sample
317<I>int main()</I> routine.
318
319<P>
320
321<H1><A NAME="SECTION02130000000000000000">
322Command line options</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]323</H1>
324
325<P>
326The <A HREF=#Table1>Table 1</A> summarizes various options affecting
327the compiler's behavior.
328
329<P>
330<BR><P></P>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]331<DIV ALIGN="CENTER"><A NAME="851"></A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]332<TABLE>
333<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
334The list of asn1c command line options</CAPTION>
335<TR><TD><TABLE COLS=2 BORDER FRAME=BOX RULES=GROUPS>
336<COLGROUP><COL ALIGN=LEFT><COLGROUP><COL ALIGN=JUSTIFY WIDTH="3in">
337<TBODY>
338<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]339<B><FONT SIZE="-1">Overall Options</FONT></B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
340<B><FONT SIZE="-1">Description</FONT></B></TD></TR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]341</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]342<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-E</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]343<FONT SIZE="-1">Stop after the parsing stage and print the reconstructed ASN.1
344specification code to the standard output.</FONT></TD></TR>
345</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]346<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-F</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]347<FONT SIZE="-1">Used together with -E, instructs the compiler to stop after
348the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
349specification to the standard output.</FONT></TD></TR>
350</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]351<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-P</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]352<FONT SIZE="-1">Dump the compiled output to the standard output instead of
353cre- ating the target language files on disk.</FONT></TD></TR>
354</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]355<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-R</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]356<FONT SIZE="-1">Restrict the compiler to generate only the ASN.1 tables, omit-
357ting the usual support code.</FONT></TD></TR>
358</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]359<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-S</FONT> <I><FONT SIZE="-1">&lt;directory&gt;</FONT></I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]360<FONT SIZE="-1">Use the specified directory with ASN.1 skeleton files.</FONT></TD></TR>
361</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]362<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-X</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
363<FONT SIZE="-1">Generate the XML DTD for the specified ASN.1 modules.</FONT></TD></TR>
Lev Walkinf7484512004-10-13 09:13:56 +0000[diff] [blame]364</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]365<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B><FONT SIZE="-1">Warning Options</FONT></B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
366<B><FONT SIZE="-1">Description</FONT></B></TD></TR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]367</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]368<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-Werror</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]369<FONT SIZE="-1">Treat warnings as errors; abort if any warning is produced.</FONT></TD></TR>
370</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]371<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-Wdebug-lexer</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]372<FONT SIZE="-1">Enable lexer debugging during the ASN.1 parsing stage.</FONT></TD></TR>
373</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]374<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-Wdebug-fixer</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]375 <FONT SIZE="-1">Enable ASN.1 syntax tree fixer debugging during the
376 fixing stage.</FONT></TD></TR>
377</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]378<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-Wdebug-compiler</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]379<FONT SIZE="-1">Enable debugging during the actual compile time.</FONT></TD></TR>
380</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]381<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B><FONT SIZE="-1">Language Options</FONT></B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
382<B><FONT SIZE="-1">Description</FONT></B></TD></TR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]383</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]384<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fall-defs-global</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
385<FONT SIZE="-1">Normally the compiler hides the definitions (asn_DEF_xxx)
386of the inner structure elements (members of SEQUENCE, SET and other
387types). This option makes all such definitions global. Enabling this
388option may pollute the namespace by making lots of asn_DEF_xxx structures
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]389globally visible, but will allow you to manipulate (encode and decode)
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]390the individual members of any complex ASN.1 structure.</FONT></TD></TR>
Lev Walkin71a8aaf2004-09-08 03:10:54 +0000[diff] [blame]391</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]392<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fbless-SIZE</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]393<FONT SIZE="-1">Allow SIZE() constraint for INTEGER, ENUMERATED, and other
394types for which this constraint is normally prohibited by the standard.
395This is a violation of an ASN.1 standard and compiler may fail to
396produce the meaningful code.</FONT></TD></TR>
397</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]398<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fcompound-names</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
399<FONT SIZE="-1">Use complex names for C structures. Using complex names prevents
400name clashes in case the module reuses the same identifiers in multiple
401contexts.</FONT></TD></TR>
402</TBODY><TBODY>
403<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fnative-types</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin6faa68e2004-09-17 08:35:02 +0000[diff] [blame]404<FONT SIZE="-1">Use the native machine's data types (int, double) whenever
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]405possible, instead of the compound INTEGER_t, ENUMERATED_t and REAL_t
406types. </FONT></TD></TR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]407</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]408<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fno-constraints</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
409<FONT SIZE="-1">Do not generate ASN.1 subtype constraint checking code. This
410may produce a shorter executable.</FONT></TD></TR>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]411</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]412<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-fno-include-deps</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
413<FONT SIZE="-1">Do not generate courtesy #include lines for non-critical
414dependencies.</FONT></TD></TR>
415</TBODY><TBODY>
416<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-funnamed-unions</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]417<FONT SIZE="-1">Enable unnamed unions in the definitions of target language's
418structures.</FONT></TD></TR>
419</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]420<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-ftypes88</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]421<FONT SIZE="-1">Pretend to support only ASN.1:1988 embedded types. Certain
422reserved words, such as UniversalString and BMPString, become ordinary
423type references and may be redefined by the specification.</FONT></TD></TR>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]424</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]425<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B><FONT SIZE="-1">Output Options</FONT></B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
426<B><FONT SIZE="-1">Description</FONT></B></TD></TR>
Lev Walkin28c89eb2004-09-30 22:45:58 +0000[diff] [blame]427<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>
428
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]429<FONT SIZE="-1">-print-constraints</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]430<FONT SIZE="-1">When -EF are also specified, this option forces the compiler
431to explain its internal understanding of subtype constraints.</FONT></TD></TR>
432</TBODY><TBODY>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]433<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><FONT SIZE="-1">-print-lines</FONT></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]434<FONT SIZE="-1">Generate &#34;- #line&#34; comments in -E output.</FONT></TD></TR>
435</TBODY>
436</TABLE>
437
438<P>
439</TD></TR>
440</TABLE>
441</DIV><P></P><BR>
442
443<P>
444
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]445<H1><A NAME="SECTION02200000000000000000">
446Using the ASN.1 Compiler</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]447</H1>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]448
449<P>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]450
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]451<H1><A NAME="SECTION02210000000000000000">
452Invoking the ASN.1 helper code</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]453</H1>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]454
455<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]456First of all, you should include one or more header files into your
457application. Typically, it is enough to include the header file of
458the main PDU type. For our Rectangle module, including the Rectangle.h
459file is sufficient:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]460
461<P>
462
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]463<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]464#include&nbsp;&lt;Rectangle.h&gt;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]465</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]466</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]467The header files defines the C structure corresponding to the ASN.1
468definition of a rectangle and the declaration of the ASN.1 type descriptor,
469which is used as an argument to most of the functions provided by
470the ASN.1 module. For example, here is the code which frees the Rectangle_t
471structure:
472
473<P>
474
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]475<BLOCKQUOTE><PRE>
476Rectangle_t&nbsp;*rect&nbsp;=&nbsp;...;
477&nbsp;
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]478asn_DEF_Rectangle-&gt;free_struct(&amp;asn_DEF_Rectangle,
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]479&nbsp;&nbsp;&nbsp;&nbsp;rect,&nbsp;0);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]480</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]481</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]482This code defines a <I>rect</I> pointer which points to the Rectangle_t
483structure which needs to be freed. The second line invokes the generic
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]484<I>free_struct()</I> routine created specifically for this Rectangle_t
485structure. The <I>asn_DEF_Rectangle</I> is the type descriptor,
486which holds a collection of routines to deal with the Rectangle_t
487structure.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]488
489<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]490The following member functions of the asn_DEF_Rectangle type descriptor
491are of interest:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]492
493<P>
494<DL>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]495<DT><STRONG>ber_decoder</STRONG></DT>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]496<DD>This is the generic <I>restartable</I><A NAME="tex2html6"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]497 HREF="#foot181"><SUP>2.1</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]498and/or fill the target structure for you. Please refer to Section
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]499sub:Decoding-BER.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]500</DD>
501<DT><STRONG>der_encoder</STRONG></DT>
502<DD>This is the generic DER encoder (Distinguished Encoding
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]503Rules). This encoder will take the target structure and encode it
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]504into a series of bytes. Please refer to Section <A HREF="#sub:Encoding-DER">Encoding DER</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]505</DD>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]506<DT><STRONG>xer_encoder</STRONG></DT>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]507<DD>This is the XER encoder (XML Encoding Rules). This
508encoder will take the target structure and represent it as an XML
509(text) document using either BASIC-XER or CANONICAL-XER encoding rules.
510Please refer to Section <A HREF="#sub:Encoding-XER">Encoding XER</A>.
511</DD>
512<DT><STRONG>xer_decoder</STRONG></DT>
513<DD>This is the generic XER decoder. It takes both BASIC-XER
514or CANONICAL-XER encodings and deserializes the data into a local,
515machine-dependent representation. Please refer to Section <A HREF="#sub:Decoding-XER">Decoding XER</A>.
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]516</DD>
517<DT><STRONG>check_constraints</STRONG></DT>
518<DD>Check that the contents of the target structure
519are semantically valid and constrained to appropriate implicit or
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]520explicit subtype constraints. Please refer to Section <A HREF="#sub:Validating-the-target">Validating the target</A>.
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]521</DD>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]522<DT><STRONG>print_struct</STRONG></DT>
523<DD>This function convert the contents of the passed target
524structure into human readable form. This form is not formal and cannot
525be converted back into the structure, but it may turn out to be useful
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]526for debugging or quick-n-dirty printing. Please refer to Section <A HREF="#sub:Printing-the-target">Printing the target</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]527</DD>
528<DT><STRONG>free_struct</STRONG></DT>
529<DD>This is a generic disposal which frees the target structure.
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]530Please refer to Section <A HREF="#sub:Freeing-the-target">Freeing the target</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]531</DD>
532</DL>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]533Each of the above function takes the type descriptor (<I>asn_DEF_...</I>)
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]534and the target structure (<I>rect</I>, in the above example).
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]535
536<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]537
538<H2><A NAME="SECTION02211000000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
539Decoding BER
540</H2>
541
542<P>
543The Basic Encoding Rules describe the most widely used (by the ASN.1
544community) way to encode and decode a given structure in a machine-independent
545way. Several other encoding rules (CER, DER) define a more restrictive
546versions of BER, so the generic BER parser is also capable of decoding
547the data encoded by CER and DER encoders. The opposite is not true.
548
549<P>
550<I>The ASN.1 compiler provides the generic BER decoder which is
551implicitly capable of decoding BER, CER and DER encoded data.</I>
552
553<P>
554The decoder is restartable (stream-oriented), which means that in
555case the buffer has less data than it is expected, the decoder will
556process whatever there is available and ask for more data to be provided.
557Please note that the decoder may actually process less data than it
558was given in the buffer, which means that you must be able to make
559the next buffer contain the unprocessed part of the previous buffer.
560
561<P>
562Suppose, you have two buffers of encoded data: 100 bytes and 200 bytes.
563
564<P>
565
566<UL>
567<LI>You may concatenate these buffers and feed the BER decoder with 300
568bytes of data, or
569</LI>
570<LI>You may feed it the first buffer of 100 bytes of data, realize that
571the ber_decoder consumed only 95 bytes from it and later feed the
572decoder with 205 bytes buffer which consists of 5 unprocessed bytes
573from the first buffer and the additional 200 bytes from the second
574buffer.
575</LI>
576</UL>
577This is not as convenient as it could be (like, the BER encoder could
578consume the whole 100 bytes and keep these 5 bytes in some temporary
579storage), but in case of existing stream based processing it might
580actually fit well into existing algorithm. Suggestions are welcome.
581
582<P>
583Here is the simplest example of BER decoding.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]584
585<P>
586
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]587<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]588Rectangle_t&nbsp;*
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]589simple_deserializer(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]590&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
Lev Walkina646ccb2004-10-20 15:48:55 +0000[diff] [blame]591&nbsp;&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]592&nbsp;
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]593&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;<B>asn_DEF_Rectangle-&gt;ber_decoder</B>(0,
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]594&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]595&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rect,
596&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size,
597&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0);
598&nbsp;
599&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
600&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;*/
601&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]602&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]603&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn_DEF_Rectangle-&gt;free_struct(
604&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;0);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]605&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
606&nbsp;&nbsp;&nbsp;&nbsp;}
607}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]608</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]609</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]610The code above defines a function, <I>simple_deserializer</I>, which
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]611takes a buffer and its length and is expected to return a pointer
612to the Rectangle_t structure. Inside, it tries to convert the bytes
613passed into the target structure (rect) using the BER decoder and
614returns the rect pointer afterwards. If the structure cannot be deserialized,
615it frees the memory which might be left allocated by the unfinished
616<I>ber_decoder</I> routine and returns 0 (no data). (This <B>freeing
617is necessary</B> because the ber_decoder is a restartable procedure,
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]618and may fail just because there is more data needs to be provided
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]619before decoding could be finalized). The code above obviously does
620not take into account the way the <I>ber_decoder()</I> failed, so
621the freeing is necessary because the part of the buffer may already
622be decoded into the structure by the time something goes wrong.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]623
624<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]625A little less wordy would be to invoke a globally available <I>ber_decode()</I>
626function instead of dereferencing the asn_DEF_Rectangle type descriptor:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]627
628<P>
629
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]630<BLOCKQUOTE><PRE>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]631rval&nbsp;=&nbsp;ber_decode(0,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;(void&nbsp;**)&amp;rect,
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]632&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]633</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]634</BLOCKQUOTE>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]635Note that the initial (asn_DEF_Rectangle-&gt;ber_decoder) reference
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]636is gone, and also the last argument (0) is no longer necessary.
637
638<P>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]639These two ways of BER decoder invocations are fully equivalent.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]640
641<P>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]642The BER de<I>coder</I> may fail because of (<I>the following RC_...
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]643codes are defined in ber_decoder.h</I>):
644
645<P>
646
647<UL>
648<LI>RC_WMORE: There is more data expected than it is provided (stream
649mode continuation feature);
650</LI>
651<LI>RC_FAIL: General failure to decode the buffer;
652</LI>
653<LI>... other codes may be defined as well.
654</LI>
655</UL>
Lev Walkina646ccb2004-10-20 15:48:55 +0000[diff] [blame]656Together with the return code (.code) the asn_dec_rval_t type contains
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]657the number of bytes which is consumed from the buffer. In the previous
658hypothetical example of two buffers (of 100 and 200 bytes), the first
659call to ber_decode() would return with .code = RC_WMORE and .consumed
660= 95. The .consumed field of the BER decoder return value is <B>always</B>
661valid, even if the decoder succeeds or fails with any other return
662code.
663
664<P>
665Please look into ber_decoder.h for the precise definition of ber_decode()
666and related types.
667
668<P>
669
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]670<H2><A NAME="SECTION02212000000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]671Encoding DER
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]672</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]673
674<P>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]675The Distinguished Encoding Rules is the <I>canonical</I> variant of
676BER encoding rules. The DER is best suited to encode the structures
677where all the lengths are known beforehand. This is probably exactly
678how you want to encode: either after a BER decoding or after a manual
679fill-up, the target structure contains the data which size is implicitly
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]680known before encoding. Among other uses, the DER encoding is used
681to encode X.509 certificates.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]682
683<P>
684As with BER decoder, the DER encoder may be invoked either directly
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]685from the ASN.1 type descriptor (asn_DEF_Rectangle) or from the stand-alone
686function, which is somewhat simpler:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]687
688<P>
689
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]690<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]691&nbsp;
692/*
693&nbsp;*&nbsp;This&nbsp;is&nbsp;the&nbsp;serializer&nbsp;itself,
694&nbsp;*&nbsp;it&nbsp;supplies&nbsp;the&nbsp;DER&nbsp;encoder&nbsp;with&nbsp;the
695&nbsp;*&nbsp;pointer&nbsp;to&nbsp;the&nbsp;custom&nbsp;output&nbsp;function.
696&nbsp;*/
697ssize_t
698simple_serializer(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]699&nbsp;&nbsp;&nbsp;&nbsp;asn_enc_rval_t&nbsp;er;&nbsp;&nbsp;/*&nbsp;Encoder&nbsp;return&nbsp;value&nbsp;*/
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]700&nbsp;
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]701&nbsp;&nbsp;&nbsp;&nbsp;er&nbsp;=&nbsp;der_encode(&amp;asn_DEF_Rect,&nbsp;rect,
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]702&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;write_stream,&nbsp;ostream);
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]703&nbsp;&nbsp;&nbsp;&nbsp;if(er.<B>encoded</B>&nbsp;==&nbsp;-1)&nbsp;{
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]704&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]705&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;Failed&nbsp;to&nbsp;encode&nbsp;the&nbsp;rectangle&nbsp;data.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]706&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/
707&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Cannot&nbsp;encode&nbsp;%s:&nbsp;%s&#92;n'',
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]708&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;er.<B>failed_type</B>-&gt;name,
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]709&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strerror(errno));
710&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;-1;
711&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
712&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Return&nbsp;the&nbsp;number&nbsp;of&nbsp;bytes&nbsp;*/
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]713&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;er.encoded;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]714&nbsp;&nbsp;&nbsp;&nbsp;}
715}
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]716</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]717</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]718As you see, the DER encoder does not write into some sort of buffer
719or something. It just invokes the custom function (possible, multiple
720times) which would save the data into appropriate storage. The optional
721argument <I>app_key</I> is opaque for the DER encoder code and just
722used by <I>_write_stream()</I> as the pointer to the appropriate
723output stream to be used.
724
725<P>
726If the custom write function is not given (passed as 0), then the
727DER encoder will essentially do the same thing (i.e., encode the data)
728but no callbacks will be invoked (so the data goes nowhere). It may
729prove useful to determine the size of the structure's encoding before
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]730actually doing the encoding<A NAME="tex2html7"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]731 HREF="#foot250"><SUP>2.2</SUP></A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]732
733<P>
734Please look into der_encoder.h for the precise definition of der_encode()
735and related types.
736
737<P>
738
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]739<H2><A NAME="SECTION02213000000000000000"></A><A NAME="sub:Encoding-XER"></A><BR>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]740Encoding XER
741</H2>
742
743<P>
744The XER stands for XML Encoding Rules, where XML, in turn, is eXtensible
745Markup Language, a text-based format for information exchange. The
746encoder routine API comes in two flavors: stdio-based and callback-based.
747With the callback-based encoder, the encoding process is very similar
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]748to the DER one, described in Section <A HREF="#sub:Encoding-DER">Encoding DER</A>. The
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]749following example uses the definition of write_stream() from up there.
750
751<P>
752
753<BLOCKQUOTE><PRE>
754/*
755&nbsp;*&nbsp;This&nbsp;procedure&nbsp;generates&nbsp;the&nbsp;XML&nbsp;document
756&nbsp;*&nbsp;by&nbsp;invoking&nbsp;the&nbsp;XER&nbsp;encoder.
757&nbsp;*&nbsp;NOTE:&nbsp;Do&nbsp;not&nbsp;copy&nbsp;this&nbsp;code&nbsp;verbatim!
758&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;If&nbsp;the&nbsp;stdio&nbsp;output&nbsp;is&nbsp;necessary,
759&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;use&nbsp;the&nbsp;xer_fprint()&nbsp;procedure&nbsp;instead.
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]760&nbsp;*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;See&nbsp;Section&nbsp;<A HREF="#sub:Printing-the-target">Printing the target</A>.
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]761&nbsp;*/
762int
763print_as_XML(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{
764&nbsp;&nbsp;&nbsp;&nbsp;asn_enc_rval_t&nbsp;er;&nbsp;&nbsp;/*&nbsp;Encoder&nbsp;return&nbsp;value&nbsp;*/
765&nbsp;
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]766&nbsp;&nbsp;&nbsp;&nbsp;er&nbsp;=&nbsp;xer_encode(&amp;asn_DEF_Rectangle,&nbsp;rect,
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]767&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;XER_F_BASIC,&nbsp;/*&nbsp;BASIC-XER&nbsp;or&nbsp;CANONICAL-XER&nbsp;*/
768&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;write_stream,&nbsp;ostream);
769&nbsp;
770&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;(er.encoded&nbsp;==&nbsp;-1)&nbsp;?&nbsp;-1&nbsp;:&nbsp;0;
771}
772</PRE>
773</BLOCKQUOTE>
774Please look into xer_encoder.h for the precise definition of xer_encode()
775and related types.
776
777<P>
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]778See Section [<A HREF="#sub:Printing-the-target">Printing the target</A>] for the example of stdio-based
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]779XML encoder and other pretty-printing suggestions.
780
781<P>
782
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]783<H2><A NAME="SECTION02214000000000000000"></A><A NAME="sub:Decoding-XER"></A><BR>
784Decoding XER
785</H2>
786
787<P>
788The data encoded using the XER rules can be subsequently decoded using
789the xer_decode() API call:
790
791<P>
792
793<BLOCKQUOTE><PRE>
794Rectangle_t&nbsp;*
795XML_to_Rectangle(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
796&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
797&nbsp;&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;
798&nbsp;&nbsp;
799&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;xer_decode(0,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;(void&nbsp;**)&amp;rect,
800&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size);
801&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
802&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;*/
803&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
804&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Free&nbsp;partially&nbsp;decoded&nbsp;rect&nbsp;*/
805&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn_DEF_Rectangle-&gt;free_struct(
806&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect,&nbsp;0);
807&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
808&nbsp;&nbsp;&nbsp;&nbsp;}
809}
810</PRE>
811</BLOCKQUOTE>
812The decoder takes both BASIC-XER and CANONICAL-XER encodings.
813
814<P>
815The decoder shares its data consumption properties with BER decoder;
816please read the Section <A HREF="#sub:Decoding-BER">Decoding BER</A> to know more.
817
818<P>
819Please look into xer_decoder.h for the precise definition of xer_decode()
820and related types.
821
822<P>
823
824<H2><A NAME="SECTION02215000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]825Validating the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]826</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]827
828<P>
829Sometimes the target structure needs to be validated. For example,
830if the structure was created by the application (as opposed to being
831decoded from some external source), some important information required
832by the ASN.1 specification might be missing. On the other hand, the
833successful decoding of the data from some external source does not
834necessarily mean that the data is fully valid either. It might well
835be the case that the specification describes some subtype constraints
836that were not taken into account during decoding, and it would actually
837be useful to perform the last check when the data is ready to be encoded
838or when the data has just been decoded to ensure its validity according
839to some stricter rules.
840
841<P>
842The asn_check_constraints() function checks the type for various
843implicit and explicit constraints. It is recommended to use asn_check_constraints()
844function after each decoding and before each encoding.
845
846<P>
847Please look into constraints.h for the precise definition of asn_check_constraints()
848and related types.
849
850<P>
851
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]852<H2><A NAME="SECTION02216000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]853Printing the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]854</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]855
856<P>
857There are two ways to print the target structure: either invoke the
858print_struct member of the ASN.1 type descriptor, or using the asn_fprint()
859function, which is a simpler wrapper of the former:
860
861<P>
862
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]863<BLOCKQUOTE><PRE>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]864asn_fprint(stdout,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]865</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]866</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]867Please look into constr_TYPE.h for the precise definition of asn_fprint()
868and related types.
869
870<P>
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]871Another practical alternative to this custom format printing would
872be to invoke XER encoder. The default BASIC-XER encoder performs reasonable
873formatting for the output to be useful and human readable. To invoke
874the XER decoder in a manner similar to asn_fprint(), use the xer_fprint()
875call:
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]876
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]877<P>
878
879<BLOCKQUOTE><PRE>
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]880xer_fprint(stdout,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rect);
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]881</PRE>
882</BLOCKQUOTE>
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]883See Section <A HREF="#sub:Encoding-XER">Encoding XER</A> for XML-related details.
Lev Walkin683f9b72004-09-26 13:41:45 +0000[diff] [blame]884
885<P>
886
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]887<H2><A NAME="SECTION02217000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]888Freeing the target structure
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]889</H2>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]890
891<P>
892Freeing the structure is slightly more complex than it may seem to.
893When the ASN.1 structure is freed, all the members of the structure
894and their submembers etc etc are recursively freed too. But it might
895not be feasible to free the structure itself. Consider the following
896case:
897
898<P>
899
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]900<BLOCKQUOTE><PRE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]901struct&nbsp;my_figure&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;custom&nbsp;structure&nbsp;*/
902&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;flags;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;&lt;some&nbsp;custom&nbsp;member&gt;&nbsp;*/
903&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;type&nbsp;is&nbsp;generated&nbsp;by&nbsp;the&nbsp;ASN.1&nbsp;compiler&nbsp;*/
904&nbsp;&nbsp;&nbsp;&nbsp;<I>Rectangle_t&nbsp;rect;</I>
905&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;other&nbsp;members&nbsp;of&nbsp;the&nbsp;structure&nbsp;*/
906};
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]907</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]908</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]909In this example, the application programmer defined a custom structure
910with one ASN.1-derived member (rect). This member is not a reference
911to the Rectangle_t, but an in-place inclusion of the Rectangle_t
912structure. If the freeing is necessary, the usual procedure of freeing
913everything must not be applied to the &amp;rect pointer itself, because
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]914it does not point to the memory block directly allocated by the memory
915allocation routine, but instead lies within a block allocated for
916the my_figure structure.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]917
918<P>
919To solve this problem, the free_struct routine has the additional
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]920argument (besides the obvious type descriptor and target structure
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]921pointers), which is the flag specifying whether the outer pointer
922itself must be freed (0, default) or it should be left intact (non-zero
923value).
924
925<P>
926
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]927<BLOCKQUOTE><PRE>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]928<B>/*&nbsp;1.&nbsp;Rectangle_t&nbsp;is&nbsp;defined&nbsp;within&nbsp;my_figure&nbsp;*/</B>
929struct&nbsp;my_figure&nbsp;{
930&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;rect;
931}&nbsp;*mf&nbsp;=&nbsp;<B>...</B>;
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]932/*
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]933&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
934&nbsp;*&nbsp;without&nbsp;freeing&nbsp;the&nbsp;mf-&gt;rect&nbsp;area
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]935&nbsp;*/
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]936asn_DEF_Rectangle-&gt;free_struct(
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]937&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn_DEF_Rectangle,&nbsp;&amp;mf-&gt;rect,&nbsp;<B>1</B>&nbsp;<B>/*&nbsp;!free&nbsp;*/</B>);
938&nbsp;&nbsp;&nbsp;&nbsp;
939&nbsp;&nbsp;
940<B>/*&nbsp;2.&nbsp;Rectangle_t&nbsp;is&nbsp;a&nbsp;stand-alone&nbsp;pointer&nbsp;*/</B>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]941Rectangle_t&nbsp;*rect&nbsp;=&nbsp;<B>...</B>;
942/*
943&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
944&nbsp;*&nbsp;and&nbsp;freeing&nbsp;the&nbsp;rect&nbsp;pointer
945&nbsp;*/
Lev Walkinc500b3e2004-09-29 13:37:15 +0000[diff] [blame]946asn_DEF_Rectangle-&gt;free_struct(
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]947&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>);
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]948</PRE>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]949</BLOCKQUOTE>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]950It is safe to invoke the <I>free_struct</I> function with the target
951structure pointer set to 0 (NULL), the function will do nothing.
952
953<P>
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]954
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]955<H1><A NAME="SECTION02300000000000000000"></A><A NAME="cha:Step-by-step-examples"></A><BR>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]956Step by step examples
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]957</H1>
958
959<P>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]960
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]961<H1><A NAME="SECTION02310000000000000000">
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]962A ''Rectangle'' Encoder</A>
963</H1>
964
965<P>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]966This example will help you to create a simple BER and XER encoder
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]967of a ''Rectangle'' type used throughout this document.
968
969<P>
970
971<OL>
972<LI>Create a file named <B>rectangle.asn1</B> with the following contents:
973
974<P>
975
976<BLOCKQUOTE><PRE>
977RectangleModule1&nbsp;DEFINITIONS&nbsp;::=
978BEGIN
979&nbsp;
980Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
981&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
982&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
983}
984&nbsp;
985END
986</PRE>
987</BLOCKQUOTE>
988
989</LI>
990<LI>Compile it into the set of .c and .h files using asn1c compiler [<A
991 HREF="asn1c-usage.html#ASN1C">ASN1C</A>]:
992
993<P>
994
995<BLOCKQUOTE><PRE>
996<I>asn1c&nbsp;-fnative-types</I>&nbsp;<B>rectangle.asn1</B>
997</PRE>
998</BLOCKQUOTE>
999
1000</LI>
1001<LI>Alternatively, use the Online ASN.1 compiler [<A
1002 HREF="asn1c-usage.html#AONL">AONL</A>] by uploading
1003the <B>rectangle.asn1</B> file into the Web form and unpacking the
1004produced archive on your computer.
1005</LI>
1006<LI>By this time, you should have gotten multiple files in the current
1007directory, including the <B>Rectangle.c</B> and <B>Rectangle.h</B>.
1008</LI>
1009<LI>Create a main() routine which creates the Rectangle_t structure in
1010memory and encodes it using BER and XER encoding rules. Let's name
1011the file <B>main.c</B>:
1012
1013<P>
1014
1015<BLOCKQUOTE><PRE>
1016<FONT SIZE="-1">#include&nbsp;&lt;stdio.h&gt;</FONT>
1017<FONT SIZE="-1">#include&nbsp;&lt;sys/types.h&gt;</FONT>
1018<FONT SIZE="-1">#include&nbsp;&lt;Rectangle.h&gt;&nbsp;&nbsp;&nbsp;/*&nbsp;Rectangle&nbsp;ASN.1&nbsp;type&nbsp;&nbsp;*/</FONT>
1019&nbsp;
1020<FONT SIZE="-1">/*</FONT>
1021&nbsp;<FONT SIZE="-1">*&nbsp;This&nbsp;is&nbsp;a&nbsp;custom&nbsp;function&nbsp;which&nbsp;writes&nbsp;the</FONT>
1022&nbsp;<FONT SIZE="-1">*&nbsp;encoded&nbsp;output&nbsp;into&nbsp;some&nbsp;FILE&nbsp;stream.</FONT>
1023&nbsp;<FONT SIZE="-1">*/</FONT>
1024<FONT SIZE="-1">static&nbsp;int</FONT>
1025<FONT SIZE="-1">write_out(const&nbsp;void&nbsp;*buffer,&nbsp;size_t&nbsp;size,&nbsp;void&nbsp;*app_key)&nbsp;{</FONT>
1026&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;FILE&nbsp;*out_fp&nbsp;=&nbsp;app_key;</FONT>
1027&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;size_t&nbsp;wrote;</FONT>
1028&nbsp;
1029&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;wrote&nbsp;=&nbsp;fwrite(buffer,&nbsp;1,&nbsp;size,&nbsp;out_fp);</FONT>
1030&nbsp;
1031&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;return&nbsp;(wrote&nbsp;==&nbsp;size)&nbsp;?&nbsp;0&nbsp;:&nbsp;-1;</FONT>
1032<FONT SIZE="-1">}</FONT>
1033&nbsp;
Lev Walkin6b0df9f2005-01-31 15:06:32 +0000[diff] [blame]1034<FONT SIZE="-1">int&nbsp;main(int&nbsp;ac,&nbsp;char&nbsp;**av)&nbsp;{</FONT>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]1035&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rectangle;&nbsp;/*&nbsp;Type&nbsp;to&nbsp;encode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</FONT>
1036&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;asn_enc_rval_t&nbsp;ec;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Encoder&nbsp;return&nbsp;value&nbsp;&nbsp;*/</FONT>
1037&nbsp;
1038&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Allocate&nbsp;the&nbsp;Rectangle_t&nbsp;*/</FONT>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1039&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;rectangle&nbsp;=&nbsp;calloc(1,&nbsp;sizeof(Rectangle_t));&nbsp;/*&nbsp;not&nbsp;malloc!&nbsp;*/</FONT>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]1040&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(!rectangle)&nbsp;{</FONT>
1041&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;perror(''calloc()&nbsp;failed'');</FONT>
1042&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(71);&nbsp;/*&nbsp;better,&nbsp;EX_OSERR&nbsp;*/</FONT>
1043&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1044&nbsp;
1045&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Initialize&nbsp;the&nbsp;Rectangle&nbsp;members&nbsp;*/</FONT>
1046&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;rectangle-&gt;height&nbsp;=&nbsp;42;&nbsp;&nbsp;/*&nbsp;any&nbsp;random&nbsp;value&nbsp;*/</FONT>
1047&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;rectangle-&gt;width&nbsp;&nbsp;=&nbsp;23;&nbsp;&nbsp;/*&nbsp;any&nbsp;random&nbsp;value&nbsp;*/</FONT>
1048&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;</FONT>
1049&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;BER&nbsp;encode&nbsp;the&nbsp;data&nbsp;if&nbsp;filename&nbsp;is&nbsp;given&nbsp;*/</FONT>
1050&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(ac&nbsp;&lt;&nbsp;2)&nbsp;{</FONT>
1051&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Specify&nbsp;filename&nbsp;for&nbsp;BER&nbsp;output&#92;n'');</FONT>
1052&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{</FONT>
1053&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;const&nbsp;char&nbsp;*filename&nbsp;=&nbsp;av[1];</FONT>
1054&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;FILE&nbsp;*fp&nbsp;=&nbsp;fopen(filename,&nbsp;''w'');&nbsp;&nbsp;&nbsp;/*&nbsp;for&nbsp;BER&nbsp;output&nbsp;*/</FONT>
1055&nbsp;
1056&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if(!fp)&nbsp;{</FONT>
1057&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;perror(filename);</FONT>
1058&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(71);&nbsp;/*&nbsp;better,&nbsp;EX_OSERR&nbsp;*/</FONT>
1059&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}</FONT>
1060&nbsp;<FONT SIZE="-1">&nbsp;</FONT>
1061&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Encode&nbsp;the&nbsp;Rectangle&nbsp;type&nbsp;as&nbsp;BER&nbsp;(DER)&nbsp;*/</FONT>
1062&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ec&nbsp;=&nbsp;der_encode(&amp;asn_DEF_Rectangle,</FONT>
Lev Walkin6b0df9f2005-01-31 15:06:32 +0000[diff] [blame]1063&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rectangle,&nbsp;write_out,&nbsp;fp);</FONT>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]1064&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fclose(fp);</FONT>
1065&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if(ec.encoded&nbsp;==&nbsp;-1)&nbsp;{</FONT>
1066&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,</FONT>
1067&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;''Could&nbsp;not&nbsp;encode&nbsp;Rectangle&nbsp;(at&nbsp;%s)&#92;n'',</FONT>
1068&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ec.failed_type&nbsp;?&nbsp;ec.failed_type-&gt;name&nbsp;:&nbsp;''unknown'');</FONT>
1069&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(65);&nbsp;/*&nbsp;better,&nbsp;EX_DATAERR&nbsp;*/</FONT>
1070&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{</FONT>
1071&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Created&nbsp;%s&nbsp;with&nbsp;BER&nbsp;encoded&nbsp;Rectangle&#92;n'',</FONT>
1072&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename);</FONT>
1073&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;}</FONT>
1074&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1075&nbsp;
1076&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Also&nbsp;print&nbsp;the&nbsp;constructed&nbsp;Rectangle&nbsp;XER&nbsp;encoded&nbsp;(XML)&nbsp;*/</FONT>
1077&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;xer_fprint(stdout,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rectangle);</FONT>
1078&nbsp;
1079&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;return&nbsp;0;&nbsp;/*&nbsp;Encoding&nbsp;finished&nbsp;successfully&nbsp;*/</FONT>
1080<FONT SIZE="-1">}</FONT>
1081</PRE>
1082</BLOCKQUOTE>
1083
1084</LI>
1085<LI>Compile all files together using C compiler (varies by platform):
1086
1087<P>
1088
1089<BLOCKQUOTE><PRE>
1090<I>cc&nbsp;-I.&nbsp;-o</I>&nbsp;<B><I>rencode</I></B>&nbsp;<I>*.c</I>
1091</PRE>
1092</BLOCKQUOTE>
1093
1094</LI>
1095<LI>Voila! You have just created the BER and XER encoder of a Rectangle
1096type, named <B>rencode</B>!
1097</LI>
1098</OL>
1099
1100
1101<P>
1102
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1103<H1><A NAME="SECTION02320000000000000000"></A><A NAME="sec:A-Rectangle-Decoder"></A><BR>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1104A ''Rectangle'' Decoder
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]1105</H1>
1106
1107<P>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1108This example will help you to create a simple BER decoder of a simple
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]1109''Rectangle'' type used throughout this document.
1110
1111<P>
1112
1113<OL>
1114<LI>Create a file named <B>rectangle.asn1</B> with the following contents:
1115
1116<P>
1117
1118<BLOCKQUOTE><PRE>
1119RectangleModule1&nbsp;DEFINITIONS&nbsp;::=
1120BEGIN
1121&nbsp;
1122Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
1123&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
1124&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
1125}
1126&nbsp;
1127END
1128</PRE>
1129</BLOCKQUOTE>
1130
1131</LI>
1132<LI>Compile it into the set of .c and .h files using asn1c compiler [<A
1133 HREF="asn1c-usage.html#ASN1C">ASN1C</A>]:
1134
1135<P>
1136
1137<BLOCKQUOTE><PRE>
1138<I>asn1c&nbsp;-fnative-types</I>&nbsp;<B>rectangle.asn1</B>
1139</PRE>
1140</BLOCKQUOTE>
1141
1142</LI>
1143<LI>Alternatively, use the Online ASN.1 compiler [<A
1144 HREF="asn1c-usage.html#AONL">AONL</A>] by uploading
1145the <B>rectangle.asn1</B> file into the Web form and unpacking the
1146produced archive on your computer.
1147</LI>
1148<LI>By this time, you should have gotten multiple files in the current
1149directory, including the <B>Rectangle.c</B> and <B>Rectangle.h</B>.
1150</LI>
1151<LI>Create a main() routine which takes the binary input file, decodes
1152it as it were a BER-encoded Rectangle type, and prints out the text
1153(XML) representation of the Rectangle type. Let's name the file <B>main.c</B>:
1154
1155<P>
1156
1157<BLOCKQUOTE><PRE>
1158<FONT SIZE="-1">#include&nbsp;&lt;stdio.h&gt;</FONT>
1159<FONT SIZE="-1">#include&nbsp;&lt;sys/types.h&gt;</FONT>
1160<FONT SIZE="-1">#include&nbsp;&lt;Rectangle.h&gt;&nbsp;&nbsp;&nbsp;/*&nbsp;Rectangle&nbsp;ASN.1&nbsp;type&nbsp;&nbsp;*/</FONT>
1161&nbsp;
1162<FONT SIZE="-1">int&nbsp;main(int&nbsp;ac,&nbsp;char&nbsp;**av)&nbsp;{</FONT>
1163&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;char&nbsp;buf[1024];&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Temporary&nbsp;buffer&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</FONT>
1164&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rectangle&nbsp;=&nbsp;0;&nbsp;/*&nbsp;Type&nbsp;to&nbsp;decode&nbsp;*/</FONT>
1165&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;asn_dec_rval_t&nbsp;rval;&nbsp;/*&nbsp;Decoder&nbsp;return&nbsp;value&nbsp;&nbsp;*/</FONT>
1166&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;FILE&nbsp;*fp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Input&nbsp;file&nbsp;handler&nbsp;&nbsp;&nbsp;&nbsp;*/</FONT>
1167&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;size_t&nbsp;size;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Number&nbsp;of&nbsp;bytes&nbsp;read&nbsp;&nbsp;*/</FONT>
1168&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;char&nbsp;*filename;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Input&nbsp;file&nbsp;name&nbsp;*/</FONT>
1169&nbsp;
1170&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Require&nbsp;a&nbsp;single&nbsp;filename&nbsp;argument&nbsp;*/</FONT>
1171&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(ac&nbsp;!=&nbsp;2)&nbsp;{</FONT>
1172&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Usage:&nbsp;%s&nbsp;&lt;file.ber&gt;&#92;n'',&nbsp;av[0]);</FONT>
1173&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(64);&nbsp;/*&nbsp;better,&nbsp;EX_USAGE&nbsp;*/</FONT>
1174&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{</FONT>
1175&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename&nbsp;=&nbsp;av[1];</FONT>
1176&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1177&nbsp;
1178&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Open&nbsp;input&nbsp;file&nbsp;as&nbsp;read-only&nbsp;binary&nbsp;*/</FONT>
1179&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;fp&nbsp;=&nbsp;fopen(filename,&nbsp;''rb'');</FONT>
1180&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(!fp)&nbsp;{</FONT>
1181&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;perror(filename);</FONT>
1182&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(66);&nbsp;/*&nbsp;better,&nbsp;EX_NOINPUT&nbsp;*/</FONT>
1183&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1184&nbsp;<FONT SIZE="-1">&nbsp;</FONT>
1185&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Read&nbsp;up&nbsp;to&nbsp;the&nbsp;buffer&nbsp;size&nbsp;*/</FONT>
1186&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;size&nbsp;=&nbsp;fread(buf,&nbsp;1,&nbsp;sizeof(buf),&nbsp;fp);</FONT>
1187&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;fclose(fp);</FONT>
1188&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(!size)&nbsp;{</FONT>
1189&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''%s:&nbsp;Empty&nbsp;or&nbsp;broken&#92;n'',&nbsp;filename);</FONT>
1190&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(65);&nbsp;/*&nbsp;better,&nbsp;EX_DATAERR&nbsp;*/</FONT>
1191&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1192&nbsp;
1193&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Decode&nbsp;the&nbsp;input&nbsp;buffer&nbsp;as&nbsp;Rectangle&nbsp;type&nbsp;*/</FONT>
1194&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;ber_decode(0,&nbsp;&amp;asn_DEF_Rectangle,</FONT>
1195&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rectangle,&nbsp;buf,&nbsp;size);</FONT>
1196&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;if(rval.code&nbsp;!=&nbsp;RC_OK)&nbsp;{</FONT>
1197&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,</FONT>
1198&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;''%s:&nbsp;Broken&nbsp;Rectangle&nbsp;encoding&nbsp;at&nbsp;byte&nbsp;%ld&#92;n'',</FONT>
1199&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;filename,&nbsp;(long)rval.consumed);</FONT>
1200&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;exit(65);&nbsp;/*&nbsp;better,&nbsp;EX_DATAERR&nbsp;*/</FONT>
1201&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;}</FONT>
1202&nbsp;
1203&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;/*&nbsp;Print&nbsp;the&nbsp;decoded&nbsp;Rectangle&nbsp;type&nbsp;as&nbsp;XML&nbsp;*/</FONT>
1204&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;xer_fprint(stdout,&nbsp;&amp;asn_DEF_Rectangle,&nbsp;rectangle);</FONT>
1205&nbsp;
1206&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;return&nbsp;0;&nbsp;/*&nbsp;Decoding&nbsp;finished&nbsp;successfully&nbsp;*/</FONT>
1207<FONT SIZE="-1">}</FONT>
1208</PRE>
1209</BLOCKQUOTE>
1210
1211</LI>
1212<LI>Compile all files together using C compiler (varies by platform):
1213
1214<P>
1215
1216<BLOCKQUOTE><PRE>
1217<I>cc&nbsp;-I.&nbsp;-o</I>&nbsp;<B><I>rdecode</I></B>&nbsp;<I>*.c</I>
1218</PRE>
1219</BLOCKQUOTE>
1220
1221</LI>
Lev Walkine94e3e52005-01-31 10:18:53 +0000[diff] [blame]1222<LI>Voila! You have just created the BER decoder of a Rectangle type,
1223named <B>rdecode</B>!
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]1224</LI>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1225</OL>
1226
1227<P>
1228
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1229<H1><A NAME="SECTION02400000000000000000">
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1230Constraint validation examples</A>
1231</H1>
1232
1233<P>
1234This chapter shows how to define ASN.1 constraints and use the generated
1235validation code.
1236
1237<P>
1238
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1239<H1><A NAME="SECTION02410000000000000000">
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1240Adding constraints into ''Rectangle'' type</A>
1241</H1>
1242
1243<P>
1244This example shows how to add basic constraints to the ASN.1 specification
1245and how to invoke the constraints validation code in your application.
1246
1247<P>
1248
1249<OL>
1250<LI>Create a file named <B>rectangle.asn1</B> with the following contents:
1251
1252<P>
1253
1254<BLOCKQUOTE><PRE>
1255RectangleModuleWithConstraints&nbsp;DEFINITIONS&nbsp;::=
1256BEGIN
1257&nbsp;
1258Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
1259&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER&nbsp;(0..100),&nbsp;--&nbsp;Value&nbsp;range&nbsp;constraint
1260&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER&nbsp;(0..MAX)&nbsp;&nbsp;--&nbsp;Makes&nbsp;width&nbsp;non-negative&nbsp;
1261}
1262&nbsp;
1263END
1264</PRE>
1265</BLOCKQUOTE>
1266
1267</LI>
1268<LI>Compile the file according to procedures shown in the previous chapter.
1269</LI>
1270<LI>Modify the Rectangle type processing routine (you can start with the
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]1271main() routine shown in the Section <A HREF="#sec:A-Rectangle-Decoder">A Rectangle Decoder</A>)
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1272by placing the following snippet of code <I>before</I> encoding and/or
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1273<I>after</I> decoding the Rectangle type<A NAME="tex2html8"
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1274 HREF="#foot923"><SUP>4.1</SUP></A>:
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1275
1276<P>
1277
1278<BLOCKQUOTE><PRE>
1279<FONT SIZE="-1">int&nbsp;ret;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Return&nbsp;value&nbsp;*/</FONT>
1280<FONT SIZE="-1">char&nbsp;errbuf[128];&nbsp;&nbsp;/*&nbsp;Buffer&nbsp;for&nbsp;error&nbsp;message&nbsp;*/</FONT>
1281<FONT SIZE="-1">size_t&nbsp;errlen&nbsp;=&nbsp;sizeof(errbuf);&nbsp;&nbsp;/*&nbsp;Size&nbsp;of&nbsp;the&nbsp;buffer&nbsp;*/</FONT>
1282&nbsp;<FONT SIZE="-1">&nbsp;</FONT>
1283<FONT SIZE="-1">/*&nbsp;...&nbsp;here&nbsp;may&nbsp;go&nbsp;Rectangle&nbsp;decoding&nbsp;code&nbsp;...&nbsp;*/</FONT>
1284&nbsp;
1285<FONT SIZE="-1">ret&nbsp;=&nbsp;asn_check_constraints(asn_DEF_Rectangle,</FONT>
1286&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rectangle,&nbsp;errbuf,&nbsp;&amp;errlen);</FONT>
1287<FONT SIZE="-1">/*&nbsp;assert(errlen&nbsp;&lt;&nbsp;sizeof(errbuf));&nbsp;//&nbsp;you&nbsp;may&nbsp;rely&nbsp;on&nbsp;that&nbsp;*/</FONT>
1288<FONT SIZE="-1">if(ret)&nbsp;{</FONT>
1289&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Constraint&nbsp;validation&nbsp;failed:&nbsp;%s&#92;n'',</FONT>
1290&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;errbuf&nbsp;&nbsp;&nbsp;/*&nbsp;errbuf&nbsp;is&nbsp;properly&nbsp;nul-terminated&nbsp;*/</FONT>
1291&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);</FONT>
1292&nbsp;<FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;exit(...);&nbsp;//&nbsp;Replace&nbsp;with&nbsp;appropriate&nbsp;action&nbsp;*/</FONT>
1293<FONT SIZE="-1">}</FONT>
1294&nbsp;
1295<FONT SIZE="-1">/*&nbsp;...&nbsp;here&nbsp;may&nbsp;go&nbsp;Rectangle&nbsp;encoding&nbsp;code&nbsp;...&nbsp;*/</FONT>
1296</PRE>
1297</BLOCKQUOTE>
1298
1299</LI>
1300<LI>Compile the resulting C code as shown in the previous chapters.
1301</LI>
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]1302<LI>Try to test the constraints checking code by assigning integer value
1303101 to the <B>.height</B> member of the Rectangle structure, or
1304a negative value to the <B>.width</B> member. In either case, the
1305program should print ''Constraint validation failed'' message, followed
1306by the short explanation why validation did not succeed.
1307</LI>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1308<LI>Done.
1309</LI>
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1310</OL>
1311
1312<P>
1313
1314<H1><A NAME="SECTION03000000000000000000"></A><A NAME="par:ASN.1-Basics"></A><BR>
1315ASN.1 Basics
1316</H1>
1317
1318<P>
1319
1320<H1><A NAME="SECTION03100000000000000000"></A><A NAME="cha:Abstract-Syntax-Notation:"></A><BR>
1321Abstract Syntax Notation: ASN.1
1322</H1>
1323
1324<P>
1325<I>This chapter defines some basic ASN.1 concepts and describes
1326several most widely used types. It is by no means an authoritative
1327or complete reference. For more complete ASN.1 description, please
1328refer to Olivier Dubuisson's book [<A
1329 HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
1330of standards itself [<A
1331 HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
1332
1333<P>
1334The Abstract Syntax Notation One is used to formally describe the
1335semantics of data transmitted across the network. Two communicating
1336parties may have different formats of their native data types (i.e.
1337number of bits in the integer type), thus it is important to have
1338a way to describe the data in a manner which is independent from the
1339particular machine's representation. The ASN.1 specifications are
1340used to achieve the following:
1341
1342<P>
1343
1344<UL>
1345<LI>The specification expressed in the ASN.1 notation is a formal and
1346precise way to communicate the data semantics to human readers;
1347</LI>
1348<LI>The ASN.1 specifications may be used as input for automatic compilers
1349which produce the code for some target language (C, C++, Java, etc)
1350to encode and decode the data according to some encoding rules (which
1351are also defined by the ASN.1 standard).
1352</LI>
1353</UL>
1354Consider the following example:
1355
1356<P>
1357
1358<BLOCKQUOTE><PRE>
1359Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
1360&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
1361&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
1362}
1363</PRE>
1364</BLOCKQUOTE>
1365This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
1366containing two integer fields. This specification may tell the reader
1367that there exists this kind of data structure and that some entity
1368may be prepared to send or receive it. The question on <I>how</I>
1369that entity is going to send or receive the <I>encoded data</I> is
1370outside the scope of ASN.1. For example, this data structure may be
1371encoded according to some encoding rules and sent to the destination
1372using the TCP protocol. The ASN.1 specifies several ways of encoding
1373(or ''serializing'', or ''marshaling'') the data: BER, PER, XER
1374and others, including CER and DER derivatives from BER.
1375
1376<P>
1377The complete specification must be wrapped in a module, which looks
1378like this:
1379
1380<P>
1381
1382<BLOCKQUOTE><PRE>
1383RectangleModule1
1384&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;iso&nbsp;org(3)&nbsp;dod(6)&nbsp;internet(1)&nbsp;private(4)
1385&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enterprise(1)&nbsp;spelio(9363)&nbsp;software(1)
1386&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1c(5)&nbsp;docs(2)&nbsp;rectangle(1)&nbsp;1&nbsp;}&nbsp;
1387&nbsp;&nbsp;&nbsp;&nbsp;DEFINITIONS&nbsp;AUTOMATIC&nbsp;TAGS&nbsp;::=
1388BEGIN
1389&nbsp;
1390--&nbsp;This&nbsp;is&nbsp;a&nbsp;comment&nbsp;which&nbsp;describes&nbsp;nothing.
1391Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
1392&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
1393&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
1394}
1395&nbsp;
1396END
1397</PRE>
1398</BLOCKQUOTE>
1399The module header consists of module name (RectangleModule1), the
1400module object identifier ({...}), a keyword ''DEFINITIONS'', a
1401set of module flags (AUTOMATIC TAGS) and ''::= BEGIN''. The module
1402ends with an ''END'' statement.
1403
1404<P>
1405
1406<H1><A NAME="SECTION03110000000000000000">
1407Some of the ASN.1 Basic Types</A>
1408</H1>
1409
1410<P>
1411
1412<H2><A NAME="SECTION03111000000000000000">
1413The BOOLEAN type</A>
1414</H2>
1415
1416<P>
1417The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
1418or a similar kind of two-way choice.
1419
1420<P>
1421
1422<H2><A NAME="SECTION03112000000000000000">
1423The INTEGER type</A>
1424</H2>
1425
1426<P>
1427The INTEGER type is a signed natural number type without any restrictions
1428on its size. If the automatic checking on INTEGER value bounds are
1429necessary, the subtype constraints must be used.
1430
1431<P>
1432
1433<BLOCKQUOTE><PRE>
1434SimpleInteger&nbsp;::=&nbsp;INTEGER
1435&nbsp;
1436--&nbsp;An&nbsp;integer&nbsp;with&nbsp;a&nbsp;very&nbsp;limited&nbsp;range
1437SmallPositiveInt&nbsp;::=&nbsp;INTEGER&nbsp;(0..127)
1438&nbsp;
1439--&nbsp;Integer,&nbsp;negative
1440NegativeInt&nbsp;::=&nbsp;INTEGER&nbsp;(MIN..0)
1441</PRE>
1442</BLOCKQUOTE>
1443
1444<P>
1445
1446<H2><A NAME="SECTION03113000000000000000">
1447The ENUMERATED type</A>
1448</H2>
1449
1450<P>
1451The ENUMERATED type is semantically equivalent to the INTEGER type
1452with some integer values explicitly named.
1453
1454<P>
1455
1456<BLOCKQUOTE><PRE>
1457FruitId&nbsp;::=&nbsp;ENUMERATED&nbsp;{&nbsp;apple(1),&nbsp;orange(2)&nbsp;}
1458&nbsp;
1459--&nbsp;The&nbsp;numbers&nbsp;in&nbsp;braces&nbsp;are&nbsp;optional,
1460--&nbsp;the&nbsp;enumeration&nbsp;can&nbsp;be&nbsp;performed
1461--&nbsp;automatically&nbsp;by&nbsp;the&nbsp;compiler
1462ComputerOSType&nbsp;::=&nbsp;ENUMERATED&nbsp;{
1463&nbsp;&nbsp;&nbsp;&nbsp;FreeBSD,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;0
1464&nbsp;&nbsp;&nbsp;&nbsp;Windows,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;acquires&nbsp;value&nbsp;1
1465&nbsp;&nbsp;&nbsp;&nbsp;Solaris(5),&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;remains&nbsp;5
1466&nbsp;&nbsp;&nbsp;&nbsp;Linux,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;6
1467&nbsp;&nbsp;&nbsp;&nbsp;MacOS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;becomes&nbsp;7
1468}
1469</PRE>
1470</BLOCKQUOTE>
1471
1472<P>
1473
1474<H2><A NAME="SECTION03114000000000000000">
1475The OCTET STRING type</A>
1476</H2>
1477
1478<P>
1479This type models the sequence of 8-bit bytes. This may be used to
1480transmit some opaque data or data serialized by other types of encoders
1481(i.e. video file, photo picture, etc).
1482
1483<P>
1484
1485<H2><A NAME="SECTION03115000000000000000">
1486The OBJECT IDENTIFIER type</A>
1487</H2>
1488
1489<P>
1490The OBJECT IDENTIFIER is used to represent the unique identifier of
1491any object, starting from the very root of the registration tree.
1492If your organization needs to uniquely identify something (a router,
1493a room, a person, a standard, or whatever), you are encouraged to
1494get your own identification subtree at <A HREF=http://www.iana.org/protocols/forms.htm>http://www.iana.org/protocols/forms.htm</A>.
1495
1496<P>
1497For example, the very first ASN.1 module in this Chapter (RectangleModule1)
1498has the following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
1499
1500<P>
1501
1502<BLOCKQUOTE><PRE>
1503ExampleOID&nbsp;::=&nbsp;OBJECT&nbsp;IDENTIFIER
1504&nbsp;
1505rectangleModule1-oid&nbsp;ExampleOID
1506&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;}
1507&nbsp;
1508--&nbsp;An&nbsp;identifier&nbsp;of&nbsp;the&nbsp;Internet.
1509internet-id&nbsp;OBJECT&nbsp;IDENTIFIER
1510&nbsp;&nbsp;::=&nbsp;{&nbsp;iso(1)&nbsp;identified-organization(3)
1511&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dod(6)&nbsp;internet(1)&nbsp;}
1512</PRE>
1513</BLOCKQUOTE>
1514As you see, names are optional.
1515
1516<P>
1517
1518<H2><A NAME="SECTION03116000000000000000">
1519The RELATIVE-OID type</A>
1520</H2>
1521
1522<P>
1523The RELATIVE-OID type has the semantics of a subtree of an OBJECT
1524IDENTIFIER. There may be no need to repeat the whole sequence of numbers
1525from the root of the registration tree where the only thing of interest
1526is some of the tree's subsequence.
1527
1528<P>
1529
1530<BLOCKQUOTE><PRE>
1531this-document&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{&nbsp;docs(2)&nbsp;usage(1)&nbsp;}
1532&nbsp;
1533this-example&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{
1534&nbsp;&nbsp;&nbsp;&nbsp;this-document&nbsp;assorted-examples(0)&nbsp;this-example(1)&nbsp;}
1535</PRE>
1536</BLOCKQUOTE>
1537
1538<P>
1539
1540<H1><A NAME="SECTION03120000000000000000">
1541Some of the ASN.1 String Types</A>
1542</H1>
1543
1544<P>
1545
1546<H2><A NAME="SECTION03121000000000000000">
1547The IA5String type</A>
1548</H2>
1549
1550<P>
1551This is essentially the ASCII, with 128 character codes available
1552(7 lower bits of an 8-bit byte).
1553
1554<P>
1555
1556<H2><A NAME="SECTION03122000000000000000">
1557The UTF8String type</A>
1558</H2>
1559
1560<P>
1561This is the character string which encodes the full Unicode range
1562(4 bytes) using multibyte character sequences.
1563
1564<P>
1565
1566<H2><A NAME="SECTION03123000000000000000">
1567The NumericString type</A>
1568</H2>
1569
1570<P>
1571This type represents the character string with the alphabet consisting
1572of numbers (''0'' to ''9'') and a space.
1573
1574<P>
1575
1576<H2><A NAME="SECTION03124000000000000000">
1577The PrintableString type</A>
1578</H2>
1579
1580<P>
1581The character string with the following alphabet: space, ''<B>'</B>''
1582(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
1583''<B>,</B>'' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
1584digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
1585upper-case and lower-case letters (''A'' to ''Z'' and ''a''
1586to ''z'').
1587
1588<P>
1589
1590<H2><A NAME="SECTION03125000000000000000">
1591The VisibleString type</A>
1592</H2>
1593
1594<P>
1595The character string with the alphabet which is more or less a subset
1596of ASCII between the space and the ''<B>~</B>''
1597symbol (tilde).
1598
1599<P>
1600Alternatively, the alphabet may be described as the PrintableString
1601alphabet presented earlier, plus the following characters: ''<B>!</B>'',
1602''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
1603''<B>&amp;</B>'', ''<B>*</B>'', ''<B>;</B>'', ''<B>&lt;</B>'',
1604''<B>&gt;</B>'', ''<B>[</B>'', ''<B>&#92;</B>'',
1605''<B>]</B>'', ''<B>&#94;</B>'', ''<B>_</B>'',
1606''<B>`</B>'' (single left quote), ''<B>{</B>'', ''<B>|</B>'',
1607''<B>}</B>'', ''<B>~</B>''.
1608
1609<P>
1610
1611<H1><A NAME="SECTION03130000000000000000">
1612ASN.1 Constructed Types</A>
1613</H1>
1614
1615<P>
1616
1617<H2><A NAME="SECTION03131000000000000000">
1618The SEQUENCE type</A>
1619</H2>
1620
1621<P>
1622This is an ordered collection of other simple or constructed types.
1623The SEQUENCE constructed type resembles the C ''struct'' statement.
1624
1625<P>
1626
1627<BLOCKQUOTE><PRE>
1628Address&nbsp;::=&nbsp;SEQUENCE&nbsp;{
1629&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;The&nbsp;apartment&nbsp;number&nbsp;may&nbsp;be&nbsp;omitted
1630&nbsp;&nbsp;&nbsp;&nbsp;apartmentNumber&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL,
1631&nbsp;&nbsp;&nbsp;&nbsp;streetName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
1632&nbsp;&nbsp;&nbsp;&nbsp;cityName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
1633&nbsp;&nbsp;&nbsp;&nbsp;stateName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
1634&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;This&nbsp;one&nbsp;may&nbsp;be&nbsp;omitted&nbsp;too
1635&nbsp;&nbsp;&nbsp;&nbsp;zipNo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL
1636}
1637</PRE>
1638</BLOCKQUOTE>
1639
1640<P>
1641
1642<H2><A NAME="SECTION03132000000000000000">
1643The SET type</A>
1644</H2>
1645
1646<P>
1647This is a collection of other simple or constructed types. Ordering
1648is not important. The data may arrive in the order which is different
1649from the order of specification. Data is encoded in the order not
1650necessarily corresponding to the order of specification.
1651
1652<P>
1653
1654<H2><A NAME="SECTION03133000000000000000">
1655The CHOICE type</A>
1656</H2>
1657
1658<P>
1659This type is just a choice between the subtypes specified in it. The
1660CHOICE type contains at most one of the subtypes specified, and it
1661is always implicitly known which choice is being decoded or encoded.
1662This one resembles the C ''union'' statement.
1663
1664<P>
1665The following type defines a response code, which may be either an
1666integer code or a boolean ''true''/''false'' code.
1667
1668<P>
1669
1670<BLOCKQUOTE><PRE>
1671ResponseCode&nbsp;::=&nbsp;CHOICE&nbsp;{
1672&nbsp;&nbsp;&nbsp;&nbsp;intCode&nbsp;&nbsp;&nbsp;&nbsp;INTEGER,
1673&nbsp;&nbsp;&nbsp;&nbsp;boolCode&nbsp;&nbsp;&nbsp;BOOLEAN
1674}
1675</PRE>
1676</BLOCKQUOTE>
1677
1678<P>
1679
1680<H2><A NAME="SECTION03134000000000000000">
1681The SEQUENCE OF type</A>
1682</H2>
1683
1684<P>
1685This one is the list (array) of simple or constructed types:
1686
1687<P>
1688
1689<BLOCKQUOTE><PRE>
1690--&nbsp;Example&nbsp;1
1691ManyIntegers&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;INTEGER
1692&nbsp;
1693--&nbsp;Example&nbsp;2
1694ManyRectangles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;Rectangle
1695&nbsp;
1696--&nbsp;More&nbsp;complex&nbsp;example:
1697--&nbsp;an&nbsp;array&nbsp;of&nbsp;structures&nbsp;defined&nbsp;in&nbsp;place.
1698ManyCircles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;SEQUENCE&nbsp;{
1699&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
1700&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;}
1701</PRE>
1702</BLOCKQUOTE>
1703
1704<P>
1705
1706<H2><A NAME="SECTION03135000000000000000">
1707The SET OF type</A>
1708</H2>
1709
1710<P>
1711The SET OF type models the bag of structures. It resembles the SEQUENCE
1712OF type, but the order is not important: i.e. the elements may arrive
1713in the order which is not necessarily the same as the in-memory order
1714on the remote machines.
1715
1716<P>
1717
1718<BLOCKQUOTE><PRE>
1719--&nbsp;A&nbsp;set&nbsp;of&nbsp;structures&nbsp;defined&nbsp;elsewhere
1720SetOfApples&nbsp;::&nbsp;SET&nbsp;OF&nbsp;Apple
1721&nbsp;
1722--&nbsp;Set&nbsp;of&nbsp;integers&nbsp;encoding&nbsp;the&nbsp;kind&nbsp;of&nbsp;a&nbsp;fruit
1723FruitBag&nbsp;::=&nbsp;SET&nbsp;OF&nbsp;ENUMERATED&nbsp;{&nbsp;apple,&nbsp;orange&nbsp;}
1724</PRE>
1725</BLOCKQUOTE>
1726
1727<H2><A NAME="SECTION04000000000000000000">
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1728Bibliography</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1729</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]1730<DD>The Open Source ASN.1 Compiler. <A HREF=http://lionet.info/asn1c>http://lionet.info/asn1c</A>
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]1731<P></P><DT><A NAME="AONL">AONL</A>
Lev Walkin1411d052005-02-02 11:06:38 +0000[diff] [blame]1732<DD>Online ASN.1 Compiler. <A HREF=http://lionet.info/asn1c/asn1c.cgi>http://lionet.info/asn1c/asn1c.cgi</A>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1733<P></P><DT><A NAME="Dub00">Dub00</A>
Lev Walkin028a28b2005-01-17 11:09:32 +0000[diff] [blame]1734<DD>Olivier Dubuisson -- <I>ASN.1 Communication between heterogeneous
1735systems</I> -- Morgan Kaufmann Publishers, 2000. <A HREF=http://asn1.elibel.tm.fr/en/book/>http://asn1.elibel.tm.fr/en/book/</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1736ISBN:0-12-6333361-0.
1737<P></P><DT><A NAME="ITU-T_ASN.1">ITU-T/ASN.1</A>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1738<DD>ITU-T Study Group 17 - Languages for Telecommunication Systems <A HREF=http://www.itu.int/ITU-T/studygroups/com17/languages/>http://www.itu.int/ITU-T/studygroups/com17/languages/</A>
1739</DL>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1740
1741<P>
1742<BR><HR><H4>Footnotes</H4>
1743<DL>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1744<DT><A NAME="foot843">... given</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1745 HREF="asn1c-usage.html#tex2html1"><SUP>1.1</SUP></A></DT>
1746<DD>Please look into Part par:ASN.1-Basics for a quick reference
1747on how to understand the ASN.1 notation.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1748
1749</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1750<DT><A NAME="foot844">... type</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1751 HREF="asn1c-usage.html#tex2html2"><SUP>1.2</SUP></A></DT>
Lev Walkin6faa68e2004-09-17 08:35:02 +0000[diff] [blame]1752<DD><I>-fnative-types</I> compiler option is used to produce basic C <I>int</I>
1753types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table 1</A>.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1754
1755</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1756<DT><A NAME="foot845">...asn1c</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1757 HREF="asn1c-usage.html#tex2html3"><SUP>1.3</SUP></A></DT>
Lev Walkin26587ab2004-08-23 15:12:04 +0000[diff] [blame]1758<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
1759
1760</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1761<DT><A NAME="foot846">... module</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1762 HREF="asn1c-usage.html#tex2html4"><SUP>1.4</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1763<DD>This is probably <B>not</B> what you want to try out right now -
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1764read through the rest of this chapter and check the <A HREF=#Table1>Table 1</A>
1765to find out about <B>-P</B> and <B>-R</B> options.
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1766
1767</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1768<DT><A NAME="foot181">...restartable</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1769 HREF="asn1c-usage.html#tex2html6"><SUP>2.1</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1770<DD>Restartable means that if the decoder encounters the end of the buffer,
1771it will fail, but may later be invoked again with the rest of the
1772buffer to continue decoding.
1773
1774</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1775<DT><A NAME="foot250">... encoding</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1776 HREF="asn1c-usage.html#tex2html7"><SUP>2.2</SUP></A></DT>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1777<DD>It is actually faster too: the encoder might skip over some computations
1778which aren't important for the size determination.
1779
1780</DD>
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]1781<DT><A NAME="foot923">... type</A><A
Lev Walkin7f70fe52005-02-22 07:28:26 +0000[diff] [blame]1782 HREF="asn1c-usage.html#tex2html8"><SUP>4.1</SUP></A></DT>
Lev Walkindee61782005-02-02 09:53:46 +0000[diff] [blame]1783<DD>Placing the constraint checking code <I>before</I> encoding helps
1784to make sure you know the data is correct and within constraints before
1785sharing the data with anyone else.
1786
1787<P>
1788Placing the constraint checking code <I>after</I> decoding, but before
1789any further action depending on the decoded data, helps to make sure
1790the application got the valid contents before making use of it.
1791
1792</DD>
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1793</DL><BR><HR>
1794<ADDRESS>
1795Lev Walkin
Lev Walkinf47d0682005-03-05 01:07:04 +0000[diff] [blame]17962005-03-04
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1797</ADDRESS>
1798</BODY>
1799</HTML>