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