diff options
| author | Lev Walkin <vlm@lionet.info> | 2005-01-31 10:18:53 +0000 |
|---|---|---|
| committer | Lev Walkin <vlm@lionet.info> | 2005-01-31 10:18:53 +0000 |
| commit | e94e3e511a6806e4c31a1b24de72d7844176f5be (patch) | |
| tree | 0a3a876addf243899a2ef36bec9e5626f7d4f902 | |
| parent | fecbd1e91ccc14b900854c49776db812943a2f74 (diff) | |
converted from tex
| -rw-r--r-- | doc/asn1c-usage.html | 274 |
1 files changed, 210 insertions, 64 deletions
diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html index 3195b2ad..36250bb9 100644 --- a/doc/asn1c-usage.html +++ b/doc/asn1c-usage.html @@ -41,93 +41,103 @@ Contents</A> <!--Table of Contents--> <UL> -<LI><A NAME="tex2html48" +<LI><A NAME="tex2html50" HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A> <UL> -<LI><A NAME="tex2html49" +<LI><A NAME="tex2html51" HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A> <UL> -<LI><A NAME="tex2html50" +<LI><A NAME="tex2html52" HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A> <UL> -<LI><A NAME="tex2html51" +<LI><A NAME="tex2html53" HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A> -<LI><A NAME="tex2html52" +<LI><A NAME="tex2html54" HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A> -<LI><A NAME="tex2html53" +<LI><A NAME="tex2html55" HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A> -<LI><A NAME="tex2html54" +<LI><A NAME="tex2html56" HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A> -<LI><A NAME="tex2html55" +<LI><A NAME="tex2html57" HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A> -<LI><A NAME="tex2html56" +<LI><A NAME="tex2html58" HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A> </UL> -<LI><A NAME="tex2html57" +<LI><A NAME="tex2html59" HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A> <UL> -<LI><A NAME="tex2html58" +<LI><A NAME="tex2html60" HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A> -<LI><A NAME="tex2html59" +<LI><A NAME="tex2html61" HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A> -<LI><A NAME="tex2html60" +<LI><A NAME="tex2html62" HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A> -<LI><A NAME="tex2html61" +<LI><A NAME="tex2html63" HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A> -<LI><A NAME="tex2html62" +<LI><A NAME="tex2html64" HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A> </UL> -<LI><A NAME="tex2html63" +<LI><A NAME="tex2html65" HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A> <UL> -<LI><A NAME="tex2html64" +<LI><A NAME="tex2html66" HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A> -<LI><A NAME="tex2html65" +<LI><A NAME="tex2html67" HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A> -<LI><A NAME="tex2html66" +<LI><A NAME="tex2html68" HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A> -<LI><A NAME="tex2html67" +<LI><A NAME="tex2html69" HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A> -<LI><A NAME="tex2html68" +<LI><A NAME="tex2html70" HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A> </UL> </UL> </UL><BR> -<LI><A NAME="tex2html69" +<LI><A NAME="tex2html71" HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A> <UL> -<LI><A NAME="tex2html70" +<LI><A NAME="tex2html72" HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A> -<LI><A NAME="tex2html71" +<LI><A NAME="tex2html73" HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A> -<LI><A NAME="tex2html72" +<LI><A NAME="tex2html74" HREF="asn1c-usage.html#SECTION03300000000000000000">Using the ASN.1 Compiler</A> <UL> -<LI><A NAME="tex2html73" +<LI><A NAME="tex2html75" HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A> -<LI><A NAME="tex2html74" +<LI><A NAME="tex2html76" HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A> -<LI><A NAME="tex2html75" +<LI><A NAME="tex2html77" HREF="asn1c-usage.html#SECTION03330000000000000000">Invoking the ASN.1 helper code from an application</A> <UL> -<LI><A NAME="tex2html76" +<LI><A NAME="tex2html78" HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A> -<LI><A NAME="tex2html77" +<LI><A NAME="tex2html79" HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A> -<LI><A NAME="tex2html78" +<LI><A NAME="tex2html80" HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A> -<LI><A NAME="tex2html79" +<LI><A NAME="tex2html81" HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A> -<LI><A NAME="tex2html80" +<LI><A NAME="tex2html82" HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A> -<LI><A NAME="tex2html81" +<LI><A NAME="tex2html83" HREF="asn1c-usage.html#SECTION03336000000000000000">Freeing the target structure</A> </UL> </UL> </UL><BR> -<LI><A NAME="tex2html82" +<LI><A NAME="tex2html84" HREF="asn1c-usage.html#SECTION04000000000000000000">Examples</A> -<LI><A NAME="tex2html83" +<UL> +<LI><A NAME="tex2html85" + HREF="asn1c-usage.html#SECTION04100000000000000000">Step by step examples</A> +<UL> +<LI><A NAME="tex2html86" + HREF="asn1c-usage.html#SECTION04110000000000000000">A ''Rectangle'' Encoder</A> +<LI><A NAME="tex2html87" + HREF="asn1c-usage.html#SECTION04120000000000000000">A ''Rectangle'' Decoder</A> +</UL> +</UL><BR> +<LI><A NAME="tex2html88" HREF="asn1c-usage.html#SECTION05000000000000000000">Bibliography</A> </UL> <!--End of Table of Contents--> @@ -570,7 +580,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="#foot574"><SUP>2.2</SUP></A>: + HREF="#foot739"><SUP>2.2</SUP></A>: <P> @@ -596,8 +606,8 @@ Quick start</A> <P> After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4" - 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>: + HREF="#foot740"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5" + HREF="#foot741"><SUP>3.2</SUP></A>: <P> @@ -663,7 +673,7 @@ the compiler's behavior. <P> <BR><P></P> -<DIV ALIGN="CENTER"><A NAME="579"></A> +<DIV ALIGN="CENTER"><A NAME="744"></A> <TABLE> <CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG> The list of asn1c command line options</CAPTION> @@ -807,7 +817,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="#foot582"><SUP>4.1</SUP></A> + HREF="#foot747"><SUP>4.1</SUP></A> </PRE> </BLOCKQUOTE> @@ -1059,19 +1069,6 @@ function, which is somewhat simpler: <P> <BLOCKQUOTE><PRE> -/* - * This is a custom function which writes the - * encoded output into some FILE stream. - */ -static int -write_stream(const void *buffer, size_t size, void *app_key) { - FILE *ostream = app_key; - size_t wrote; - - wrote = fwrite(buffer, 1, size, ostream); - - return (wrote == size) ? 0 : -1; -} /* * This is the serializer itself, @@ -1112,7 +1109,7 @@ 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="tex2html9" - HREF="#foot329"><SUP>4.3</SUP></A>. + HREF="#foot322"><SUP>4.3</SUP></A>. <P> Please look into der_encoder.h for the precise definition of der_encode() @@ -1299,11 +1296,159 @@ Examples</A> <P> <H1><A NAME="SECTION04100000000000000000"> -Step-by-step: A ''Rectangle'' Decoder</A> +Step by step examples</A> +</H1> + +<P> + +<H1><A NAME="SECTION04110000000000000000"> +A ''Rectangle'' Encoder</A> +</H1> + +<P> +This chapter 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, ''w''); /* 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, stream);</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="SECTION04120000000000000000"> +A ''Rectangle'' Decoder</A> </H1> <P> -This chapter will help you to create a simple decoder of a simple +This chapter will help you to create a simple BER decoder of a simple ''Rectangle'' type used throughout this document. <P> @@ -1417,7 +1562,8 @@ it as it were a BER-encoded Rectangle type, and prints out the text </BLOCKQUOTE> </LI> -<LI>Voila! You have just created the Rectangle type decoder named <B>rdecode</B>! +<LI>Voila! You have just created the BER decoder of a Rectangle type, +named <B>rdecode</B>! </LI> </OL> <H2><A NAME="SECTION05000000000000000000"> @@ -1442,7 +1588,7 @@ ISBN:0-12-6333361-0. not a definitive factor. </DD> -<DT><A NAME="foot574">... this</A><A +<DT><A NAME="foot739">... 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>. @@ -1454,19 +1600,19 @@ types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table text (XML) based. </DD> -<DT><A NAME="foot575">...asn1c</A><A +<DT><A NAME="foot740">...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="foot576">... specification</A><A +<DT><A NAME="foot741">... 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="foot582">...that simple</A><A +<DT><A NAME="foot747">...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. @@ -1479,7 +1625,7 @@ it will fail, but may later be invoked again with the rest of the buffer to continue decoding. </DD> -<DT><A NAME="foot329">... encoding</A><A +<DT><A NAME="foot322">... encoding</A><A HREF="asn1c-usage.html#tex2html9"><SUP>4.3</SUP></A></DT> <DD>It is actually faster too: the encoder might skip over some computations which aren't important for the size determination. @@ -1488,7 +1634,7 @@ which aren't important for the size determination. </DL><BR><HR> <ADDRESS> Lev Walkin -2005-01-17 +2005-01-31 </ADDRESS> </BODY> </HTML> |