diff options
| author | Lev Walkin <vlm@lionet.info> | 2004-09-26 13:41:45 +0000 |
|---|---|---|
| committer | Lev Walkin <vlm@lionet.info> | 2004-09-26 13:41:45 +0000 |
| commit | 683f9b7f27db9800dcfe6f32fc70038a72ac41a8 (patch) | |
| tree | 10d309a7a04f6fdb64fd4e451ed57dc435d0d105 | |
| parent | 78a463a639931d9bbe9dfdfecfb0ec569f56b4b5 (diff) | |
html version recompiled from the source
| -rw-r--r-- | doc/asn1c-usage.html | 224 |
1 files changed, 149 insertions, 75 deletions
diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html index 523435ed..9ac7b1ba 100644 --- a/doc/asn1c-usage.html +++ b/doc/asn1c-usage.html @@ -25,6 +25,9 @@ original version by: Nikos Drakos, CBLU, University of Leeds <P ALIGN="CENTER"><STRONG>Lev Walkin <vlm@lionet.info></STRONG></P> </DIV> +<!-- MATH + $Revision$ + --> <P> <BR> @@ -35,89 +38,91 @@ Contents</A> <!--Table of Contents--> <UL> -<LI><A NAME="tex2html45" +<LI><A NAME="tex2html46" HREF="asn1c-usage.html#SECTION02000000000000000000">ASN.1 Basics</A> <UL> -<LI><A NAME="tex2html46" +<LI><A NAME="tex2html47" HREF="asn1c-usage.html#SECTION02100000000000000000">Abstract Syntax Notation: ASN.1</A> <UL> -<LI><A NAME="tex2html47" +<LI><A NAME="tex2html48" HREF="asn1c-usage.html#SECTION02110000000000000000">Some of the ASN.1 Basic Types</A> <UL> -<LI><A NAME="tex2html48" - HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A> <LI><A NAME="tex2html49" - HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A> + HREF="asn1c-usage.html#SECTION02111000000000000000">The BOOLEAN type</A> <LI><A NAME="tex2html50" - HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A> + HREF="asn1c-usage.html#SECTION02112000000000000000">The INTEGER type</A> <LI><A NAME="tex2html51" - HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A> + HREF="asn1c-usage.html#SECTION02113000000000000000">The ENUMERATED type</A> <LI><A NAME="tex2html52" - HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A> + HREF="asn1c-usage.html#SECTION02114000000000000000">The OCTET STRING type</A> <LI><A NAME="tex2html53" + HREF="asn1c-usage.html#SECTION02115000000000000000">The OBJECT IDENTIFIER type</A> +<LI><A NAME="tex2html54" HREF="asn1c-usage.html#SECTION02116000000000000000">The RELATIVE-OID type</A> </UL> -<LI><A NAME="tex2html54" +<LI><A NAME="tex2html55" HREF="asn1c-usage.html#SECTION02120000000000000000">Some of the ASN.1 String Types</A> <UL> -<LI><A NAME="tex2html55" - HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A> <LI><A NAME="tex2html56" - HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A> + HREF="asn1c-usage.html#SECTION02121000000000000000">The IA5String type</A> <LI><A NAME="tex2html57" - HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A> + HREF="asn1c-usage.html#SECTION02122000000000000000">The UTF8String type</A> <LI><A NAME="tex2html58" - HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A> + HREF="asn1c-usage.html#SECTION02123000000000000000">The NumericString type</A> <LI><A NAME="tex2html59" + HREF="asn1c-usage.html#SECTION02124000000000000000">The PrintableString type</A> +<LI><A NAME="tex2html60" HREF="asn1c-usage.html#SECTION02125000000000000000">The VisibleString type</A> </UL> -<LI><A NAME="tex2html60" +<LI><A NAME="tex2html61" HREF="asn1c-usage.html#SECTION02130000000000000000">ASN.1 Constructed Types</A> <UL> -<LI><A NAME="tex2html61" - HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A> <LI><A NAME="tex2html62" - HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A> + HREF="asn1c-usage.html#SECTION02131000000000000000">The SEQUENCE type</A> <LI><A NAME="tex2html63" - HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A> + HREF="asn1c-usage.html#SECTION02132000000000000000">The SET type</A> <LI><A NAME="tex2html64" - HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A> + HREF="asn1c-usage.html#SECTION02133000000000000000">The CHOICE type</A> <LI><A NAME="tex2html65" + HREF="asn1c-usage.html#SECTION02134000000000000000">The SEQUENCE OF type</A> +<LI><A NAME="tex2html66" HREF="asn1c-usage.html#SECTION02135000000000000000">The SET OF type</A> </UL> </UL> </UL><BR> -<LI><A NAME="tex2html66" +<LI><A NAME="tex2html67" HREF="asn1c-usage.html#SECTION03000000000000000000">Using the ASN.1 Compiler</A> <UL> -<LI><A NAME="tex2html67" - HREF="asn1c-usage.html#SECTION03100000000000000000">Introduction to the ASN.1 Compiler</A> <LI><A NAME="tex2html68" - HREF="asn1c-usage.html#SECTION03200000000000000000">Quick start</A> + 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#SECTION03300000000000000000">Using the ASN.1 Compiler</A> <UL> -<LI><A NAME="tex2html70" - HREF="asn1c-usage.html#SECTION03310000000000000000">Command-line options</A> <LI><A NAME="tex2html71" - HREF="asn1c-usage.html#SECTION03320000000000000000">Recognizing compiler output</A> + 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#SECTION03330000000000000000">Invoking the ASN.1 helper code from the application</A> <UL> -<LI><A NAME="tex2html73" - HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A> <LI><A NAME="tex2html74" - HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A> + HREF="asn1c-usage.html#SECTION03331000000000000000">Decoding BER</A> <LI><A NAME="tex2html75" - HREF="asn1c-usage.html#SECTION03333000000000000000">Validating the target structure</A> + HREF="asn1c-usage.html#SECTION03332000000000000000">Encoding DER</A> <LI><A NAME="tex2html76" - HREF="asn1c-usage.html#SECTION03334000000000000000">Printing the target structure</A> + HREF="asn1c-usage.html#SECTION03333000000000000000">Encoding XER</A> <LI><A NAME="tex2html77" - HREF="asn1c-usage.html#SECTION03335000000000000000">Freeing the target structure</A> + HREF="asn1c-usage.html#SECTION03334000000000000000">Validating the target structure</A> +<LI><A NAME="tex2html78" + HREF="asn1c-usage.html#SECTION03335000000000000000">Printing the target structure</A> +<LI><A NAME="tex2html79" + HREF="asn1c-usage.html#SECTION03336000000000000000">Freeing the target structure</A> </UL> </UL> </UL><BR> -<LI><A NAME="tex2html78" +<LI><A NAME="tex2html80" HREF="asn1c-usage.html#SECTION04000000000000000000">Bibliography</A> </UL> <!--End of Table of Contents--> @@ -557,7 +562,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="#foot379"><SUP>2.2</SUP></A>: + HREF="#foot403"><SUP>2.2</SUP></A>: <P> @@ -583,8 +588,8 @@ Quick start</A> <P> After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4" - HREF="#foot380"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5" - HREF="#foot381"><SUP>3.2</SUP></A>: + HREF="#foot404"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5" + HREF="#foot405"><SUP>3.2</SUP></A>: <P> @@ -650,7 +655,7 @@ the compiler's behavior. <P> <BR><P></P> -<DIV ALIGN="CENTER"><A NAME="384"></A> +<DIV ALIGN="CENTER"><A NAME="408"></A> <TABLE> <CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG> The list of asn1c command line options</CAPTION> @@ -681,11 +686,6 @@ ting the usual support code.</FONT></TD></TR> <TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-S <I><directory></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>-t <I><data-string></I></TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216"> -<FONT SIZE="-1">Interpret the data-string as a sequence of hexadecimal values -representing the start of BER TLV encoding. Print the human readable -explanation.</FONT></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> </TBODY><TBODY> @@ -724,6 +724,10 @@ produce the meaningful code.</FONT></TD></TR> possible, instead of the compound ASN.1 INTEGER_t, ENUMERATED_t and REAL_t types. </FONT></TD></TR> </TBODY><TBODY> +<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fno-constraints</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216"> +Do not generate ASN.1 subtype constraint checking code. This may make +a shorter executable.</TD></TR> +</TBODY><TBODY> <TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-funnamed-unions</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> @@ -789,7 +793,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="#foot387"><SUP>4.1</SUP></A> + HREF="#foot411"><SUP>4.1</SUP></A> </PRE> </BLOCKQUOTE> @@ -836,22 +840,27 @@ There are several generic functions available: <P> <DL> -<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 sub:Validating-the-target. -</DD> <DT><STRONG>ber_decoder</STRONG></DT> <DD>This is the generic <I>restartable</I><A NAME="tex2html8" - HREF="#foot241"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create + HREF="#foot238"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create and/or fill the target structure for you. Please refer to Section [<A HREF="#sub:Decoding-BER">Decoding-BER</A>]. </DD> <DT><STRONG>der_encoder</STRONG></DT> <DD>This is the generic DER encoder (Distinguished Encoding -Rules). This decoder will take the target structure and encode it +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 generic XER encoder (XML Encoding Rules). +This encoder will take the target structure and represent it as an +XML (text) document. Please refer to Section [<A HREF="#sub:Encoding-XER">Encoding-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 sub:Validating-the-target. +</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 @@ -863,6 +872,11 @@ for debugging or quick-n-dirty printing. Please refer to Section [<A HREF="#sub: Please refer to Section [<A HREF="#sub:Freeing-the-target">Freeing-the-target</A>]. </DD> </DL> +check_constraints Check that the contents of the target structure +are semantically valid and constrained to appropriate implicit or +explicit subtype constraints. Please refer to Section sub:Validating-the-target. + +<P> Each of the above function takes the type descriptor (<I>asn1_DEF_...</I>) and the target structure (<I>rect</I>, in the above example). The target structure is typically created by the generic BER decoder or @@ -1015,12 +1029,13 @@ Encoding DER </H2> <P> -The Distinguished Encoding Rules is the variant of BER encoding rules -which is oriented on representing the structures with length 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. -The DER encoding is used, for example, to encode X.509 certificates. +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. The DER encoding is used, for example, to encode +X.509 certificates. <P> As with BER decoder, the DER encoder may be invoked either directly @@ -1051,21 +1066,21 @@ write_stream(const void *buffer, size_t size, void  */ ssize_t simple_serializer(FILE *ostream, Rectangle_t *rect) { - der_enc_rval_t rval; /* Return value */ + asn_enc_rval_t er; /* Encoder return value */ - rval = der_encode(&asn1_DEF_Rect, rect, + er = der_encode(&asn1_DEF_Rect, rect, write_stream, ostream); - if(rval<B>.encoded</B> == -1) { + if(er.<B>encoded</B> == -1) { /* - * Failure to encode the rectangle data. + * Failed to encode the rectangle data. */ fprintf(stderr, ''Cannot encode %s: %s\n'', - rval<B>.failed_type</B>->name, + er.<B>failed_type</B>->name, strerror(errno)); return -1; } else { /* Return the number of bytes */ - return rval.encoded; + return er.encoded; } } </PRE> @@ -1083,7 +1098,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="#foot313"><SUP>4.3</SUP></A>. + HREF="#foot314"><SUP>4.3</SUP></A>. <P> Please look into der_encoder.h for the precise definition of der_encode() @@ -1091,7 +1106,51 @@ and related types. <P> -<H2><A NAME="SECTION03333000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR> +<H2><A NAME="SECTION03333000000000000000"></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 sub:Encoding-DER. 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 sub:Printing-the-target. + */ +int +print_as_XML(FILE *ostream, Rectangle_t *rect) { + asn_enc_rval_t er; /* Encoder return value */ + + er = xer_encode(&asn1_DEF_Rect, 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="SECTION03334000000000000000"></A><A NAME="sub:Validating-the-target"></A><BR> Validating the target structure </H2> @@ -1119,7 +1178,7 @@ and related types. <P> -<H2><A NAME="SECTION03334000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR> +<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Printing-the-target"></A><BR> Printing the target structure </H2> @@ -1138,8 +1197,23 @@ 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, &asn1_DEF_Rectangle, rect); +</PRE> +</BLOCKQUOTE> +See Section sub:Encoding-XER for XML-related details. + +<P> -<H2><A NAME="SECTION03335000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR> +<H2><A NAME="SECTION03336000000000000000"></A><A NAME="sub:Freeing-the-target"></A><BR> Freeing the target structure </H2> @@ -1224,7 +1298,7 @@ ISBN:0-12-6333361-0. not a definitive factor. </DD> -<DT><A NAME="foot379">... this</A><A +<DT><A NAME="foot403">... 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>. @@ -1236,32 +1310,32 @@ types instead of infinite width INTEGER_t structures. See <A HREF=#Table1>Table text (XML) based. </DD> -<DT><A NAME="foot380">...asn1c</A><A +<DT><A NAME="foot404">...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="foot381">... specification</A><A +<DT><A NAME="foot405">... 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="foot387">...that simple</A><A +<DT><A NAME="foot411">...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. </DD> -<DT><A NAME="foot241">...restartable</A><A +<DT><A NAME="foot238">...restartable</A><A HREF="asn1c-usage.html#tex2html8"><SUP>4.2</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="foot313">... encoding</A><A +<DT><A NAME="foot314">... 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. @@ -1270,7 +1344,7 @@ which aren't important for the size determination. </DL><BR><HR> <ADDRESS> Lev Walkin -2004-09-17 +2004-09-26 </ADDRESS> </BODY> </HTML> |