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