mirror of https://gerrit.osmocom.org/asn1c
api changes
git-svn-id: https://asn1c.svn.sourceforge.net/svnroot/asn1c/trunk@450 59561ff5-6e30-0410-9f3c-9617f08c8826
This commit is contained in:
parent
0d181f2074
commit
4a168ae4b6
|
@ -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</A>
|
|||
<P>
|
||||
The character string with the following alphabet: space, ''<B>'</B>''
|
||||
(single quote), ''<B>(</B>'', ''<B>)</B>'', ''<B>+</B>'',
|
||||
'','' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
|
||||
''<B>,</B>'' (comma), ''<B>-</B>'', ''<B>.</B>'', ''<B>/</B>'',
|
||||
digits (''0'' to ''9''), ''<B>:</B>'', ''<B>=</B>'', ''<B>?</B>'',
|
||||
upper-case and lower-case letters (''A'' to ''Z'' and ''a''
|
||||
to ''z'')
|
||||
to ''z'').
|
||||
|
||||
<P>
|
||||
|
||||
|
@ -413,7 +413,10 @@ The VisibleString type</A>
|
|||
|
||||
<P>
|
||||
The character string with the alphabet which is more or less a subset
|
||||
of ASCII between space and ''<B>~</B>'' (tilde).
|
||||
of ASCII between the space and the ''<B>~</B>''
|
||||
symbol (tilde).
|
||||
|
||||
<P>
|
||||
Alternatively, the alphabet may be described as the PrintableString
|
||||
alphabet presented earlier, plus the following characters: ''<B>!</B>'',
|
||||
''<B>''</B>'', ''<B>#</B>'', ''<B>$</B>'', ''<B>%</B>'',
|
||||
|
@ -557,12 +560,12 @@ Introduction to the ASN.1 Compiler</A>
|
|||
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 supported<A NAME="tex2html1"
|
||||
HREF="#foot144"><SUP>2.1</SUP></A>). The compiler reads the specification and emits a series of target
|
||||
HREF="#foot145"><SUP>2.1</SUP></A>). 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 <I>Rectangle</I> specification defined earlier in this document,
|
||||
may look like this<A NAME="tex2html2"
|
||||
HREF="#foot403"><SUP>2.2</SUP></A>:
|
||||
HREF="#foot404"><SUP>2.2</SUP></A>:
|
||||
|
||||
<P>
|
||||
|
||||
|
@ -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 binary<A NAME="tex2html3"
|
||||
HREF="#foot151"><SUP>2.3</SUP></A> data provided in some buffer. It also produces the code that takes
|
||||
HREF="#foot152"><SUP>2.3</SUP></A> 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</A>
|
|||
|
||||
<P>
|
||||
After building and installing the compiler, the <I>asn1c</I><A NAME="tex2html4"
|
||||
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>:
|
||||
HREF="#foot405"><SUP>3.1</SUP></A> command may be used to compile the ASN.1 specification<A NAME="tex2html5"
|
||||
HREF="#foot406"><SUP>3.2</SUP></A>:
|
||||
|
||||
<P>
|
||||
|
||||
|
@ -655,7 +658,7 @@ the compiler's behavior.
|
|||
|
||||
<P>
|
||||
<BR><P></P>
|
||||
<DIV ALIGN="CENTER"><A NAME="408"></A>
|
||||
<DIV ALIGN="CENTER"><A NAME="409"></A>
|
||||
<TABLE>
|
||||
<CAPTION><STRONG><A NAME=Table1>Table 1:</A></STRONG>
|
||||
The list of asn1c command line options</CAPTION>
|
||||
|
@ -706,10 +709,10 @@ ting the usual support code.</FONT></TD></TR>
|
|||
<B>Description</B></TD></TR>
|
||||
</TBODY><TBODY>
|
||||
<TR><TD VALIGN=BASELINE ALIGN=LEFT NOWRAP>-fall-defs-global</TD><TD VALIGN=BASELINE ALIGN=LEFT WIDTH="216">
|
||||
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.</TD></TR>
|
||||
</TBODY><TBODY>
|
||||
|
@ -793,7 +796,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="#foot411"><SUP>4.1</SUP></A>
|
||||
HREF="#foot412"><SUP>4.1</SUP></A>
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
|
||||
|
@ -825,14 +828,14 @@ structure:
|
|||
<BLOCKQUOTE><PRE>
|
||||
Rectangle_t *rect = ...;
|
||||
|
||||
asn1_DEF_Rectangle->free_struct(&asn1_DEF_Rectangle,
|
||||
asn_DEF_Rectangle->free_struct(&asn_DEF_Rectangle,
|
||||
rect, 0);
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
This code defines a <I>rect</I> 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 <I>asn1_DEF_Rectangle</I> is the type descriptor, which holds
|
||||
The <I>asn_DEF_Rectangle</I> is the type descriptor, which holds
|
||||
a collection of generic routines to deal with the Rectangle_t structure.
|
||||
|
||||
<P>
|
||||
|
@ -842,7 +845,7 @@ There are several generic functions available:
|
|||
<DL>
|
||||
<DT><STRONG>ber_decoder</STRONG></DT>
|
||||
<DD>This is the generic <I>restartable</I><A NAME="tex2html8"
|
||||
HREF="#foot238"><SUP>4.2</SUP></A> BER decoder (Basic Encoding Rules). This decoder would create
|
||||
HREF="#foot239"><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>
|
||||
|
@ -877,7 +880,7 @@ 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>)
|
||||
Each of the above function takes the type descriptor (<I>asn_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
|
||||
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:
|
|||
<P>
|
||||
|
||||
<BLOCKQUOTE><PRE>
|
||||
rval = ber_decode(&asn1_DEF_Rectangle, (void **)&rect,
|
||||
rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
|
||||
buffer, buf_size);
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
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.
|
||||
|
||||
<P>
|
||||
These two ways of invocations are fully equivalent.
|
||||
|
||||
<P>
|
||||
The BER de<I>coder</I> may fail because (<I>the following RC_...
|
||||
The BER de<I>coder</I> may fail because of (<I>the following RC_...
|
||||
codes are defined in ber_decoder.h</I>):
|
||||
|
||||
<P>
|
||||
|
@ -1039,8 +1042,8 @@ X.509 certificates.
|
|||
|
||||
<P>
|
||||
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:
|
||||
|
||||
<P>
|
||||
|
||||
|
@ -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.<B>encoded</B> == -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 encoding<A NAME="tex2html9"
|
||||
HREF="#foot314"><SUP>4.3</SUP></A>.
|
||||
HREF="#foot315"><SUP>4.3</SUP></A>.
|
||||
|
||||
<P>
|
||||
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:
|
|||
<P>
|
||||
|
||||
<BLOCKQUOTE><PRE>
|
||||
asn_fprint(stdout, &asn1_DEF_Rectangle, rect);
|
||||
asn_fprint(stdout, &asn_DEF_Rectangle, rect);
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
Please look into constr_TYPE.h for the precise definition of asn_fprint()
|
||||
|
@ -1206,7 +1209,7 @@ call:
|
|||
<P>
|
||||
|
||||
<BLOCKQUOTE><PRE>
|
||||
xer_fprint(stdout, &asn1_DEF_Rectangle, rect);
|
||||
xer_fprint(stdout, &asn_DEF_Rectangle, rect);
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
See Section sub:Encoding-XER for XML-related details.
|
||||
|
@ -1260,8 +1263,8 @@ struct my_figure *mf = <B>...</B>;
|
|||
* Freeing the Rectangle_td
|
||||
* without freeing the mf->rect pointer
|
||||
*/
|
||||
asn1_DEF_Rectangle->free_struct(
|
||||
&asn1_DEF_Rectangle, &mf->rect, <I>1</I> /* !free */);
|
||||
asn_DEF_Rectangle->free_struct(
|
||||
&asn_DEF_Rectangle, &mf->rect, <I>1</I> /* !free */);
|
||||
|
||||
/* Rectangle_t is a stand-alone pointer */
|
||||
Rectangle_t *rect = <B>...</B>;
|
||||
|
@ -1269,8 +1272,8 @@ Rectangle_t *rect = <B>...</B>;
|
|||
* Freeing the Rectangle_t
|
||||
* and freeing the rect pointer
|
||||
*/
|
||||
asn1_DEF_Rectangle->free_struct(
|
||||
&asn1_DEF_Rectangle, rect, <I>0</I> /* free the pointer too */);
|
||||
asn_DEF_Rectangle->free_struct(
|
||||
&asn_DEF_Rectangle, rect, <I>0</I> /* free the pointer too */);
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
It is safe to invoke the <I>free_struct</I> function with the target
|
||||
|
@ -1292,50 +1295,50 @@ ISBN:0-12-6333361-0.
|
|||
<P>
|
||||
<BR><HR><H4>Footnotes</H4>
|
||||
<DL>
|
||||
<DT><A NAME="foot144">... supported</A><A
|
||||
<DT><A NAME="foot145">... supported</A><A
|
||||
HREF="asn1c-usage.html#tex2html1"><SUP>2.1</SUP></A></DT>
|
||||
<DD>C++ is ''supported'' too, as long as an class-based approach is
|
||||
not a definitive factor.
|
||||
|
||||
</DD>
|
||||
<DT><A NAME="foot403">... this</A><A
|
||||
<DT><A NAME="foot404">... 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>.
|
||||
|
||||
</DD>
|
||||
<DT><A NAME="foot151">... binary</A><A
|
||||
<DT><A NAME="foot152">... binary</A><A
|
||||
HREF="asn1c-usage.html#tex2html3"><SUP>2.3</SUP></A></DT>
|
||||
<DD>BER, CER and DER encodings are binary. However, the XER encoding is
|
||||
text (XML) based.
|
||||
|
||||
</DD>
|
||||
<DT><A NAME="foot404">...asn1c</A><A
|
||||
<DT><A NAME="foot405">...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="foot405">... specification</A><A
|
||||
<DT><A NAME="foot406">... 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="foot411">...that simple</A><A
|
||||
<DT><A NAME="foot412">...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="foot238">...restartable</A><A
|
||||
<DT><A NAME="foot239">...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="foot314">... encoding</A><A
|
||||
<DT><A NAME="foot315">... 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.
|
||||
|
@ -1344,7 +1347,7 @@ which aren't important for the size determination.
|
|||
</DL><BR><HR>
|
||||
<ADDRESS>
|
||||
Lev Walkin
|
||||
2004-09-26
|
||||
2004-09-29
|
||||
</ADDRESS>
|
||||
</BODY>
|
||||
</HTML>
|
||||
|
|
Loading…
Reference in New Issue