From 4a168ae4b6eceb78321f0bccfcfb6017b26abea9 Mon Sep 17 00:00:00 2001 From: vlm Date: Wed, 29 Sep 2004 13:37:15 +0000 Subject: [PATCH] api changes git-svn-id: https://asn1c.svn.sourceforge.net/svnroot/asn1c/trunk@450 59561ff5-6e30-0410-9f3c-9617f08c8826 --- doc/asn1c-usage.html | 91 +++++++++++++++++++++++--------------------- 1 file changed, 47 insertions(+), 44 deletions(-) diff --git a/doc/asn1c-usage.html b/doc/asn1c-usage.html index 9ac7b1ba..ded6c758 100644 --- a/doc/asn1c-usage.html +++ b/doc/asn1c-usage.html @@ -254,7 +254,7 @@ necessary, the subtype constraints must be used. SimpleInteger ::= INTEGER   -- An integer with a very limited range -SmallInt ::= INTEGER (0..127) +SmallPositiveInt ::= INTEGER (0..127)   -- Integer, negative NegativeInt ::= INTEGER (MIN..0) @@ -400,10 +400,10 @@ The PrintableString type

The character string with the following alphabet: space, ''''' (single quote), ''('', '')'', ''+'', -'','' (comma), ''-'', ''.'', ''/'', +'','' (comma), ''-'', ''.'', ''/'', digits (''0'' to ''9''), '':'', ''='', ''?'', upper-case and lower-case letters (''A'' to ''Z'' and ''a'' -to ''z'') +to ''z'').

@@ -413,7 +413,10 @@ The VisibleString type

The character string with the alphabet which is more or less a subset -of ASCII between space and ''~'' (tilde). +of ASCII between the space and the ''~'' +symbol (tilde). + +

Alternatively, the alphabet may be described as the PrintableString alphabet presented earlier, plus the following characters: ''!'', '''''', ''#'', ''$'', ''%'', @@ -557,12 +560,12 @@ Introduction to the ASN.1 Compiler The purpose of the ASN.1 compiler, of which this document is part, is to convert the ASN.1 specifications to some other target language (currently, only C is supported2.1). The compiler reads the specification and emits a series of target + HREF="#foot145">2.1). The compiler reads the specification and emits a series of target 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="#foot404">2.2:

@@ -576,7 +579,7 @@ typedef struct Rectangle_s { This would not be of much value for such a simple specification, so the compiler goes further and actually produces the code which fills in this structure by parsing the opaque binary2.3 data provided in some buffer. It also produces the code that takes + HREF="#foot152">2.3 data provided in some buffer. It also produces the code that takes this structure as an argument and performs structure serialization by emitting a series of bytes. @@ -588,8 +591,8 @@ Quick start

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

@@ -655,7 +658,7 @@ the compiler's behavior.


-
+
@@ -706,10 +709,10 @@ ting the usual support code.Description @@ -793,7 +796,7 @@ be possible to compile everything with the single instruction: 
 cc -o rectangle *.c   # It could be that simple4.1
+  HREF="#foot412">4.1
@@ -825,14 +828,14 @@ structure: 
 Rectangle_t *rect = ...;
  
-asn1_DEF_Rectangle->free_struct(&asn1_DEF_Rectangle,
+asn_DEF_Rectangle->free_struct(&asn_DEF_Rectangle,
     rect, 0);
This code defines a rect pointer which points to the Rectangle_t structure which needs to be freed. The second line invokes the generic free_struct routine created specifically for this Rectangle_t structure. -The asn1_DEF_Rectangle is the type descriptor, which holds +The asn_DEF_Rectangle is the type descriptor, which holds a collection of generic routines to deal with the Rectangle_t structure.

@@ -842,7 +845,7 @@ There are several generic functions available:

ber_decoder
This is the generic restartable4.2 BER decoder (Basic Encoding Rules). This decoder would create + HREF="#foot239">4.2 BER decoder (Basic Encoding Rules). This decoder would create and/or fill the target structure for you. Please refer to Section [Decoding-BER].
@@ -877,7 +880,7 @@ are semantically valid and constrained to appropriate implicit or explicit subtype constraints. Please refer to Section sub:Validating-the-target.

-Each of the above function takes the type descriptor (asn1_DEF_...) +Each of the above function takes the type descriptor (asn_DEF_...) and the target structure (rect, in the above example). The target structure is typically created by the generic BER decoder or by the application itself. @@ -893,8 +896,8 @@ simple_deserializer(const void *buffer, size_t buf_size)&nbs     Rectangle_t *rect = 0;    /* Note this 0! */     ber_dec_rval_t rval;   -    rval = asn1_DEF_Rectangle->ber_decoder( -          &asn1_DEF_Rectangle, +    rval = asn_DEF_Rectangle->ber_decoder(0, +          &asn_DEF_Rectangle,           (void **)&rect,           buffer, buf_size,           0); @@ -903,8 +906,8 @@ simple_deserializer(const void *buffer, size_t buf_size)&nbs         return rect;          /* Decoding succeeded */     } else {         /* Free partially decoded rect */ -        asn1_DEF_Rectangle->free_struct( -            &asn1_DEF_Rectangle, rect, 0); +        asn_DEF_Rectangle->free_struct( +            &asn_DEF_Rectangle, rect, 0);         return 0;     } } @@ -985,18 +988,18 @@ wrapper of the former approach into a less wordy notation: 

-rval = ber_decode(&asn1_DEF_Rectangle, (void **)&rect,
+rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
     buffer, buf_size);
-Note that the initial (asn1_DEF_Rectangle->ber_decoder) reference +Note that the initial (asn_DEF_Rectangle->ber_decoder) reference is gone, and also the last argument (0) is no longer necessary.

These two ways of invocations are fully equivalent.

-The BER decoder may fail because (the following RC_... +The BER decoder may fail because of (the following RC_... codes are defined in ber_decoder.h):

@@ -1039,8 +1042,8 @@ X.509 certificates.

As with BER decoder, the DER encoder may be invoked either directly -from the ASN.1 type descriptor (asn1_DEF_Rectangle) or from the -stand-alone function, which is somewhat simpler: +from the ASN.1 type descriptor (asn_DEF_Rectangle) or from the stand-alone +function, which is somewhat simpler:

@@ -1068,7 +1071,7 @@ ssize_t simple_serializer(FILE *ostream, Rectangle_t *rect) {     asn_enc_rval_t er;  /* Encoder return value */   -    er = der_encode(&asn1_DEF_Rect, rect, +    er = der_encode(&asn_DEF_Rect, rect,         write_stream, ostream);     if(er.encoded == -1) {         /* @@ -1098,7 +1101,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 encoding4.3. + HREF="#foot315">4.3.

Please look into der_encoder.h for the precise definition of der_encode() @@ -1133,7 +1136,7 @@ int print_as_XML(FILE *ostream, Rectangle_t *rect) {     asn_enc_rval_t er;  /* Encoder return value */   -    er = xer_encode(&asn1_DEF_Rect, rect, +    er = xer_encode(&asn_DEF_Rect, rect,         XER_F_BASIC, /* BASIC-XER or CANONICAL-XER */         write_stream, ostream);   @@ -1190,7 +1193,7 @@ function, which is a simpler wrapper of the former: 

-asn_fprint(stdout, &asn1_DEF_Rectangle, rect);
+asn_fprint(stdout, &asn_DEF_Rectangle, rect);
Please look into constr_TYPE.h for the precise definition of asn_fprint() @@ -1206,7 +1209,7 @@ call: 

-xer_fprint(stdout, &asn1_DEF_Rectangle, rect);
+xer_fprint(stdout, &asn_DEF_Rectangle, rect);
See Section sub:Encoding-XER for XML-related details. @@ -1260,8 +1263,8 @@ struct my_figure *mf = ...;  * Freeing the Rectangle_td  * without freeing the mf->rect pointer  */ -asn1_DEF_Rectangle->free_struct( -    &asn1_DEF_Rectangle, &mf->rect, 1 /* !free */); +asn_DEF_Rectangle->free_struct( +    &asn_DEF_Rectangle, &mf->rect, 1 /* !free */);   /* Rectangle_t is a stand-alone pointer */ Rectangle_t *rect = ...; @@ -1269,8 +1272,8 @@ Rectangle_t *rect = ...;  * Freeing the Rectangle_t  * and freeing the rect pointer  */ -asn1_DEF_Rectangle->free_struct( -    &asn1_DEF_Rectangle, rect, 0 /* free the pointer too */); +asn_DEF_Rectangle->free_struct( +    &asn_DEF_Rectangle, rect, 0 /* free the pointer too */); It is safe to invoke the free_struct function with the target @@ -1292,50 +1295,50 @@ ISBN:0-12-6333361-0.


Footnotes

-
... supported... supported2.1
C++ is ''supported'' too, as long as an class-based approach is 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.
-
... binary... binary2.3
BER, CER and DER encodings are binary. However, the XER encoding is 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.
-
...restartable...restartable4.2
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.
-
... encoding... encoding4.3
It is actually faster too: the encoder might skip over some computations which aren't important for the size determination. @@ -1344,7 +1347,7 @@ which aren't important for the size determination.

Lev Walkin -2004-09-26 +2004-09-29
Table 1: The list of asn1c command line options
-fall-defs-global -Normally the compiler hides the definitions (asn1_DEF_xxx) of the +Normally the compiler hides the definitions (asn_DEF_xxx) of the inner structure elements (members of SEQUENCE, SET and other types). This option makes all such definitions global. Enabling this option -may pollute the namespace by making lots of asn1_DEF_xxx structures +may pollute the namespace by making lots of asn_DEF_xxx structures globally visible, but will allow you to manipulate (encode and decode) the individual members of any complex ASN.1 structure.