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