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