expanded step-by-step examples

2 files changed, 538 insertions, 43 deletions

diff --git a/doc/asn1c-usage.lyx b/doc/asn1c-usage.lyx
index 695a5e09..03bf7ca6 100644
--- a/doc/asn1c-usage.lyx
+++ b/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,542 @@ free_struct
 \layout Part
 
 Examples
-\layout Chapter*
+\layout Chapter
+
+Step by step examples
+\layout Section
+
+A 
+\begin_inset Quotes sld
+\end_inset 
+
+Rectangle
+\begin_inset Quotes srd
+\end_inset 
+
+ Encoder
+\layout Standard
 
-Step-by-step: A 
+This chapter will help you to create a simple BER and XER encoder of a 
+\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 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
+\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
+
+ 
+\layout LyX-Code
+
+
+\size small 
+/*
+\layout LyX-Code
+
+
+\size small 
+ * This is a custom function which writes the
+\layout LyX-Code
+
+
+\size small 
+ * encoded output into some FILE stream.
+\layout LyX-Code
+
+
+\size small 
+ */
+\layout LyX-Code
+
+
+\size small 
+static int
+\layout LyX-Code
+
+
+\size small 
+write_out(const void *buffer, size_t size, void *app_key) {
+\layout LyX-Code
+
+
+\size small 
+    FILE *out_fp = app_key;
+\layout LyX-Code
+
+
+\size small 
+    size_t wrote;
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    wrote = fwrite(buffer, 1, size, out_fp);
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    return (wrote == size) ? 0 : -1;
+\layout LyX-Code
+
+
+\size small 
+}
+\layout LyX-Code
+
+ 
+\layout LyX-Code
+
+
+\size small 
+int main(int ac, char *av) {
+\layout LyX-Code
+
+
+\size small 
+    Rectangle_t *rectangle; /* Type to encode        */
+\layout LyX-Code
+
+
+\size small 
+    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 
+    rectangle = calloc(1, sizeof(Rectangle_t); /* not malloc! */
+\layout LyX-Code
+
+
+\size small 
+    if(!rectangle) {
+\layout LyX-Code
+
+
+\size small 
+      perror(
+\begin_inset Quotes sld
+\end_inset 
+
+calloc() failed
+\begin_inset Quotes srd
+\end_inset 
+
+);
+\layout LyX-Code
+
+
+\size small 
+      exit(71); /* better, EX_OSERR */
+\layout LyX-Code
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+ 
+\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 
+    rectangle->width  = 23;  /* any random value */
+\layout LyX-Code
+
+
+\size small 
+     
+\layout LyX-Code
+
+
+\size small 
+    /* BER encode the data if filename is given */
+\layout LyX-Code
+
+
+\size small 
+    if(ac < 2) {
+\layout LyX-Code
+
+
+\size small 
+      fprintf(stderr, 
+\begin_inset Quotes sld
+\end_inset 
+
+Specify filename for BER output
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+);
+\layout LyX-Code
+
+
+\size small 
+    } 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 
+      if(!fp) {
+\layout LyX-Code
+
+
+\size small 
+        perror(filename);
+\layout LyX-Code
+
+
+\size small 
+        exit(71); /* better, EX_OSERR */
+\layout LyX-Code
+
+
+\size small 
+      }
+\layout LyX-Code
+
+
+\size small 
+  
+\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 
+
+Could not encode Rectangle (at %s)
+\backslash 
+n
+\begin_inset Quotes srd
+\end_inset 
+
+,
+\layout LyX-Code
+
+
+\size small 
+          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 */
+\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
+
+
+\size small 
+    }
+\layout LyX-Code
+
+
+\size small 
+ 
+\layout LyX-Code
+
+
+\size small 
+    /* Also print the constructed Rectangle XER encoded (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; /* Encoding 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 
+rencode
+\series default 
+ *.c
+\end_deeper 
+\layout Enumerate
+
+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 
 
@@ -2790,7 +3284,7 @@ Rectangle
  Decoder
 \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 decoder of a simple 
 \begin_inset Quotes sld
 \end_inset 
 
@@ -3204,7 +3698,8 @@ rdecode
 \end_deeper 
 \layout Enumerate
 
-Voila! You have just created the Rectangle type decoder named 
+Voila! You have just created the BER decoder of a Rectangle type, named
+ 
 \series bold 
 rdecode
 \series default 
diff --git a/doc/asn1c-usage.pdf b/doc/asn1c-usage.pdf
index 88562665..09d6e098 100644
--- a/doc/asn1c-usage.pdf
+++ b/doc/asn1c-usage.pdf