It would also create the code for converting this structure into platform-independent
wire representation (a serializer API) and the decoder of such wire
representation back into local, machine-specific type (a deserializer
API).
The asn1c compiler also creates the code for converting this structure into
platform-independent wire representation and the decoder
of such wire representation back into local, machine-specific type.
These encoders and decoders are also called serializers and deserializers,
marshallers and unmarshallers, or codecs.
\section{Quick start with asn1c}
After building and installing the compiler, the \emph{asn1c}
command may be used to compile the ASN.1 modules%
After building and installing the compiler, the \cmd{asn1c}
may be used to compile the ASN.1 modules%
\footnote{This is probably \textbf{not} what you want to try out right now. Read through the rest of this chapter and check the Section~\ref{sec:Command-line-options}
to find out about \textbf{-P} and \textbf{-R} options.%
}:
\begin{bash}
asn1c %\emph{<modules.asn1>}%
asn1c %\emph{<modules.asn>}%
\end{bash}
If several ASN.1 modules contain interdependencies, all of the files
must be specified altogether:
\begin{bash}
asn1c %\emph{<module1.asn1> <module2.asn1> ...}%
asn1c %\emph{<module1.asn> <module2.asn> ...}%
\end{bash}
The compiler \textbf{-E} and \textbf{-EF} options are used for testing
the parser and the semantic fixer, respectively. These options will
...
...
@@ -175,7 +177,7 @@ is involved) ASN.1 specification as it was understood
by the compiler. It might be useful to check whether a particular
syntactic construct is properly supported by the compiler.
\begin{bash}
asn1c %\textbf{-EF} \emph{<module-to-test.asn1>}%
asn1c %\textbf{-EF} \emph{<module-to-test.asn>}%
\end{bash}
The \textbf{-P} option is used to dump the compiled output on the
screen instead of creating a bunch of .c and .h files on disk in the
...
...
@@ -187,36 +189,40 @@ files.
Print the compiled output instead of creating multiple source files:
The \cmd{asn1c} compiler produces a number of files:
\begin{itemize}
\item A set of .c and .h files for each type defined
in the ASN.1 specification. These files will be named similarly to
the ASN.1 types (\emph{Rectangle.c} and \emph{Rectangle.h} for the
RectangleTest ASN.1 module defined in the beginning of this document).
the ASN.1 types (\textbf{Rectangle.c} and \textbf{Rectangle.h} for the
RectangleModule ASN.1 module defined in the beginning of this document).
\item A set of helper .c and .h files which contain the generic encoders,
decoders and other useful routines. There will be quite a few of them, some
decoders and other useful routines.
Sometimes they are referred to by the term \emph{skeletons}.
There will be quite a few of them, some
of them are not even always necessary, but the overall amount of code
after compilation will be rather small anyway.
\item A \emph{converter-example.c} file containing the \emph{int main()} function with a fully functioning decoder. It can convert a given PDU between BER, XER and possibly OER and PER (if -gen-OER or -gen-PER options to asn1c were in effect). At some point you will want to replace this file with your own file containing the \emph{int main()} function.
\item A \emph{Makefile.am.libasncodecs} file mentioning all the files created
at the earlier steps. The accompanying \emph{Makefile.am.example} file is
suitable for either automake suite or the plain `make` utility.
Just rename it into \emph{Makefile}.
\item A \textbf{Makefile.am.libasncodecs} file which explicitly lists all the
generated files.
This makefile can be used on its own to build the just the codec library.
\item A \textbf{converter-example.c} file containing the \emph{int main()} function with a fully functioning encoder and data format converter. It can convert a given PDU between BER, XER and possibly OER and PER (if \cmd{-gen-OER} or \cmd{-gen-PER} options to \cmd{asn1c} were in effect). At some point you will want to replace this file with your own file containing the \emph{int main()} function.
\item A \textbf{Makefile.am.example} file which binds together
\textbf{Makefile.am.libasncodecs} and \textbf{converter-example.c}
to build a versatile converter and debugger for your data formats.
\end{itemize}
It is possible to compile everything with just a couple of instructions:
\begin{bash}
asn1c -pdu=%\emph{Rectangle}% *.asn1
make -f Makefile.am.example # If you use `make`
asn1c -pdu=%\emph{Rectangle}% *.asn
make -f Makefile.am.example # If you use `make`
\end{bash}
or
\begin{bash}
asn1c *.asn1
asn1c *.asn
cc -I. -DPDU=%\emph{Rectangle}% -o rectangle.exe *.c # ... or like this
\end{bash}
Refer to the Chapter \ref{cha:Step-by-step-examples} for a sample
...
...
@@ -226,7 +232,7 @@ with the supplied \emph{converter-example.c}.
\clearpage{}
\section{\label{sec:Command-line-options}Command line options}
The following table summarizes the asn1c command line options.
The following table summarizes the \cmd{asn1c} command line options.
\renewcommand{\arraystretch}{1.33}
\begin{longtable}{lp{4in}}
...
...
@@ -278,7 +284,8 @@ may produce a shorter executable.}\\
In case of \texttt{-pdu=\textbf{all}}, all ASN.1 types defined in all modules wil form a PDU table. In case of \texttt{-pdu=\textbf{auto}}, all types not referenced by any other type will form a PDU table. If \texttt{\emph{Type}} is an ASN.1 type identifier, it is added to a PDU table. The last form may be specified multiple times.}\\\\
\textbf{Output Options}&\textbf{Description}\\
\midrule
{\ttfamily -print-constraints}&{\small When \texttt{-EF} are also specified, this option forces the compiler
{\ttfamily -print-class-matrix}&{\small When \texttt{-EF} options are given, this option instructs the compiler to print out the collected Information Object Class matrix.}\\
{\ttfamily -print-constraints}&{\small With \texttt{-EF}, this option instructs the compiler
to explain its internal understanding of subtype constraints.}\\
This code defines a \emph{rect} pointer which points to the Rectangle\_t
structure which needs to be freed. The second line uses the generic
ASN\_STRUCT\_FREE() macro which invokes the memory deallocation routine
structure which needs to be freed. The second line uses a generic
\code{ASN\_STRUCT\_FREE()} macro which invokes the memory deallocation routine
created specifically for this Rectangle\_t structure.
The \emph{asn\_DEF\_Rectangle} is the type descriptor which holds
a collection of routines and operations defined for the Rectangle\_t structure.
...
...
@@ -354,14 +360,14 @@ to be useful for debugging or quick-n-dirty printing. See Section~\ref{sub:Print
structure. See Section~\ref{sub:Freeing-the-target}.
\end{description}
Each of the above function takes the type descriptor (\emph{asn\_DEF\_\ldots{}})
and the target structure (\emph{rect}, in the above example).
and the target structure (\emph{rect}, as in the example above).
\subsection{\label{sub:Generic-Encoding}Generic encoders and decoders}
Before we start describing specific encoders and decoders, let's step back
a little and check out a simple high level way.
The asn1c runtime supplies (see asn\_application.h) two sets of high level functions, \emph{asn\_encode*} and \emph{asn\_decode*}, which take a transfer syntax selector as the argument. The transfer syntax selector is defined as this:
The asn1c runtime supplies (see \emph{asn\_application.h}) two sets of high level functions, \emph{asn\_encode*} and \emph{asn\_decode*}, which take a transfer syntax selector as the argument. The transfer syntax selector is defined as this: