expanded step-by-step examples

doc/asn1c-usage.lyx

@@ -2320,45 +2320,6 @@ As with BER decoder, the DER encoder may be invoked either directly from
  which is somewhat simpler:
 \layout LyX-Code
 
-/*
-\layout LyX-Code
-
- * This is a custom function which writes the
-\layout LyX-Code
-
- * encoded output into some FILE stream.
-\layout LyX-Code
-
- */
-\layout LyX-Code
-
-static int
-\layout LyX-Code
-
-write_stream(const void *buffer, size_t size, void *app_key) {
-\layout LyX-Code
-
-    FILE *ostream = app_key;
-\layout LyX-Code
-
-    size_t wrote;
-\layout LyX-Code
-
- 
-\layout LyX-Code
-
-    wrote = fwrite(buffer, 1, size, ostream);
-\layout LyX-Code
-
- 
-\layout LyX-Code
-
-    return (wrote == size) ? 0 : -1;
-\layout LyX-Code
-
-}
-\layout LyX-Code
-
  
 \layout LyX-Code
 
@@ -2777,9 +2738,12 @@ free_struct
 \layout Part
 
 Examples
-\layout Chapter*
+\layout Chapter
+
+Step by step examples
+\layout Section
 
-Step-by-step: A 
+A 
 \begin_inset Quotes sld
 \end_inset 
 
@@ -2787,10 +2751,10 @@ Rectangle
 \begin_inset Quotes srd
 \end_inset 
 
- Decoder
+ Encoder
 \layout Standard
 
-This chapter will help you to create a simple decoder of a simple 
+This chapter will help you to create a simple BER and XER encoder of a 
 \begin_inset Quotes sld
 \end_inset 
 
@@ -2879,9 +2843,8 @@ Rectangle.h
 .
 \layout Enumerate
 
-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) representat
-ion of the Rectangle type.
+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 
 \series bold 
 main.c
@@ -2915,44 +2878,47 @@ clearpage{}
 #include <Rectangle.h>   /* Rectangle ASN.1 type  */
 \layout LyX-Code
 
+ 
+\layout LyX-Code
+
 
 \size small 
- 
+/*
 \layout LyX-Code
 
 
 \size small 
-int main(int ac, char **av) {
+ * This is a custom function which writes the
 \layout LyX-Code
 
 
 \size small 
-    char buf[1024];      /* Temporary buffer      */
+ * encoded output into some FILE stream.
 \layout LyX-Code
 
 
 \size small 
-    Rectangle_t *rectangle = 0; /* Type to decode */
+ */
 \layout LyX-Code
 
 
 \size small 
-    asn_dec_rval_t rval; /* Decoder return value  */
+static int
 \layout LyX-Code
 
 
 \size small 
-    FILE *fp;            /* Input file handler    */
+write_out(const void *buffer, size_t size, void *app_key) {
 \layout LyX-Code
 
 
 \size small 
-    size_t size;         /* Number of bytes read  */
+    FILE *out_fp = app_key;
 \layout LyX-Code
 
 
 \size small 
-    char *filename;      /* Input file name */
+    size_t wrote;
 \layout LyX-Code
 
 
@@ -2962,66 +2928,69 @@ int main(int ac, char **av) {
 
 
 \size small 
-    /* Require a single filename argument */
+    wrote = fwrite(buffer, 1, size, out_fp);
 \layout LyX-Code
 
 
 \size small 
-    if(ac != 2) {
+ 
 \layout LyX-Code
 
 
 \size small 
-      fprintf(stderr, 
-\begin_inset Quotes sld
-\end_inset 
+    return (wrote == size) ? 0 : -1;
+\layout LyX-Code
 
-Usage: %s <file.ber>
-\backslash 
-n
-\begin_inset Quotes srd
-\end_inset 
 
-, av[0]);
+\size small 
+}
+\layout LyX-Code
+
+ 
 \layout LyX-Code
 
 
 \size small 
-      exit(64); /* better, EX_USAGE */
+int main(int ac, char *av) {
 \layout LyX-Code
 
 
 \size small 
-    } else {
+    Rectangle_t *rectangle; /* Type to encode        */
 \layout LyX-Code
 
 
 \size small 
-      filename = av[1];
+    asn_enc_rval_t ec;      /* Encoder return value  */
 \layout LyX-Code
 
 
 \size small 
-    }
+ 
 \layout LyX-Code
 
 
 \size small 
- 
+    /* Allocate the Rectangle_t */
 \layout LyX-Code
 
 
 \size small 
-    /* Open input file as read-only binary */
+    rectangle = calloc(1, sizeof(Rectangle_t); /* not malloc! */
 \layout LyX-Code
 
 
 \size small 
-    fp = fopen(filename, 
+    if(!rectangle) {
+\layout LyX-Code
+
+
+\size small 
+      perror(
 \begin_inset Quotes sld
 \end_inset 
 
-rb
+calloc() failed
 \begin_inset Quotes srd
 \end_inset 
 
@@ -3030,47 +2999,47 @@ rb
 
 
 \size small 
-    if(!fp) {
+      exit(71); /* better, EX_OSERR */
 \layout LyX-Code
 
 
 \size small 
-      perror(filename);
+    }
 \layout LyX-Code
 
 
 \size small 
-      exit(66); /* better, EX_NOINPUT */
+ 
 \layout LyX-Code
 
 
 \size small 
-    }
+    /* Initialize the Rectangle members */
 \layout LyX-Code
 
 
 \size small 
-  
+    rectangle->height = 42;  /* any random value */
 \layout LyX-Code
 
 
 \size small 
-    /* Read up to the buffer size */
+    rectangle->width  = 23;  /* any random value */
 \layout LyX-Code
 
 
 \size small 
-    size = fread(buf, 1, sizeof(buf), fp);
+     
 \layout LyX-Code
 
 
 \size small 
-    fclose(fp);
+    /* BER encode the data if filename is given */
 \layout LyX-Code
 
 
 \size small 
-    if(!size) {
+    if(ac < 2) {
 \layout LyX-Code
 
 
@@ -3079,62 +3048,103 @@ rb
 \begin_inset Quotes sld
 \end_inset 
 
-%s: Empty or broken
+Specify filename for BER output
 \backslash 
 n
 \begin_inset Quotes srd
 \end_inset 
 
-, filename);
+);
 \layout LyX-Code
 
 
 \size small 
-      exit(65); /* better, EX_DATAERR */
+    } else {
 \layout LyX-Code
 
 
 \size small 
-    }
+      const char *filename = av[1];
 \layout LyX-Code
 
 
 \size small 
+      FILE *fp = fopen(filename, 
+\begin_inset Quotes sld
+\end_inset 
+
+w
+\begin_inset Quotes srd
+\end_inset 
+
+);   /* for BER output */
+\layout LyX-Code
+
  
 \layout LyX-Code
 
 
 \size small 
-    /* Decode the input buffer as Rectangle type */
+      if(!fp) {
 \layout LyX-Code
 
 
 \size small 
-    rval = ber_decode(0, &asn_DEF_Rectangle,
+        perror(filename);
 \layout LyX-Code
 
 
 \size small 
-      (void **)&rectangle, buf, size);
+        exit(71); /* better, EX_OSERR */
 \layout LyX-Code
 
 
 \size small 
-    if(rval.code != RC_OK) {
+      }
 \layout LyX-Code
 
 
 \size small 
-      fprintf(stderr,
+  
 \layout LyX-Code
 
 
 \size small 
-        
+      /* Encode the Rectangle type as BER (DER) */
+\layout LyX-Code
+
+
+\size small 
+      ec = der_encode(&asn_DEF_Rectangle,
+\layout LyX-Code
+
+
+\size small 
+            rectangle, write_out, stream);
+\layout LyX-Code
+
+
+\size small 
+      fclose(fp);
+\layout LyX-Code
+
+
+\size small 
+      if(ec.encoded == -1) {
+\layout LyX-Code
+
+
+\size small 
+        fprintf(stderr,
+\layout LyX-Code
+
+
+\size small 
+          
 \begin_inset Quotes sld
 \end_inset 
 
-%s: Broken Rectangle encoding at byte %ld
+Could not encode Rectangle (at %s)
 \backslash 
 n
 \begin_inset Quotes srd
@@ -3145,12 +3155,50 @@ n
 
 
 \size small 
-        filename, (long)rval.consumed);
+          ec.failed_type ? ec.failed_type->name : 
+\begin_inset Quotes sld
+\end_inset 
+
+unknown
+\begin_inset Quotes srd
+\end_inset 
+
+);
 \layout LyX-Code
 
 
 \size small 
-      exit(65); /* better, EX_DATAERR */
+        exit(65); /* better, EX_DATAERR */
+\layout LyX-Code
+
+
+\size small 
+      } else {
+\layout LyX-Code
+
+
+\size small 
+        fprintf(stderr, 
+\begin_inset Quotes sld
+\end_inset 
+
+Created %s with BER encoded Rectangle
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+,
+\layout LyX-Code
+
+
+\size small 
+          filename);
+\layout LyX-Code
+
+
+\size small 
+      }
 \layout LyX-Code
 
 
@@ -3165,7 +3213,7 @@ n
 
 
 \size small 
-    /* Print the decoded Rectangle type as XML */
+    /* Also print the constructed Rectangle XER encoded (XML) */
 \layout LyX-Code
 
 
@@ -3180,7 +3228,7 @@ n
 
 
 \size small 
-    return 0; /* Decoding finished successfully */
+    return 0; /* Encoding finished successfully */
 \layout LyX-Code
 
 
@@ -3198,13 +3246,460 @@ Compile all files together using C compiler (varies by platform):
 cc -I.
  -o 
 \series bold 
-rdecode
+rencode
 \series default 
  *.c
 \end_deeper 
 \layout Enumerate
 
-Voila! You have just created the Rectangle type decoder named 
+Voila! You have just created the BER and XER encoder of a Rectangle type,
+ named 
+\series bold 
+rencode
+\series default 
+!
+\layout Standard
+
+
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash 
+clearpage{}
+\end_inset 
+
+
+\layout Section
+
+A 
+\begin_inset Quotes sld
+\end_inset 
+
+Rectangle
+\begin_inset Quotes srd
+\end_inset 
+
+ Decoder
+\layout Standard
+
+This chapter will help you to create a simple BER decoder of a simple 
+\begin_inset Quotes sld
+\end_inset 
+
+Rectangle
+\begin_inset Quotes srd
+\end_inset 
+
+ type used throughout this document.
+\layout Enumerate
+
+Create a file named 
+\series bold 
+rectangle.asn1
+\series default 
+ with the following contents:
+\begin_deeper 
+\layout LyX-Code
+
+RectangleModule1 DEFINITIONS ::=
+\layout LyX-Code
+
+BEGIN
+\layout LyX-Code
+
+ 
+\layout LyX-Code
+
+Rectangle ::= SEQUENCE {
+\layout LyX-Code
+
+    height  INTEGER,
+\layout LyX-Code
+
+    width   INTEGER
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+ 
+\layout LyX-Code
+
+END
+\end_deeper 
+\layout Enumerate
+
+Compile it into the set of .c and .h files using asn1c compiler 
+\begin_inset LatexCommand \cite{ASN1C}
+
+\end_inset 
+
+:
+\begin_deeper 
+\layout LyX-Code
+
+
+\emph on 
+asn1c -fnative-types 
+\series bold 
+\emph default 
+rectangle.asn1
+\end_deeper 
+\layout Enumerate
+
+Alternatively, use the Online ASN.1 compiler 
+\begin_inset LatexCommand \cite{AONL}
+
+\end_inset 
+
+ by uploading the 
+\series bold 
+rectangle.asn1
+\series default 
+ file into the Web form and unpacking the produced archive on your computer.
+\layout Enumerate
+
+By this time, you should have gotten multiple files in the current directory,
+ including the 
+\series bold 
+Rectangle.c
+\series default 
+ and 
+\series bold 
+Rectangle.h
+\series default 
+.
+\layout Enumerate
+
+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) representat
+ion of the Rectangle type.
+ Let's name the file 
+\series bold 
+main.c
+\series default 
+:
+\begin_inset ERT
+status Open
+
+\layout Standard
+
+\backslash 
+clearpage{}
+\end_inset 
+
+
+\begin_deeper 
+\layout LyX-Code
+
+
+\size small 
+#include <stdio.h>
+\layout LyX-Code
+
+
+\size small 
+#include <sys/types.h>
+\layout LyX-Code
+
+
+\size small 
+#include <Rectangle.h>   /* Rectangle ASN.1 type  */
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+int main(int ac, char **av) {
+\layout LyX-Code
+
+
+\size small 
+    char buf[1024];      /* Temporary buffer      */
+\layout LyX-Code
+
+
+\size small 
+    Rectangle_t *rectangle = 0; /* Type to decode */
+\layout LyX-Code
+
+
+\size small 
+    asn_dec_rval_t rval; /* Decoder return value  */
+\layout LyX-Code
+
+
+\size small 
+    FILE *fp;            /* Input file handler    */
+\layout LyX-Code
+
+
+\size small 
+    size_t size;         /* Number of bytes read  */
+\layout LyX-Code
+
+
+\size small 
+    char *filename;      /* Input file name */
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    /* Require a single filename argument */
+\layout LyX-Code
+
+
+\size small 
+    if(ac != 2) {
+\layout LyX-Code
+
+
+\size small 
+      fprintf(stderr, 
+\begin_inset Quotes sld
+\end_inset 
+
+Usage: %s <file.ber>
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+, av[0]);
+\layout LyX-Code
+
+
+\size small 
+      exit(64); /* better, EX_USAGE */
+\layout LyX-Code
+
+
+\size small 
+    } else {
+\layout LyX-Code
+
+
+\size small 
+      filename = av[1];
+\layout LyX-Code
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    /* Open input file as read-only binary */
+\layout LyX-Code
+
+
+\size small 
+    fp = fopen(filename, 
+\begin_inset Quotes sld
+\end_inset 
+
+rb
+\begin_inset Quotes srd
+\end_inset 
+
+);
+\layout LyX-Code
+
+
+\size small 
+    if(!fp) {
+\layout LyX-Code
+
+
+\size small 
+      perror(filename);
+\layout LyX-Code
+
+
+\size small 
+      exit(66); /* better, EX_NOINPUT */
+\layout LyX-Code
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+  
+\layout LyX-Code
+
+
+\size small 
+    /* Read up to the buffer size */
+\layout LyX-Code
+
+
+\size small 
+    size = fread(buf, 1, sizeof(buf), fp);
+\layout LyX-Code
+
+
+\size small 
+    fclose(fp);
+\layout LyX-Code
+
+
+\size small 
+    if(!size) {
+\layout LyX-Code
+
+
+\size small 
+      fprintf(stderr, 
+\begin_inset Quotes sld
+\end_inset 
+
+%s: Empty or broken
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+, filename);
+\layout LyX-Code
+
+
+\size small 
+      exit(65); /* better, EX_DATAERR */
+\layout LyX-Code
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    /* Decode the input buffer as Rectangle type */
+\layout LyX-Code
+
+
+\size small 
+    rval = ber_decode(0, &asn_DEF_Rectangle,
+\layout LyX-Code
+
+
+\size small 
+      (void **)&rectangle, buf, size);
+\layout LyX-Code
+
+
+\size small 
+    if(rval.code != RC_OK) {
+\layout LyX-Code
+
+
+\size small 
+      fprintf(stderr,
+\layout LyX-Code
+
+
+\size small 
+        
+\begin_inset Quotes sld
+\end_inset 
+
+%s: Broken Rectangle encoding at byte %ld
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+,
+\layout LyX-Code
+
+
+\size small 
+        filename, (long)rval.consumed);
+\layout LyX-Code
+
+
+\size small 
+      exit(65); /* better, EX_DATAERR */
+\layout LyX-Code
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    /* Print the decoded Rectangle type as XML */
+\layout LyX-Code
+
+
+\size small 
+    xer_fprint(stdout, &asn_DEF_Rectangle, rectangle);
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    return 0; /* Decoding finished successfully */
+\layout LyX-Code
+
+
+\size small 
+}
+\end_deeper 
+\layout Enumerate
+
+Compile all files together using C compiler (varies by platform):
+\begin_deeper 
+\layout LyX-Code
+
+
+\emph on 
+cc -I.
+ -o 
+\series bold 
+rdecode
+\series default 
+ *.c
+\end_deeper 
+\layout Enumerate
+
+Voila! You have just created the BER decoder of a Rectangle type, named
+ 
 \series bold 
 rdecode
 \series default