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