mirror of https://gerrit.osmocom.org/asn1c
different layout
git-svn-id: https://asn1c.svn.sourceforge.net/svnroot/asn1c/trunk@684 59561ff5-6e30-0410-9f3c-9617f08c8826
This commit is contained in:
parent
edb12c668b
commit
485123c705
1446
doc/asn1c-usage.html
1446
doc/asn1c-usage.html
File diff suppressed because it is too large
Load Diff
|
@ -69,7 +69,7 @@ status Open
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
\backslash
|
\backslash
|
||||||
lhead{Document describes
|
lhead{This document describes
|
||||||
\backslash
|
\backslash
|
||||||
href{http://lionet.info/asn1c}{asn1c-0.9.9}}
|
href{http://lionet.info/asn1c}{asn1c-0.9.9}}
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
@ -109,17 +109,17 @@ Introduction to the ASN.1 Compiler
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
The purpose of the ASN.1 compiler, of which this document is part, is to
|
The purpose of the ASN.1 compiler, of which this document is part, is to
|
||||||
convert the ASN.1 specifications into some other target language.
|
convert the specifications in ASN.1 notation into some other language.
|
||||||
At this moment, only C and C++ target languages are supported, the latter
|
At this moment, only C and C++ target languages are supported, the latter
|
||||||
in upward compatibility mode.
|
is in upward compatibility mode.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
The compiler reads the specification and emits a series of target language
|
The compiler reads the specification and emits a series of target language
|
||||||
structures (C's structs, unions, enums) describing the corresponding ASN.1
|
structures (C's structs, unions, enums) describing the corresponding ASN.1
|
||||||
types.
|
types.
|
||||||
Also, it creates the code which allows automatic serialization and deserializat
|
The compiler also creates the code which allows automatic serialization
|
||||||
ion of these structures using several standardized encoding rules (BER,
|
and deserialization of these structures using several standardized encoding
|
||||||
DER, XER).
|
rules (BER, DER, XER).
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
For example, suppose the following ASN.1 module is given
|
For example, suppose the following ASN.1 module is given
|
||||||
|
@ -249,7 +249,7 @@ This is probably
|
||||||
not
|
not
|
||||||
\series default
|
\series default
|
||||||
what you want to try out right now -- read through the rest of this chapter
|
what you want to try out right now -- read through the rest of this chapter
|
||||||
and check the table
|
and check the Table
|
||||||
\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
|
\begin_inset LatexCommand \vref{cap:asn1c-cmdopts}
|
||||||
|
|
||||||
\end_inset
|
\end_inset
|
||||||
|
@ -959,9 +959,9 @@ Invoking the helper code
|
||||||
|
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
First of all, you should to include one or more header files into your applicati
|
First of all, you should include one or more header files into your application.
|
||||||
on.
|
Typically, it is enough to include the header file of the main PDU type.
|
||||||
For our Rectangle module, including the Rectangle.h file is enough:
|
For our Rectangle module, including the Rectangle.h file is sufficient:
|
||||||
\layout LyX-Code
|
\layout LyX-Code
|
||||||
|
|
||||||
#include <Rectangle.h>
|
#include <Rectangle.h>
|
||||||
|
@ -990,17 +990,21 @@ This code defines a
|
||||||
rect
|
rect
|
||||||
\emph default
|
\emph default
|
||||||
pointer which points to the Rectangle_t structure which needs to be freed.
|
pointer which points to the Rectangle_t structure which needs to be freed.
|
||||||
The second line invokes the generic free_struct routine created specifically
|
The second line invokes the generic
|
||||||
for this Rectangle_t structure.
|
\emph on
|
||||||
|
free_struct()
|
||||||
|
\emph default
|
||||||
|
routine created specifically for this Rectangle_t structure.
|
||||||
The
|
The
|
||||||
\emph on
|
\emph on
|
||||||
asn_DEF_Rectangle
|
asn_DEF_Rectangle
|
||||||
\emph default
|
\emph default
|
||||||
is the type descriptor, which holds a collection of generic routines to
|
is the type descriptor, which holds a collection of routines to deal with
|
||||||
deal with the Rectangle_t structure.
|
the Rectangle_t structure.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
There are several generic functions available:
|
The following member functions of the asn_DEF_Rectangle type descriptor
|
||||||
|
are of interest:
|
||||||
\layout Description
|
\layout Description
|
||||||
|
|
||||||
ber_decoder This is the generic
|
ber_decoder This is the generic
|
||||||
|
@ -1113,13 +1117,15 @@ Decoding BER
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
The Basic Encoding Rules describe the most widely used (by the ASN.1 community)
|
The Basic Encoding Rules describe the most widely used (by the ASN.1 community)
|
||||||
way how the structure can be encoded and decoded.
|
way to encode and decode a given structure in a machine-independent way.
|
||||||
Several other encoding rules (CER, DER) define a more restrictive versions
|
Several other encoding rules (CER, DER) define a more restrictive versions
|
||||||
of BER, so the generic BER parser is also capable of decoding the data
|
of BER, so the generic BER parser is also capable of decoding the data
|
||||||
encoded by CER and DER encoders.
|
encoded by CER and DER encoders.
|
||||||
The opposite is not true.
|
The opposite is not true.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
|
|
||||||
|
\emph on
|
||||||
The ASN.1 compiler provides the generic BER decoder which is implicitly capable
|
The ASN.1 compiler provides the generic BER decoder which is implicitly capable
|
||||||
of decoding BER, CER and DER encoded data.
|
of decoding BER, CER and DER encoded data.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
@ -1142,16 +1148,17 @@ You may concatenate these buffers and feed the BER decoder with 300 bytes
|
||||||
You may feed it the first buffer of 100 bytes of data, realize that the
|
You may feed it the first buffer of 100 bytes of data, realize that the
|
||||||
ber_decoder consumed only 95 bytes from it and later feed the decoder with
|
ber_decoder consumed only 95 bytes from it and later feed the decoder with
|
||||||
205 bytes buffer which consists of 5 unprocessed bytes from the first buffer
|
205 bytes buffer which consists of 5 unprocessed bytes from the first buffer
|
||||||
and the latter 200 bytes from the second buffer.
|
and the additional 200 bytes from the second buffer.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
This is not as convenient as it could be (like, the BER encoder would consume
|
This is not as convenient as it could be (like, the BER encoder could consume
|
||||||
the whole 100 bytes and keep these 5 bytes in some temporary storage),
|
the whole 100 bytes and keep these 5 bytes in some temporary storage),
|
||||||
but in case of stream-based processing it might actually be OK.
|
but in case of existing stream based processing it might actually fit well
|
||||||
|
into existing algorithm.
|
||||||
Suggestions are welcome.
|
Suggestions are welcome.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
Here is the simplest example which shows how to invoke a BER decoder.
|
Here is the simplest example of BER decoding.
|
||||||
\layout LyX-Code
|
\layout LyX-Code
|
||||||
|
|
||||||
Rectangle_t *
|
Rectangle_t *
|
||||||
|
@ -1226,35 +1233,35 @@ The code above defines a function,
|
||||||
\emph on
|
\emph on
|
||||||
simple_deserializer
|
simple_deserializer
|
||||||
\emph default
|
\emph default
|
||||||
, which takes a buffer and its length and expected to return a pointer to
|
, which takes a buffer and its length and is expected to return a pointer
|
||||||
the Rectangle_t structure.
|
to the Rectangle_t structure.
|
||||||
Inside, it tries to convert the bytes passed into the target structure
|
Inside, it tries to convert the bytes passed into the target structure
|
||||||
(rect) using the generic BER decoder and returns the rect pointer afterwards.
|
(rect) using the BER decoder and returns the rect pointer afterwards.
|
||||||
If the structure cannot be deserialized, it frees the memory which might
|
If the structure cannot be deserialized, it frees the memory which might
|
||||||
be left allocated by the unfinished
|
be left allocated by the unfinished
|
||||||
\emph on
|
\emph on
|
||||||
ber_decoder
|
ber_decoder
|
||||||
\emph default
|
\emph default
|
||||||
routine and returns 0 (no data).
|
routine and returns 0 (no data).
|
||||||
This
|
(This
|
||||||
\series bold
|
\series bold
|
||||||
freeing is necessary
|
freeing is necessary
|
||||||
\series default
|
\series default
|
||||||
because the ber_decoder is a restartable procedure, and may fail just because
|
because the ber_decoder is a restartable procedure, and may fail just because
|
||||||
there is more data needs to be provided before decoding could be finalized.
|
there is more data needs to be provided before decoding could be finalized).
|
||||||
The code above obviously does not take into account the way the
|
The code above obviously does not take into account the way the
|
||||||
\emph on
|
\emph on
|
||||||
ber_decoder
|
ber_decoder()
|
||||||
\emph default
|
\emph default
|
||||||
failed, so the freeing is necessary because the part of the buffer may
|
failed, so the freeing is necessary because the part of the buffer may
|
||||||
already be decoded into the structure by the time something goes wrong.
|
already be decoded into the structure by the time something goes wrong.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
A little less wordy would be to invoke a
|
A little less wordy would be to invoke a globally available
|
||||||
\emph on
|
\emph on
|
||||||
ber_decode
|
ber_decode()
|
||||||
\emph default
|
\emph default
|
||||||
function instead of dereferencing the asn_DEF_Rectangle:
|
function instead of dereferencing the asn_DEF_Rectangle type descriptor:
|
||||||
\layout LyX-Code
|
\layout LyX-Code
|
||||||
|
|
||||||
rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
|
rval = ber_decode(0, &asn_DEF_Rectangle, (void **)&rect,
|
||||||
|
@ -1623,6 +1630,15 @@ XML_to_Rectangle(const void *buffer, size_t buf_size) {
|
||||||
The decoder takes both BASIC-XER and CANONICAL-XER encodings.
|
The decoder takes both BASIC-XER and CANONICAL-XER encodings.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
|
The decoder shares its data consumption properties with BER decoder; please
|
||||||
|
read the Section
|
||||||
|
\begin_inset LatexCommand \vref{sub:Decoding-BER}
|
||||||
|
|
||||||
|
\end_inset
|
||||||
|
|
||||||
|
to know more.
|
||||||
|
\layout Standard
|
||||||
|
|
||||||
Please look into xer_decoder.h for the precise definition of xer_decode()
|
Please look into xer_decoder.h for the precise definition of xer_decode()
|
||||||
and related types.
|
and related types.
|
||||||
\layout Subsection
|
\layout Subsection
|
||||||
|
@ -1738,14 +1754,14 @@ In this example, the application programmer defined a custom structure with
|
||||||
of the Rectangle_t structure.
|
of the Rectangle_t structure.
|
||||||
If the freeing is necessary, the usual procedure of freeing everything
|
If the freeing is necessary, the usual procedure of freeing everything
|
||||||
must not be applied to the &rect pointer itself, because it does not point
|
must not be applied to the &rect pointer itself, because it does not point
|
||||||
to the memory block directly allocated by memory allocation routine, but
|
to the memory block directly allocated by the memory allocation routine,
|
||||||
instead lies within such a block allocated for my_figure structure.
|
but instead lies within a block allocated for the my_figure structure.
|
||||||
\layout Standard
|
\layout Standard
|
||||||
|
|
||||||
To solve this problem, the free_struct routine has the additional argument
|
To solve this problem, the free_struct routine has the additional argument
|
||||||
(besides the intuitive type descriptor and target structure pointers),
|
(besides the obvious type descriptor and target structure pointers), which
|
||||||
which is the flag specifying whether the outer pointer itself must be freed
|
is the flag specifying whether the outer pointer itself must be freed (0,
|
||||||
(0, default) or it should be left intact (non-zero value).
|
default) or it should be left intact (non-zero value).
|
||||||
\layout LyX-Code
|
\layout LyX-Code
|
||||||
|
|
||||||
|
|
||||||
|
|
Binary file not shown.
Loading…
Reference in New Issue