regenerated
diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html
index fd0fa92..3195b2a 100644
--- a/doc/asn1c-usage.html
+++ b/doc/asn1c-usage.html
@@ -41,92 +41,94 @@
<!--Table of Contents-->
<UL>
-<LI><A NAME="tex2html46"
+<LI><A NAME="tex2html48"
HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A>
<UL>
-<LI><A NAME="tex2html47"
+<LI><A NAME="tex2html49"
HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A>
<UL>
-<LI><A NAME="tex2html48"
+<LI><A NAME="tex2html50"
HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A>
<UL>
-<LI><A NAME="tex2html49"
- HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
-<LI><A NAME="tex2html50"
- HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
<LI><A NAME="tex2html51"
- HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
+ HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A>
<LI><A NAME="tex2html52"
- HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
+ HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A>
<LI><A NAME="tex2html53"
- HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
+ HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A>
<LI><A NAME="tex2html54"
+ HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A>
+<LI><A NAME="tex2html55"
+ HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A>
+<LI><A NAME="tex2html56"
HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A>
</UL>
-<LI><A NAME="tex2html55"
+<LI><A NAME="tex2html57"
HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A>
<UL>
-<LI><A NAME="tex2html56"
- HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
-<LI><A NAME="tex2html57"
- HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
<LI><A NAME="tex2html58"
- HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
+ HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A>
<LI><A NAME="tex2html59"
- HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
+ HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A>
<LI><A NAME="tex2html60"
+ HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A>
+<LI><A NAME="tex2html61"
+ HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A>
+<LI><A NAME="tex2html62"
HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A>
</UL>
-<LI><A NAME="tex2html61"
+<LI><A NAME="tex2html63"
HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A>
<UL>
-<LI><A NAME="tex2html62"
- HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
-<LI><A NAME="tex2html63"
- HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
<LI><A NAME="tex2html64"
- HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
+ HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A>
<LI><A NAME="tex2html65"
- HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
+ HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A>
<LI><A NAME="tex2html66"
+ HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A>
+<LI><A NAME="tex2html67"
+ HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A>
+<LI><A NAME="tex2html68"
HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A>
</UL>
</UL>
</UL><BR>
-<LI><A NAME="tex2html67"
+<LI><A NAME="tex2html69"
HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A>
<UL>
-<LI><A NAME="tex2html68"
- HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
-<LI><A NAME="tex2html69"
- HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A>
<LI><A NAME="tex2html70"
+ HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A>
+<LI><A NAME="tex2html71"
+ HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A>
+<LI><A NAME="tex2html72"
HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A>
<UL>
-<LI><A NAME="tex2html71"
- HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A>
-<LI><A NAME="tex2html72"
- HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A>
<LI><A NAME="tex2html73"
+ HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A>
+<LI><A NAME="tex2html74"
+ HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A>
+<LI><A NAME="tex2html75"
HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from an application</A>
<UL>
-<LI><A NAME="tex2html74"
- HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A>
-<LI><A NAME="tex2html75"
- HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A>
<LI><A NAME="tex2html76"
- HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A>
+ HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A>
<LI><A NAME="tex2html77"
- HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A>
+ HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A>
<LI><A NAME="tex2html78"
- HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A>
+ HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A>
<LI><A NAME="tex2html79"
+ HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A>
+<LI><A NAME="tex2html80"
+ HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A>
+<LI><A NAME="tex2html81"
HREF="asn1c-usage.html#SECTION03336000000000000000">Freeing the target structure</A>
</UL>
</UL>
</UL><BR>
-<LI><A NAME="tex2html80"
- HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A>
+<LI><A NAME="tex2html82"
+ HREF="asn1c-usage.html#SECTION04000000000000000000">Examples</A>
+<LI><A NAME="tex2html83"
+ HREF="asn1c-usage.html#SECTION05000000000000000000">Bibliography</A>
</UL>
<!--End of Table of Contents-->
@@ -159,8 +161,8 @@
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 is used
-to achieve one or more of the following:
+particular machine's representation. The ASN.1 specifications are
+used to achieve the following:
<P>
@@ -187,14 +189,14 @@
</BLOCKQUOTE>
This ASN.1 specification describes a constructed type, <I>Rectangle</I>,
containing two integer fields. This specification may tell the reader
-that there is 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, CER, DER and
-XER, some of them which will be described later.
+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, CER, DER
+and XER, some of them which will be outlined later.
<P>
The complete specification must be wrapped in a module, which looks
@@ -203,10 +205,10 @@
<P>
<BLOCKQUOTE><PRE>
-UsageExampleModule1
+RectangleModule1
{ iso org(3) dod(6) internet(1) private(4)
enterprise(1) spelio(9363) software(1)
- asn1c(5) docs(2) usage(1) 1 }
+ asn1c(5) docs(2) rectangle(1) 1 }
DEFINITIONS AUTOMATIC TAGS ::=
BEGIN
@@ -219,7 +221,7 @@
END
</PRE>
</BLOCKQUOTE>
-The module header consists of module name (UsageExampleModule1), the
+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.
@@ -325,7 +327,7 @@
<BLOCKQUOTE><PRE>
ExampleOID ::= OBJECT IDENTIFIER
-usageExampleModule1-oid ExampleOID
+rectangleModule1-oid ExampleOID
::= { 1 3 6 1 4 1 9363 1 5 2 1 1 }
-- An identifier of the Internet.
@@ -568,7 +570,7 @@
the C structure which may be created by compiler to represent the
simple <I>Rectangle</I> specification defined earlier in this document,
may look like this<A NAME="tex2html2"
- HREF="#foot419"><SUP>2.2</SUP></A>:
+ HREF="#foot574"><SUP>2.2</SUP></A>:
<P>
@@ -594,8 +596,8 @@
<P>
After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
- HREF="#foot420"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
- HREF="#foot421"><SUP>3.2</SUP></A>:
+ HREF="#foot575"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
+ HREF="#foot576"><SUP>3.2</SUP></A>:
<P>
@@ -661,7 +663,7 @@
<P>
<BR><P></P>
-<DIV ALIGN="CENTER"><A NAME="424"></A>
+<DIV ALIGN="CENTER"><A NAME="579"></A>
<TABLE>
<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
The list of asn1c command line options</CAPTION>
@@ -693,7 +695,7 @@
<FONT SIZE="-1">Use the specified directory with ASN.1 skeleton files.</FONT></TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-X</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
-<FONT SIZE="-1">Generate the XML DTD schema for the specified ASN.1 modules.</FONT></TD></TR>
+Generate the XML DTD for the specified ASN.1 modules.</TD></TR>
</TBODY><TBODY>
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP><B>Warning Options</B></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
<B>Description</B></TD></TR>
@@ -805,7 +807,7 @@
<BLOCKQUOTE><PRE>
cc -o rectangle *.c # It could be <I>that</I> simple<A NAME="tex2html7"
- HREF="#foot427"><SUP>4.1</SUP></A>
+ HREF="#foot582"><SUP>4.1</SUP></A>
</PRE>
</BLOCKQUOTE>
@@ -1289,14 +1291,144 @@
structure pointer set to 0 (NULL), the function will do nothing.
<P>
-
-<H2><A NAME="SECTION04000000000000000000">
+
+<H1><A NAME="SECTION04000000000000000000">
+Examples</A>
+</H1>
+
+<P>
+
+<H1><A NAME="SECTION04100000000000000000">
+Step-by-step: A ''Rectangle'' Decoder</A>
+</H1>
+
+<P>
+This chapter will help you to create a simple 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 Rectangle type decoder named <B>rdecode</B>!
+</LI>
+</OL>
+<H2><A NAME="SECTION05000000000000000000">
Bibliography</A>
</H2><DL COMPACT><DD><P></P><DT><A NAME="ASN1C">ASN1C</A>
<DD>The OpenSource 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/>http://lionet.info/asn1c/</A>asn1c.cgi
<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>.
+<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>
@@ -1310,7 +1442,7 @@
not a definitive factor.
</DD>
-<DT><A NAME="foot419">... this</A><A
+<DT><A NAME="foot574">... this</A><A
HREF="asn1c-usage.html#tex2html2"><SUP>2.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>.
@@ -1322,19 +1454,19 @@
text (XML) based.
</DD>
-<DT><A NAME="foot420">...asn1c</A><A
+<DT><A NAME="foot575">...asn1c</A><A
HREF="asn1c-usage.html#tex2html4"><SUP>3.1</SUP></A></DT>
<DD>The 1 symbol in asn<B>1</B>c is a digit, not an ''ell'' letter.
</DD>
-<DT><A NAME="foot421">... specification</A><A
+<DT><A NAME="foot576">... specification</A><A
HREF="asn1c-usage.html#tex2html5"><SUP>3.2</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 to find out about <B>-P</B>
and <B>-R</B> options.
</DD>
-<DT><A NAME="foot427">...that simple</A><A
+<DT><A NAME="foot582">...that simple</A><A
HREF="asn1c-usage.html#tex2html7"><SUP>4.1</SUP></A></DT>
<DD>Provided that you've also created a .c file with the <I>int main()</I>
routine.
@@ -1356,7 +1488,7 @@
</DL><BR><HR>
<ADDRESS>
Lev Walkin
-2004-09-30
+2005-01-17
</ADDRESS>
</BODY>
</HTML>