Gitiles
Code Review Sign In
gerrit.osmocom.org / asn1c / 4d9fbb48074a3c8a3a220d4e21a9784c53dd7385 / . / doc / asn1c-usage.html
blob: 8aeafae17a67f034213a9f8dcd61e361e96169c1 [file] [log] [blame]
Lev Walkineb97a702004-08-07 06:03:15 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3<!--Converted with LaTeX2HTML 2002-2-1 (1.70)
4original version by: Nikos Drakos, CBLU, University of Leeds
5* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6* with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
8<HTML>
9<HEAD>
10<TITLE>Using the Free ASN.1 Compiler</TITLE>
11<META NAME="description" CONTENT="Using the Free ASN.1 Compiler">
12<META NAME="asn1c, ASN.1, free, compiler, BER, DER, PER, XER\">
13
14<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
15<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
16
17
18</HEAD>
19
20<BODY >
21
22<P>
23
24<P>
25
26<P>
27<H1 ALIGN="CENTER">Using the Free ASN.1 Compiler</H1><DIV>
28
29<P ALIGN="CENTER"><STRONG>Lev Walkin &lt;vlm@lionet.info&gt;</STRONG></P>
30</DIV>
31<BR>
32
33<H2><A NAME="SECTION01000000000000000000">
34Contents</A>
35</H2>
36<!--Table of Contents-->
37
38<UL>
39<LI><A NAME="tex2html38"
40 HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A>
41<UL>
42<LI><A NAME="tex2html39"
43 HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A>
44<UL>
45<LI><A NAME="tex2html40"
46 HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A>
47<UL>
48<LI><A NAME="tex2html41"
49 HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
50<LI><A NAME="tex2html42"
51 HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
52<LI><A NAME="tex2html43"
53 HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
54<LI><A NAME="tex2html44"
55 HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
56<LI><A NAME="tex2html45"
57 HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
58<LI><A NAME="tex2html46"
59 HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A>
60</UL>
61<LI><A NAME="tex2html47"
62 HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A>
63<UL>
64<LI><A NAME="tex2html48"
65 HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
66<LI><A NAME="tex2html49"
67 HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
68<LI><A NAME="tex2html50"
69 HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
70<LI><A NAME="tex2html51"
71 HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
72<LI><A NAME="tex2html52"
73 HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A>
74</UL>
75<LI><A NAME="tex2html53"
76 HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A>
77<UL>
78<LI><A NAME="tex2html54"
79 HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
80<LI><A NAME="tex2html55"
81 HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
82<LI><A NAME="tex2html56"
83 HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
84<LI><A NAME="tex2html57"
85 HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
86<LI><A NAME="tex2html58"
87 HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A>
88</UL>
89</UL>
90</UL><BR>
91<LI><A NAME="tex2html59"
92 HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A>
93<UL>
94<LI><A NAME="tex2html60"
95 HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
96<UL>
97<LI><A NAME="tex2html61"
98 HREF="asn1c-usage.html#SECTION03110000000000000000">Quick start</A>
99<LI><A NAME="tex2html62"
100 HREF="asn1c-usage.html#SECTION03120000000000000000">Slow start</A>
101<UL>
102<LI><A NAME="tex2html63"
103 HREF="asn1c-usage.html#SECTION03121000000000000000">Recognizing compiler output</A>
104<LI><A NAME="tex2html64"
105 HREF="asn1c-usage.html#SECTION03122000000000000000">Invoking the ASN.1 helper code from the application</A>
106</UL>
107</UL>
108</UL><BR>
109<LI><A NAME="tex2html65"
110 HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
111</UL>
112<!--End of Table of Contents-->
113
114<P>
115
116<H1><A NAME="SECTION02000000000000000000">
117ASN.1 Basics</A>
118</H1>
119
120<P>
121
122<H1><A NAME="SECTION02100000000000000000">
123Abstract Syntax Notation: ASN.1</A>
124</H1>
125
126<P>
127<I>This chapter defines some basic ASN.1 concepts and describes
128several most widely used types. It is by no means an authoritative
129or complete reference. For more complete ASN.1 description, please
130refer to Olivier Dubuisson's book [<A
131 HREF="asn1c-usage.html#Dub00">Dub00</A>] or the ASN.1 body
132of standards itself [<A
133 HREF="asn1c-usage.html#ITU-T_ASN.1">ITU-T/ASN.1</A>].</I>
134
135<P>
136The Abstract Syntax Notation One is used to formally describe the
137semantics of data transmitted across the network. Two communicating
138parties may have different formats of their native data types (i.e.
139number of bits in the integer type), thus it is important to have
140a way to describe the data in a manner which is independent from the
141particular machine's representation. The ASN.1 specifications is used
142to achieve one or more of the following:
143
144<P>
145
146<UL>
147<LI>The specification expressed in the ASN.1 notation is a formal and
148precise way to communicate the data semantics to human readers;
149</LI>
150<LI>The ASN.1 specifications may be used as input for automatic compilers
151which produce the code for some target language (C, C++, Java, etc)
152to encode and decode the data according to some encoding rules (which
153are also defined by the ASN.1 standard).
154</LI>
155</UL>
156Consider the following example:
157
158<P>
159
160<DD><PRE>
161
162Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
163&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,
164&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER
165}
166
167</PRE>
168</DD>
169This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
170containing two integer fields. This specification may tell the reader
171that there is this kind of data structure and that some entity may
172be prepared to send or receive it. The question on <I>how</I> that
173entity is going to send or receive the <I>encoded data</I> is outside
174the scope of ASN.1. For example, this data structure may be encoded
175according to some encoding rules and sent to the destination using
176the TCP protocol. The ASN.1 specifies several ways of encoding (or
177''serializing'', or ''marshaling'') the data: BER, CER, DER and
178XER, some of them which will be described later.
179
180<P>
181The complete specification must be wrapped in a module, which looks
182like this:
183
184<P>
185
186<DD><PRE>
187
188UsageExampleModule1
189&nbsp;&nbsp;&nbsp;&nbsp;{&nbsp;iso&nbsp;org(3)&nbsp;dod(6)&nbsp;internet(1)&nbsp;private(4)
190&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;enterprise(1)&nbsp;spelio(9363)&nbsp;software(1)
191&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1c(5)&nbsp;docs(2)&nbsp;usage(1)&nbsp;1&nbsp;}&nbsp;
192&nbsp;&nbsp;&nbsp;&nbsp;AUTOMATIC&nbsp;TAGS&nbsp;DEFINITIONS&nbsp;::=
193BEGIN
194&nbsp;
195--&nbsp;This&nbsp;is&nbsp;a&nbsp;comment&nbsp;which&nbsp;describes&nbsp;nothing.
196Rectangle&nbsp;::=&nbsp;SEQUENCE&nbsp;{
197&nbsp;&nbsp;&nbsp;&nbsp;height&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Height&nbsp;of&nbsp;the&nbsp;rectangle
198&nbsp;&nbsp;&nbsp;&nbsp;width&nbsp;&nbsp;&nbsp;INTEGER,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;Width&nbsp;of&nbsp;the&nbsp;rectangle
199}
200&nbsp;
201END
202
203</PRE>
204</DD>
205The module header consists of module name (UsageExampleModule1), the
206module object identifier ({...}), some flags (AUTOMATIC TAGS) and
207''DEFINITIONS ::= BEGIN''. The module ends with an ''END'' statement.
208
209<P>
210
211<H1><A NAME="SECTION02110000000000000000">
212Some of the ASN.1 Basic Types</A>
213</H1>
214
215<P>
216
217<H2><A NAME="SECTION02111000000000000000">
218The BOOLEAN type</A>
219</H2>
220
221<P>
222The BOOLEAN type models the simple binary TRUE/FALSE, YES/NO, ON/OFF
223or a similar kind of two-way choice.
224
225<P>
226
227<H2><A NAME="SECTION02112000000000000000">
228The INTEGER type</A>
229</H2>
230
231<P>
232The INTEGER type is a signed natural number type without any restrictions
233on its size. If the automatic checking on INTEGER value bounds are
234necessary, the subtype constraints must be used.
235
236<P>
237
238<DD><PRE>
239
240SimpleInteger&nbsp;::=&nbsp;INTEGER
241--&nbsp;An&nbsp;integer&nbsp;with&nbsp;a&nbsp;very&nbsp;limited&nbsp;range
242SmallInt&nbsp;::=&nbsp;INTEGER&nbsp;(0..127)
243--&nbsp;Integer,&nbsp;negative
244NegativeInt&nbsp;::=&nbsp;INTEGER&nbsp;(MIN..0)
245
246</PRE>
247</DD>
248
249<P>
250
251<H2><A NAME="SECTION02113000000000000000">
252The ENUMERATED type</A>
253</H2>
254
255<P>
256The ENUMERATED type is semantically equivalent to the INTEGER type
257with some integer values explicitly named.
258
259<P>
260
261<DD><PRE>
262
263FruitId&nbsp;::=&nbsp;ENUMERATED&nbsp;{&nbsp;apple(1),&nbsp;orange(2)&nbsp;}
264--&nbsp;The&nbsp;numbers&nbsp;in&nbsp;braces&nbsp;are&nbsp;optional,
265--&nbsp;the&nbsp;enumeration&nbsp;may&nbsp;be&nbsp;performed
266--&nbsp;automatically&nbsp;by&nbsp;the&nbsp;compiler
267ComputerOSType&nbsp;::=&nbsp;ENUMERATED&nbsp;{
268&nbsp;&nbsp;&nbsp;&nbsp;FreeBSD,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;0
269&nbsp;&nbsp;&nbsp;&nbsp;Windows,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;1
270&nbsp;&nbsp;&nbsp;&nbsp;Solaris(5),&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;remain&nbsp;5
271&nbsp;&nbsp;&nbsp;&nbsp;Linux,&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;6
272&nbsp;&nbsp;&nbsp;&nbsp;MacOS&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;will&nbsp;be&nbsp;7
273}
274
275</PRE>
276</DD>
277
278<P>
279
280<H2><A NAME="SECTION02114000000000000000">
281The OCTET STRING type</A>
282</H2>
283
284<P>
285This type models the sequence of 8-bit bytes. This may be used to
286transmit some opaque data or data serialized by other types of encoders
287(i.e. video file, photo picture, etc).
288
289<P>
290
291<H2><A NAME="SECTION02115000000000000000">
292The OBJECT IDENTIFIER type</A>
293</H2>
294
295<P>
296The OBJECT IDENTIFIER is used to represent the unique identifier of
297any object, starting from the very root of the registration tree.
298If your organization needs to uniquely identify something (a router,
299a room, a person, a standard, or whatever), you are encouraged to
300get your own identification subtree at http://www.iana.org/protocols/forms.htm.
301
302<P>
303For example, the very first ASN.1 module in this document has the
304following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1.
305
306<P>
307
308<DD><PRE>
309
310ExampleOID&nbsp;::=&nbsp;OBJECT&nbsp;IDENTIFIER
311usageExampleModule1-oid&nbsp;ExampleOID
312&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;}
313--&nbsp;An&nbsp;identifier&nbsp;of&nbsp;the&nbsp;Internet.
314internet-id&nbsp;OBJECT&nbsp;IDENTIFIER
315&nbsp;&nbsp;::=&nbsp;{&nbsp;iso(1)&nbsp;identified-organization(3)
316&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dod(6)&nbsp;internet(1)&nbsp;}
317
318</PRE>
319</DD>
320As you see, names are optional.
321
322<P>
323
324<H2><A NAME="SECTION02116000000000000000">
325The RELATIVE-OID type</A>
326</H2>
327
328<P>
329The RELATIVE-OID type has the semantics of a subtree of an OBJECT
330IDENTIFIER. There may be no need to repeat the whole sequence of numbers
331from the root of the registration tree where the only thing of interest
332is some of the tree's subsequence.
333
334<P>
335
336<DD><PRE>
337
338this-document&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{&nbsp;docs(2)&nbsp;usage(1)&nbsp;}
339this-example&nbsp;RELATIVE-OID&nbsp;::=&nbsp;{
340&nbsp;&nbsp;&nbsp;&nbsp;this-document&nbsp;assorted-examples(0)&nbsp;this-example(1)&nbsp;}
341
342</PRE>
343</DD>
344
345<P>
346
347<H1><A NAME="SECTION02120000000000000000">
348Some of the ASN.1 String Types</A>
349</H1>
350
351<P>
352
353<H2><A NAME="SECTION02121000000000000000">
354The IA5String type</A>
355</H2>
356
357<P>
358This is essentially the ASCII, with 128 character codes available
359(7 lower bits of 8-bit byte).
360
361<P>
362
363<H2><A NAME="SECTION02122000000000000000">
364The UTF8String type</A>
365</H2>
366
367<P>
368This is the character string which encodes the full Unicode range
369(4 bytes) using multibyte character sequences.
370
371<P>
372
373<H2><A NAME="SECTION02123000000000000000">
374The NumericString type</A>
375</H2>
376
377<P>
378This type represents the character string with the alphabet consisting
379of numbers (''0'' to ''9'') and a space.
380
381<P>
382
383<H2><A NAME="SECTION02124000000000000000">
384The PrintableString type</A>
385</H2>
386
387<P>
388The character string with the following alphabet: space, ''<B>'</B>''
389(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
390'','' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
391digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
392upper-case and lower-case letters (''A'' to ''Z'' and ''a''
393to ''z'')
394
395<P>
396
397<H2><A NAME="SECTION02125000000000000000">
398The VisibleString type</A>
399</H2>
400
401<P>
402The character string with the alphabet which is more or less a subset
403of ASCII between space and ''~'' (tilde). Alternatively,
404the alphabet may be represented as the PrintableString alphabet described
405earlier, plus the following characters: ''<B>!</B>'', ''<B>''</B>'',
406''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'', ''<B>&amp;</B>'',
407''<B>*</B>'', ''<B>;</B>'', ''<B>&lt;</B>'', ''<B>&gt;</B>'',
408''<B>[</B>'', ''<B>&#92;</B>'', ''<B>]</B>'',
409''<B>&#94;</B>'', ''<B>_</B>'', ''<B>`</B>''
410(single left quote), ''<B>{</B>'', ''<B>|</B>'', ''<B>}</B>'',
411''~''.
412
413<P>
414
415<H1><A NAME="SECTION02130000000000000000">
416ASN.1 Constructed Types</A>
417</H1>
418
419<P>
420
421<H2><A NAME="SECTION02131000000000000000">
422The SEQUENCE type</A>
423</H2>
424
425<P>
426This is an ordered collection of other simple or constructed types.
427The SEQUENCE constructed type resembles the C ''struct'' statement.
428
429<P>
430
431<DD><PRE>
432
433Address&nbsp;::=&nbsp;SEQUENCE&nbsp;{
434&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;The&nbsp;apartment&nbsp;number&nbsp;may&nbsp;be&nbsp;omitted
435&nbsp;&nbsp;&nbsp;&nbsp;apartmentNumber&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL,
436&nbsp;&nbsp;&nbsp;&nbsp;streetName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
437&nbsp;&nbsp;&nbsp;&nbsp;cityName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
438&nbsp;&nbsp;&nbsp;&nbsp;stateName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;PrintableString,
439&nbsp;&nbsp;&nbsp;&nbsp;--&nbsp;This&nbsp;one&nbsp;may&nbsp;be&nbsp;omitted&nbsp;too
440&nbsp;&nbsp;&nbsp;&nbsp;zipNo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NumericString&nbsp;OPTIONAL
441}
442
443</PRE>
444</DD>
445
446<P>
447
448<H2><A NAME="SECTION02132000000000000000">
449The SET type</A>
450</H2>
451
452<P>
453This is a collection of other simple or constructed types. Ordering
454is not important. The data may arrive in the order which is different
455from the order of specification. Data is encoded in the order not
456necessarily corresponding to the order of specification.
457
458<P>
459
460<H2><A NAME="SECTION02133000000000000000">
461The CHOICE type</A>
462</H2>
463
464<P>
465This type is just a choice between the subtypes specified in it. The
466CHOICE type contains at most one of the subtypes specified, and it
467is always implicitly known which choice is being decoded or encoded.
468This one resembles the C ''union'' statement.
469
470<P>
471The following type defines a response code, which may be either an
472integer code or a boolean ''true''/''false'' code.
473
474<P>
475
476<DD><PRE>
477
478ResponseCode&nbsp;::=&nbsp;CHOICE&nbsp;{
479&nbsp;&nbsp;&nbsp;&nbsp;intCode&nbsp;&nbsp;&nbsp;&nbsp;INTEGER,
480&nbsp;&nbsp;&nbsp;&nbsp;boolCode&nbsp;&nbsp;&nbsp;BOOLEAN
481}
482
483</PRE>
484</DD>
485
486<P>
487
488<H2><A NAME="SECTION02134000000000000000">
489The SEQUENCE OF type</A>
490</H2>
491
492<P>
493This one is the list (array) of simple or constructed types:
494
495<P>
496
497<DD><PRE>
498
499--&nbsp;Example&nbsp;1
500ManyIntegers&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;INTEGER
501--&nbsp;Example&nbsp;2
502ManyRectangles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;Rectangle
503--&nbsp;More&nbsp;complex&nbsp;example:
504--&nbsp;an&nbsp;array&nbsp;of&nbsp;structures&nbsp;defined&nbsp;in&nbsp;place.
505ManyCircles&nbsp;::=&nbsp;SEQUENCE&nbsp;OF&nbsp;SEQUENCE&nbsp;{
506&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
507&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;}
508
509</PRE>
510</DD>
511
512<P>
513
514<H2><A NAME="SECTION02135000000000000000">
515The SET OF type</A>
516</H2>
517
518<P>
519The SET OF type models the bag of structures. It resembles the SEQUENCE
520OF type, but the order is not important: i.e. the elements may arrive
521in the order which is not necessarily the same as the in-memory order
522on the remote machines.
523
524<P>
525
526<DD><PRE>
527
528--&nbsp;A&nbsp;set&nbsp;of&nbsp;structures&nbsp;defined&nbsp;elsewhere
529SetOfApples&nbsp;::&nbsp;SET&nbsp;OF&nbsp;Apple
530--&nbsp;Set&nbsp;of&nbsp;integers&nbsp;encoding&nbsp;the&nbsp;kind&nbsp;of&nbsp;a&nbsp;fruit
531FruitBag&nbsp;::=&nbsp;SET&nbsp;OF&nbsp;ENUMERATED&nbsp;{&nbsp;apple,&nbsp;orange&nbsp;}
532
533</PRE>
534</DD>
535
536<P>
537
538<H1><A NAME="SECTION03000000000000000000">
539Using the ASN.1 Compiler</A>
540</H1>
541
542<P>
543
544<H1><A NAME="SECTION03100000000000000000">
545Introduction to the ASN.1 Compiler</A>
546</H1>
547
548<P>
549The purpose of the ASN.1 compiler, of which this document is part,
550is to convert the ASN.1 specifications to some other target language
551(currently, only C is supported<A NAME="tex2html1"
552 HREF="#foot136"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
553language structures and surrounding maintenance code. For example,
554the C structure which may be created by compiler to represent the
555simple <I>Rectangle</I> specification defined earlier in this document,
556may look like this<A NAME="tex2html2"
557 HREF="#foot315"><SUP>2.2</SUP></A>:
558
559<P>
560
561<DD><PRE>
562
563typedef&nbsp;struct&nbsp;Rectangle_s&nbsp;{
564&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;height;
565&nbsp;&nbsp;&nbsp;&nbsp;int&nbsp;width;
566}&nbsp;Rectangle_t;
567
568</PRE>
569</DD>
570This would not be of much value for such a simple specification, so
571the compiler goes further and actually produces the code which fills
572in this structure by parsing the binary<A NAME="tex2html3"
573 HREF="#foot142"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
574this structure as an argument and performs structure serialization
575by emitting a series of bytes.
576
577<P>
578
579<H1><A NAME="SECTION03110000000000000000">
580Quick start</A>
581</H1>
582
583<P>
584After building and installing the compiler, the asn1c command may
585be used to compile the ASN.1 specification<A NAME="tex2html4"
586 HREF="#foot316"><SUP>2.4</SUP></A>:
587
588<P>
589
590<DD><PRE>
591
592asn1c&nbsp;<I>&lt;spec.asn1&gt;</I>
593
594</PRE>
595</DD>
596If several specifications contain interdependencies, all of them must
597be specified:
598
599<P>
600
601<DD><PRE>
602
603asn1c&nbsp;<I>&lt;spec1.asn1&gt;&nbsp;&lt;spec2.asn1&gt;&nbsp;...</I>
604
605</PRE>
606</DD>
607The compiler -E and -EF options are used for testing the parser and
608the semantic fixer, respectively. These options will instruct the
609compiler to dump out the parsed (and fixed) ASN.1 specification as
610it was &#34;understood&#34; by the compiler. It might might
611be useful to check whether a particular syntactic construction is
612properly supported by the compiler.
613
614<P>
615
616<DD><PRE>
617
618asn1c&nbsp;-EF&nbsp;<I>&lt;spec-to-test.asn1&gt;</I>
619
620</PRE>
621</DD>
622The -P option is used to dump the compiled output on the screen instead
623of creating a bunch of .c and .h files on disk in the current directory.
624You would probably want to start with -P option instead of creating
625a mess in your current directory.
626
627<P>
628
629<H1><A NAME="SECTION03120000000000000000">
630Slow start</A>
631</H1>
632
633<P>
634
635<H2><A NAME="SECTION03121000000000000000">
636Recognizing compiler output</A>
637</H2>
638
639<P>
640After compiling, the following entities will be created in your current
641directory:
642
643<P>
644
645<UL>
646<LI>A set of .c and .h files, generally a single pair for each type defined
647in the ASN.1 specifications. These files will be named similarly to
648the ASN.1 types (<I>Rectangle.c</I> and <I>Rectangle.h</I> for the
649specification defined in the beginning of this document).
650</LI>
651<LI>A set of helper .c and .h files which contain generic encoders, decoders
652and other useful routines. There will be many of them, some of them
653even not necessary<A NAME="tex2html5"
654 HREF="#foot161"><SUP>2.5</SUP></A>, but the overall amount of code after compiling will be rather small
655anyway.
656</LI>
657</UL>
658It is your responsibility to create .c file with the <I>int main()</I>
659routine and the Makefile (if needed). Compiler helps you with the
660latter by creating the Makefile.am.sample, containing the skeleton
661definition for the automake, should you want to use autotools.
662
663<P>
664In other words, after compiling the Rectangle module, you have the
665following set of files: { Makefile.am.sample, Rectangle.c, Rectangle.h,
666<B>...</B> }, where <B>''...''</B> stands for the
667set of additional ''helper'' files created by the compiler. If you
668add the simple file with the <I>int main()</I> routine, it would even
669be possible to compile everything with the single instruction:
670
671<P>
672
673<DD><PRE>
674
675cc&nbsp;-o&nbsp;rectangle&nbsp;*.c&nbsp;&nbsp;&nbsp;#&nbsp;It&nbsp;could&nbsp;be&nbsp;<I>that</I>&nbsp;simple<A NAME="tex2html6"
676 HREF="#foot319"><SUP>2.6</SUP></A>
677
678</PRE>
679</DD>
680
681<P>
682
683<H2><A NAME="SECTION03122000000000000000">
684Invoking the ASN.1 helper code from the application</A>
685</H2>
686
687<P>
688First of all, you would want to include one or more header files into
689your application. For the Rectangle module, including the Rectangle.h
690file is enough:
691
692<P>
693
694<DD><PRE>
695
696#include&nbsp;&lt;Rectangle.h&gt;
697
698</PRE>
699</DD>
700The header files defines the C structure corresponding to the ASN.1
701definition of a rectangle and the declaration of the ASN.1 type descriptor,
702which is used as an argument to most of the functions provided by
703the ASN.1 module. For example, here is the code which frees the Rectangle_t
704structure:
705
706<P>
707
708<DD><PRE>
709
710Rectangle_t&nbsp;*rect&nbsp;=&nbsp;;
711asn1_DEF_Rectangle-&gt;free_struct(&amp;asn1_DEF_Rectangle,
712&nbsp;&nbsp;&nbsp;&nbsp;rect,&nbsp;0);
713
714</PRE>
715</DD>
716This code defines a <I>rect</I> pointer which points to the Rectangle_t
717structure which needs to be freed. The second line invokes the generic
718free_struct routine created specifically for this Rectangle_t structure.
719The <I>asn1_DEF_Rectangle</I> is the type descriptor, which holds
720a collection of generic routines to deal with the Rectangle_t structure.
721
722<P>
723There are several generic functions available:
724
725<P>
726<DL>
727<DT><STRONG>check_constraints</STRONG></DT>
728<DD>Check that the contents of the target structure
729are semantically valid and constrained to appropriate implicit or
730explicit subtype constraints. Please refer to Section sub:Validating-the-target.
731</DD>
732<DT><STRONG>ber_decoder</STRONG></DT>
733<DD>This is the generic <I>restartable</I><A NAME="tex2html7"
734 HREF="#foot183"><SUP>2.7</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
735and/or fill the target structure for you. Please refer to Section
736[<A HREF="#sub:Decoding-BER">Decoding-BER</A>].
737</DD>
738<DT><STRONG>der_encoder</STRONG></DT>
739<DD>This is the generic DER encoder (Distinguished Encoding
740Rules). This decoder will take the target structure and encode it
741into a series of bytes. Please refer to Section [<A HREF="#sub:Encoding-DER">Encoding-DER</A>].
742</DD>
743<DT><STRONG>print_struct</STRONG></DT>
744<DD>This function convert the contents of the passed target
745structure into human readable form. This form is not formal and cannot
746be converted back into the structure, but it may turn out to be useful
747for debugging or quick-n-dirty printing. Please refer to Section [<A HREF="#sub:Printing-the-target">Printing-the-target</A>].
748</DD>
749<DT><STRONG>free_struct</STRONG></DT>
750<DD>This is a generic disposal which frees the target structure.
751Please refer to Section [<A HREF="#sub:Freeing-the-target">Freeing-the-target</A>].
752</DD>
753</DL>
754Each of the above function takes the type descriptor (<I>asn1_DEF_...</I>)
755and the target structure (<I>rect</I>, in the above example). The
756target structure is typically created by the generic BER decoder or
757by the application itself.
758
759<P>
760Here is how the buffer can be deserialized into the structure:
761
762<P>
763
764<DD><PRE>
765
766Rectangle_t&nbsp;*
767simple_deserializer(void&nbsp;*buffer,&nbsp;size_t&nbsp;buf_size)&nbsp;{
768&nbsp;&nbsp;&nbsp;&nbsp;Rectangle_t&nbsp;*rect&nbsp;=&nbsp;0;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Note&nbsp;this&nbsp;0!&nbsp;*/
769&nbsp;&nbsp;&nbsp;&nbsp;ber_dec_rval_t&nbsp;rval;
770&nbsp;
771&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;asn1_DEF_Rectangle-&gt;ber_decoder(
772&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,
773&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(void&nbsp;**)&amp;rect,
774&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size,
775&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0);
776&nbsp;
777&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.code</B>&nbsp;==&nbsp;RC_OK)&nbsp;{
778&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;*/
779&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
780&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;asn1_DEF_Rectangle-&gt;free_struct(
781&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect,&nbsp;0);
782&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;0;
783&nbsp;&nbsp;&nbsp;&nbsp;}
784}
785
786</PRE>
787</DD>
788The code above defines a function, <I>simple_deserializer</I>, which
789takes a buffer and its length and expected to return a pointer to
790the Rectangle_t structure. Inside, it tries to convert the bytes
791passed into the target structure (rect) using the generic BER decoder
792and returns the rect pointer afterwards. If the structure cannot be
793deserialized, it frees the memory which might be left allocated by
794the unfinished <I>ber_decoder</I> routine and returns NULL. <B>This
795freeing is necessary</B> because the ber_decoder is a restartable procedure,
796and may fail just because there is more data needs to be provided
797before decoding could be finalized. The code above obviously does
798not take into account the way the <I>ber_decoder</I> failed, so the
799freeing is necessary because the part of the buffer may already be
800decoded into the structure by the time something goes wrong.
801
802<P>
803Restartable decoding is a little bit trickier: you need to provide
804the old target structure pointer (which might be already half-decoded)
805and react on RC_WMORE return code. This will be explained later in
806Section sub:Decoding-BER
807
808<P>
809
810<H3><A NAME="SECTION03122100000000000000"></A><A NAME="sub:Decoding-BER"></A><BR>
811Decoding BER
812</H3>
813
814<P>
815The Basic Encoding Rules describe the basic way how the structure
816can be encoded and decoded. Several other encoding rules (CER, DER)
817define a more restrictive versions of BER, so the generic BER parser
818is also capable of decoding the data encoded by CER and DER encoders.
819The opposite is not true.
820
821<P>
822The ASN.1 compiler provides the generic BER decoder which is implicitly
823capable of decoding BER, CER and DER encoded data.
824
825<P>
826The decoder is restartable (stream-oriented), which means that in
827case the buffer has less data than it is expected, the decoder will
828process whatever it is available and ask for more data to be provided.
829Please note that the decoder may actually process less data than it
830is given in the buffer, which means that you should be able to make
831the next buffer contain the unprocessed part of the previous buffer.
832
833<P>
834Suppose, you have two buffers of encoded data: 100 bytes and 200 bytes.
835
836<P>
837
838<UL>
839<LI>You may concatenate these buffers and feed the BER decoder with 300
840bytes of data, or
841</LI>
842<LI>You may feed it the first buffer of 100 bytes of data, realize that
843the ber_decoder consumed only 95 bytes from it and later feed the
844decoder with 205 bytes buffer which consists of 5 unprocessed bytes
845from the first buffer and the latter 200 bytes from the second buffer.
846</LI>
847</UL>
848This is not as convenient as it could be (like, the BER encoder would
849consume the whole 100 bytes and keep these 5 bytes in some temporary
850storage), but in case of stream-based processing it might actually
851be OK. Suggestions are welcome.
852
853<P>
854There are two ways to invoke a BER decoder. The first one is a direct
855reference of the type-specific decoder. This way was shown in the
856previous example of <I>simple_deserializer</I> function. The second
857way is to invoke a <I>ber_decode</I> function, which is just a simple
858wrapper of the former approach into a less wordy notation:
859
860<P>
861
862<DD><PRE>
863
864rval&nbsp;=&nbsp;ber_decode(&amp;asn1_DEF_Rectangle,&nbsp;(void&nbsp;**)&amp;rect,
865&nbsp;&nbsp;&nbsp;&nbsp;buffer,&nbsp;buf_size);
866
867</PRE>
868</DD>
869Note that the initial (asn1_DEF_Rectangle-&gt;ber_decoder) reference
870is gone, and also the last argument (0) is no longer necessary.
871
872<P>
873These two ways of invocations are fully equivalent.
874
875<P>
876The BER de<I>coder</I> may fail because (<I>the following RC_...
877codes are defined in ber_decoder.h</I>):
878
879<P>
880
881<UL>
882<LI>RC_WMORE: There is more data expected than it is provided (stream
883mode continuation feature);
884</LI>
885<LI>RC_FAIL: General failure to decode the buffer;
886</LI>
887<LI>... other codes may be defined as well.
888</LI>
889</UL>
890Together with the return code (.code) the ber_dec_rval_t type contains
891the number of bytes which is consumed from the buffer. In the previous
892hypothetical example of two buffers (of 100 and 200 bytes), the first
893call to ber_decode() would return with .code = RC_WMORE and .consumed
894= 95. The .consumed field of the BER decoder return value is <B>always</B>
895valid, even if the decoder succeeds or fails with any other return
896code.
897
898<P>
899Please look into ber_decoder.h for the precise definition of ber_decode()
900and related types.
901
902<P>
903
904<H3><A NAME="SECTION03122200000000000000"></A><A NAME="sub:Encoding-DER"></A><BR>
905Encoding DER
906</H3>
907
908<P>
909The Distinguished Encoding Rules is the variant of BER encoding rules
910which is oriented on representing the structures with length known
911beforehand. This is probably exactly how you want to encode: either
912after a BER decoding or after a manual fill-up, the target structure
913contains the data which size is implicitly known before encoding.
914The DER encoding is used, for example, to encode X.509 certificates.
915
916<P>
917As with BER decoder, the DER encoder may be invoked either directly
918from the ASN.1 type descriptor (asn1_DEF_Rectangle) or from the
919stand-alone function, which is somewhat simpler:
920
921<P>
922
923<DD><PRE>
924
925/*
926&nbsp;*&nbsp;This&nbsp;is&nbsp;a&nbsp;custom&nbsp;function&nbsp;which&nbsp;writes&nbsp;the
927&nbsp;*&nbsp;encoded&nbsp;output&nbsp;into&nbsp;some&nbsp;FILE&nbsp;stream.
928&nbsp;*/
929int&nbsp;_write_stream(void&nbsp;*buffer,&nbsp;size_t&nbsp;size,&nbsp;void&nbsp;*app_key)&nbsp;{
930&nbsp;&nbsp;&nbsp;&nbsp;FILE&nbsp;*ostream&nbsp;=&nbsp;app_key;
931&nbsp;&nbsp;&nbsp;&nbsp;size_t&nbsp;wrote;
932&nbsp;
933&nbsp;&nbsp;&nbsp;&nbsp;wrote&nbsp;=&nbsp;fwrite(buffer,&nbsp;1,&nbsp;size,&nbsp;ostream);
934&nbsp;
935&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;(wrote&nbsp;==&nbsp;size)&nbsp;?&nbsp;0&nbsp;:&nbsp;-1;
936}
937&nbsp;
938/*
939&nbsp;*&nbsp;This&nbsp;is&nbsp;the&nbsp;serializer&nbsp;itself,
940&nbsp;*&nbsp;it&nbsp;supplies&nbsp;the&nbsp;DER&nbsp;encoder&nbsp;with&nbsp;the
941&nbsp;*&nbsp;pointer&nbsp;to&nbsp;the&nbsp;custom&nbsp;output&nbsp;function.
942&nbsp;*/
943ssize_t
944simple_serializer(FILE&nbsp;*ostream,&nbsp;Rectangle_t&nbsp;*rect)&nbsp;{
945&nbsp;&nbsp;&nbsp;&nbsp;der_enc_rval_t&nbsp;rval;&nbsp;&nbsp;/*&nbsp;Return&nbsp;value&nbsp;*/
946&nbsp;
947&nbsp;&nbsp;&nbsp;&nbsp;rval&nbsp;=&nbsp;der_encode(&amp;asn1_DEF_Rect,&nbsp;rect,
948&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_write_stream,&nbsp;ostream);
949&nbsp;&nbsp;&nbsp;&nbsp;if(rval<B>.encoded</B>&nbsp;==&nbsp;-1)&nbsp;{
950&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*
951&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;Failure&nbsp;to&nbsp;encode&nbsp;the&nbsp;rectangle&nbsp;data.
952&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/
953&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fprintf(stderr,&nbsp;''Cannot&nbsp;encode&nbsp;%s:&nbsp;%s&#92;n'',
954&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rval<B>.failed_type</B>-&gt;name,
955&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strerror(errno));
956&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;-1;
957&nbsp;&nbsp;&nbsp;&nbsp;}&nbsp;else&nbsp;{
958&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Return&nbsp;the&nbsp;number&nbsp;of&nbsp;bytes&nbsp;*/
959&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;rval.encoded;
960&nbsp;&nbsp;&nbsp;&nbsp;}
961}
962
963</PRE>
964</DD>
965As you see, the DER encoder does not write into some sort of buffer
966or something. It just invokes the custom function (possible, multiple
967times) which would save the data into appropriate storage. The optional
968argument <I>app_key</I> is opaque for the DER encoder code and just
969used by <I>_write_stream()</I> as the pointer to the appropriate
970output stream to be used.
971
972<P>
973If the custom write function is not given (passed as 0), then the
974DER encoder will essentially do the same thing (i.e., encode the data)
975but no callbacks will be invoked (so the data goes nowhere). It may
976prove useful to determine the size of the structure's encoding before
977actually doing the encoding<A NAME="tex2html8"
978 HREF="#foot253"><SUP>2.8</SUP></A>.
979
980<P>
981Please look into der_encoder.h for the precise definition of der_encode()
982and related types.
983
984<P>
985
986<H3><A NAME="SECTION03122300000000000000"></A><A NAME="sub:Validating-the-target"></A><BR>
987Validating the target structure
988</H3>
989
990<P>
991Sometimes the target structure needs to be validated. For example,
992if the structure was created by the application (as opposed to being
993decoded from some external source), some important information required
994by the ASN.1 specification might be missing. On the other hand, the
995successful decoding of the data from some external source does not
996necessarily mean that the data is fully valid either. It might well
997be the case that the specification describes some subtype constraints
998that were not taken into account during decoding, and it would actually
999be useful to perform the last check when the data is ready to be encoded
1000or when the data has just been decoded to ensure its validity according
1001to some stricter rules.
1002
1003<P>
1004The asn_check_constraints() function checks the type for various
1005implicit and explicit constraints. It is recommended to use asn_check_constraints()
1006function after each decoding and before each encoding.
1007
1008<P>
1009Please look into constraints.h for the precise definition of asn_check_constraints()
1010and related types.
1011
1012<P>
1013
1014<H3><A NAME="SECTION03122400000000000000"></A><A NAME="sub:Printing-the-target"></A><BR>
1015Printing the target structure
1016</H3>
1017
1018<P>
1019There are two ways to print the target structure: either invoke the
1020print_struct member of the ASN.1 type descriptor, or using the asn_fprint()
1021function, which is a simpler wrapper of the former:
1022
1023<P>
1024
1025<DD><PRE>
1026
1027asn_fprint(stdout,&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect);
1028
1029</PRE>
1030</DD>
1031Please look into constr_TYPE.h for the precise definition of asn_fprint()
1032and related types.
1033
1034<P>
1035
1036<H3><A NAME="SECTION03122500000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR>
1037Freeing the target structure
1038</H3>
1039
1040<P>
1041Freeing the structure is slightly more complex than it may seem to.
1042When the ASN.1 structure is freed, all the members of the structure
1043and their submembers etc etc are recursively freed too. But it might
1044not be feasible to free the structure itself. Consider the following
1045case:
1046
1047<P>
1048
1049<DD><PRE>
1050
1051struct&nbsp;my_figure&nbsp;{&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;custom&nbsp;structure&nbsp;*/
1052&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;*/
1053&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;The&nbsp;type&nbsp;is&nbsp;generated&nbsp;by&nbsp;the&nbsp;ASN.1&nbsp;compiler&nbsp;*/
1054&nbsp;&nbsp;&nbsp;&nbsp;<I>Rectangle_t&nbsp;rect;</I>
1055&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;other&nbsp;members&nbsp;of&nbsp;the&nbsp;structure&nbsp;*/
1056};
1057
1058</PRE>
1059</DD>
1060In this example, the application programmer defined a custom structure
1061with one ASN.1-derived member (rect). This member is not a reference
1062to the Rectangle_t, but an in-place inclusion of the Rectangle_t
1063structure. If the freeing is necessary, the usual procedure of freeing
1064everything must not be applied to the &amp;rect pointer itself, because
1065it does not point to the memory block directly allocated by memory
1066allocation routine, but instead lies within such a block allocated
1067for my_figure structure.
1068
1069<P>
1070To solve this problem, the free_struct routine has the additional
1071argument (besides the intuitive type descriptor and target structure
1072pointers), which is the flag specifying whether the outer pointer
1073itself must be freed (0, default) or it should be left intact (non-zero
1074value).
1075
1076<P>
1077
1078<DD><PRE>
1079
1080/*&nbsp;Rectangle_t&nbsp;is&nbsp;defined&nbsp;within&nbsp;my_figure&nbsp;*/
1081struct&nbsp;my_figure&nbsp;*mf&nbsp;=&nbsp;<B>...</B>;
1082/*
1083&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_td
1084&nbsp;*&nbsp;without&nbsp;freeing&nbsp;the&nbsp;mf-&gt;rect&nbsp;pointer
1085&nbsp;*/
1086asn1_DEF_Rectangle-&gt;free_struct(
1087&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;&amp;mf-&gt;rect,&nbsp;<I>1</I>&nbsp;/*&nbsp;!free&nbsp;*/);
1088&nbsp;
1089/*&nbsp;Rectangle_t&nbsp;is&nbsp;a&nbsp;stand-alone&nbsp;pointer&nbsp;*/
1090Rectangle_t&nbsp;*rect&nbsp;=&nbsp;<B>...</B>;
1091/*
1092&nbsp;*&nbsp;Freeing&nbsp;the&nbsp;Rectangle_t
1093&nbsp;*&nbsp;and&nbsp;freeing&nbsp;the&nbsp;rect&nbsp;pointer
1094&nbsp;*/
1095asn1_DEF_Rectangle-&gt;free_struct(
1096&nbsp;&nbsp;&nbsp;&nbsp;&amp;asn1_DEF_Rectangle,&nbsp;rect,&nbsp;<I>0</I>&nbsp;/*&nbsp;free&nbsp;the&nbsp;pointer&nbsp;too&nbsp;*/);
1097
1098</PRE>
1099</DD>
1100It is safe to invoke the <I>free_struct</I> function with the target
1101structure pointer set to 0 (NULL), the function will do nothing.
1102
1103<P>
1104
1105<H2><A NAME="SECTION04000000000000000000">
1106Bibliography</A>
1107</H2><DL COMPACT><DD><P></P><DT><A NAME="Dub00">Dub00</A>
1108<DD>Olivier Dubuisson - <I>ASN.1 Communication between heterogeneous
1109systems</I> - Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
1110ISBN:0-12-6333361-0.
1111<P></P><DT><A NAME="ITU-T_ASN.1">ITU-T/ASN.1</A>
1112<DD>ITU-T Study Group 17 - Languages for Telecommunication Systems http://www.itu.int/ITU-T/studygroups/com17/languages/</DL>
1113
1114<P>
1115<BR><HR><H4>Footnotes</H4>
1116<DL>
1117<DT><A NAME="foot136">... supported</A><A
1118 HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT>
1119<DD>C++ is ''supported'' too, as long as an object-oriented approach
1120is not a definitive factor.
1121
1122</DD>
1123<DT><A NAME="foot315">... this</A><A
1124 HREF="asn1c-usage.html#tex2html2"><SUP>2.2</SUP></A></DT>
1125<DD><I>-fnative-integers</I> compiler option is used to produce basic
1126C <I>int</I> types instead of generic INTEGER_t.
1127
1128</DD>
1129<DT><A NAME="foot142">... binary</A><A
1130 HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT>
1131<DD>BER, CER and DER encodings are binary. However, the XER encoding is
1132text (XML) based.
1133
1134</DD>
1135<DT><A NAME="foot316">... specification</A><A
1136 HREF="asn1c-usage.html#tex2html4"><SUP>2.4</SUP></A></DT>
1137<DD>This is probably <B>not</B> what you want to try out right now -
1138read through the rest of this chapter to find out about -P option.
1139
1140</DD>
1141<DT><A NAME="foot161">... necessary</A><A
1142 HREF="asn1c-usage.html#tex2html5"><SUP>2.5</SUP></A></DT>
1143<DD>Soon the compiler will be modified to emit the smallest subset of
1144necessary files.
1145
1146</DD>
1147<DT><A NAME="foot319">...that&nbsp;simple</A><A
1148 HREF="asn1c-usage.html#tex2html6"><SUP>2.6</SUP></A></DT>
1149<DD>Provided that you've also created a .c file with the <I>int main()</I>
1150routine.
1151
1152</DD>
1153<DT><A NAME="foot183">...restartable</A><A
1154 HREF="asn1c-usage.html#tex2html7"><SUP>2.7</SUP></A></DT>
1155<DD>Restartable means that if the decoder encounters the end of the buffer,
1156it will fail, but may later be invoked again with the rest of the
1157buffer to continue decoding.
1158
1159</DD>
1160<DT><A NAME="foot253">... encoding</A><A
1161 HREF="asn1c-usage.html#tex2html8"><SUP>2.8</SUP></A></DT>
1162<DD>It is actually faster too: the encoder might skip over some computations
1163which aren't important for the size determination.
1164
1165</DD>
1166</DL><BR><HR>
1167<ADDRESS>
1168Lev Walkin
11692004-08-06
1170</ADDRESS>
1171</BODY>
1172</HTML>