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 @@ -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:

@@ -187,14 +189,14 @@ Rectangle ::= SEQUENCE { This ASN.1 specification describes a constructed type, Rectangle, 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 how that -entity is going to send or receive the encoded data 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 how +that entity is going to send or receive the encoded data 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.

The complete specification must be wrapped in a module, which looks @@ -203,10 +205,10 @@ like this: 

-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
-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. 
 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 Rectangle specification defined earlier in this document,
 may look like this2.2:
+  HREF="#foot574">2.2:
 
 

 
@@ -594,8 +596,8 @@ Quick start
 
 

 After building and installing the compiler, the asn1c3.1 command may be used to compile the ASN.1 specification3.2:
+  HREF="#foot575">3.1 command may be used to compile the ASN.1 specification3.2:
 
 

 
@@ -661,7 +663,7 @@ the compiler's behavior.
 
 

 

-

+

 
@@ -693,7 +695,7 @@ ting the usual support code.Use the specified directory with ASN.1 skeleton files.
+Generate the XML DTD for the specified ASN.1 modules.
@@ -805,7 +807,7 @@ be possible to compile everything with the single instruction:
 
 
 cc -o rectangle *.c   # It could be that simple4.1
+  HREF="#foot582">4.1
 

 

 
@@ -1289,14 +1291,144 @@ It is safe to invoke the free_struct function with the target
 structure pointer set to 0 (NULL), the function will do nothing.
 
 

- 
-

+
+

+Examples
+

+
+

+
+

+Step-by-step: A ''Rectangle'' Decoder
+

+
+

+This chapter will help you to create a simple decoder of a simple
+''Rectangle'' type used throughout this document.
+
+

+
+
    
+
  1. Create a file named rectangle.asn1 with the following contents:
+
+
    
+
+
    +RectangleModule1 DEFINITIONS ::=
+BEGIN
+ 
+Rectangle ::= SEQUENCE {
+    height  INTEGER,
+    width   INTEGER
+}
+ 
+END
+
    
+
    
+
+
    2. 
+
  2. Compile it into the set of .c and .h files using asn1c compiler [ASN1C]:
+
+
    
+
+
    +asn1c -fnative-types rectangle.asn1
+
    
+
    
+
+
    3. 
+
  3. Alternatively, use the Online ASN.1 compiler [AONL] by uploading
+the rectangle.asn1 file into the Web form and unpacking the
+produced archive on your computer.
+
    4. 
+
  4. By this time, you should have gotten multiple files in the current
+directory, including the Rectangle.c and Rectangle.h.
+
    5. 
+
  5. 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 main.c:
+
+
    
+
+
    +#include <stdio.h>
+#include <sys/types.h>
+#include <Rectangle.h>   /* Rectangle ASN.1 type  */
+ 
+int main(int ac, char **av) {
+    char buf[1024];      /* Temporary buffer      */
+    Rectangle_t *rectangle = 0; /* Type to decode */
+    asn_dec_rval_t rval; /* Decoder return value  */
+    FILE *fp;            /* Input file handler    */
+    size_t size;         /* Number of bytes read  */
+    char *filename;      /* Input file name */
+ 
+    /* Require a single filename argument */
+    if(ac != 2) {
+      fprintf(stderr, ''Usage: %s <file.ber>\n'', av[0]);
+      exit(64); /* better, EX_USAGE */
+    } else {
+      filename = av[1];
+    }
+ 
+    /* Open input file as read-only binary */
+    fp = fopen(filename, ''rb'');
+    if(!fp) {
+      perror(filename);
+      exit(66); /* better, EX_NOINPUT */
+    }
+  
+    /* Read up to the buffer size */
+    size = fread(buf, 1, sizeof(buf), fp);
+    fclose(fp);
+    if(!size) {
+      fprintf(stderr, ''%s: Empty or broken\n'', filename);
+      exit(65); /* better, EX_DATAERR */
+    }
+ 
+    /* Decode the input buffer as Rectangle type */
+    rval = ber_decode(0, &asn_DEF_Rectangle,
+      (void **)&rectangle, buf, size);
+    if(rval.code != RC_OK) {
+      fprintf(stderr,
+        ''%s: Broken Rectangle encoding at byte %ld\n'',
+        filename, (long)rval.consumed);
+      exit(65); /* better, EX_DATAERR */
+    }
+ 
+    /* Print the decoded Rectangle type as XML */
+    xer_fprint(stdout, &asn_DEF_Rectangle, rectangle);
+ 
+    return 0; /* Decoding finished successfully */
+}
+
    
+
    
+
+
    6. 
+
  6. Compile all files together using C compiler (varies by platform):
+
+
    
+
+
    +cc -I. -o rdecode *.c
+
    
+
    
+
+
    7. 
+
  7. Voila! You have just created the Rectangle type decoder named rdecode!
+
    8. 
+
 
+

 Bibliography
 
ASN1C
 
The OpenSource ASN.1 Compiler. http://lionet.info/asn1c/
+
AONL
+
Online ASN.1 Compiler. http://lionet.info/asn1c/asn1c.cgi
 
Dub00
-
Olivier Dubuisson - ASN.1 Communication between heterogeneous
-systems - Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
+
Olivier Dubuisson -- ASN.1 Communication between heterogeneous
+systems -- Morgan Kaufmann Publishers, 2000. http://asn1.elibel.tm.fr/en/book/.
 ISBN:0-12-6333361-0.
 
ITU-T/ASN.1
 
ITU-T Study Group 17 - Languages for Telecommunication Systems http://www.itu.int/ITU-T/studygroups/com17/languages/

@@ -1310,7 +1442,7 @@ ISBN:0-12-6333361-0.
 not a definitive factor.
 
 
-
... this... this2.2
-fnative-types compiler option is used to produce basic C int
 types instead of infinite width INTEGER_t structures. See Table 1.
@@ -1322,19 +1454,19 @@ types instead of infinite width INTEGER_t structures. See Table
 text (XML) based.
 
 

-
...asn1c...asn1c3.1
The 1 symbol in asn1c is a digit, not an ''ell'' letter.
 
 

-
... specification... specification3.2
This is probably not what you want to try out right now -
 read through the rest of this chapter to find out about -P
 and -R options.
 
 

-
...that simple...that simple4.1
Provided that you've also created a .c file with the int main()
 routine.
@@ -1356,7 +1488,7 @@ which aren't important for the size determination.
 

 

 Lev Walkin
-2004-09-30
+2005-01-17
 

 
 


 Table 1:
 The list of asn1c command line options
 
 
 
-X
-Generate the XML DTD schema for the specified ASN.1 modules.

 
 
Warning Options
 Description