diff options
| author | Lev Walkin <vlm@lionet.info> | 2005-01-17 11:09:32 +0000 |
|---|---|---|
| committer | Lev Walkin <vlm@lionet.info> | 2005-01-17 11:09:32 +0000 |
| commit | 028a28bf5fbf247292b9590e496ff44161eaa2fa (patch) | |
| tree | b39ca7da79c22824dfb648187efe3d118f660d6f /doc | |
| parent | fc67f3e017e55c4c48507501650020945a342e39 (diff) | |
regenerated
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/asn1c-usage.html | 262 |
1 files changed, 197 insertions, 65 deletions
diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html index fd0fa926..3195b2ad 100644 --- a/doc/asn1c-usage.html +++ b/doc/asn1c-usage.html @@ -41,92 +41,94 @@ Contents</A> <!--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" +<LI><A NAME="tex2html51" HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A> -<LI><A NAME="tex2html50" +<LI><A NAME="tex2html52" HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A> -<LI><A NAME="tex2html51" +<LI><A NAME="tex2html53" HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A> -<LI><A NAME="tex2html52" +<LI><A NAME="tex2html54" HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A> -<LI><A NAME="tex2html53" +<LI><A NAME="tex2html55" HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A> -<LI><A NAME="tex2html54" +<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" +<LI><A NAME="tex2html58" HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A> -<LI><A NAME="tex2html57" +<LI><A NAME="tex2html59" HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A> -<LI><A NAME="tex2html58" +<LI><A NAME="tex2html60" HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A> -<LI><A NAME="tex2html59" +<LI><A NAME="tex2html61" HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A> -<LI><A NAME="tex2html60" +<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" +<LI><A NAME="tex2html64" HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A> -<LI><A NAME="tex2html63" +<LI><A NAME="tex2html65" HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A> -<LI><A NAME="tex2html64" +<LI><A NAME="tex2html66" HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A> -<LI><A NAME="tex2html65" +<LI><A NAME="tex2html67" HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A> -<LI><A NAME="tex2html66" +<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" +<LI><A NAME="tex2html70" HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A> -<LI><A NAME="tex2html69" +<LI><A NAME="tex2html71" HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A> -<LI><A NAME="tex2html70" +<LI><A NAME="tex2html72" HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A> <UL> -<LI><A NAME="tex2html71" +<LI><A NAME="tex2html73" HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A> -<LI><A NAME="tex2html72" +<LI><A NAME="tex2html74" HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A> -<LI><A NAME="tex2html73" +<LI><A NAME="tex2html75" HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from an application</A> <UL> -<LI><A NAME="tex2html74" +<LI><A NAME="tex2html76" HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A> -<LI><A NAME="tex2html75" +<LI><A NAME="tex2html77" HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A> -<LI><A NAME="tex2html76" +<LI><A NAME="tex2html78" HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A> -<LI><A NAME="tex2html77" +<LI><A NAME="tex2html79" HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A> -<LI><A NAME="tex2html78" +<LI><A NAME="tex2html80" HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A> -<LI><A NAME="tex2html79" +<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 @@ 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 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 @@ Rectangle ::= SEQUENCE { </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 @@ like this: <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 @@ Rectangle ::= SEQUENCE { 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 @@ following OBJECT IDENTIFIER: 1 3 6 1 4 1 9363 1 5 2 1 1. <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 @@ language structures and surrounding maintenance code. For example, 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 @@ Quick start</A> <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 @@ the compiler's behavior. <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 @@ ting the usual support code.</FONT></TD></TR> <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 @@ be possible to compile everything with the single instruction: <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 @@ 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> - -<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 @@ ISBN:0-12-6333361-0. 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 @@ types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table 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 @@ which aren't important for the size determination. </DL><BR><HR> <ADDRESS> Lev Walkin -2004-09-30 +2005-01-17 </ADDRESS> </BODY> </HTML> |