It would also create the code for converting this structure into platform-independent
The asn1c compiler also creates the code for converting this structure into
wire representation (a serializer API) and the decoder of such wire
platform-independent wire representation and the decoder
representation back into local, machine-specific type (a deserializer
of such wire representation back into local, machine-specific type.
API).
These encoders and decoders are also called serializers and deserializers,
marshallers and unmarshallers, or codecs.
\section{Quick start with asn1c}
\section{Quick start with asn1c}
After building and installing the compiler, the \emph{asn1c}
After building and installing the compiler, the \cmd{asn1c}
command may be used to compile the ASN.1 modules%
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}
\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.%
to find out about \textbf{-P} and \textbf{-R} options.%
}:
}:
\begin{bash}
\begin{bash}
asn1c %\emph{<modules.asn1>}%
asn1c %\emph{<modules.asn>}%
\end{bash}
\end{bash}
If several ASN.1 modules contain interdependencies, all of the files
If several ASN.1 modules contain interdependencies, all of the files
must be specified altogether:
must be specified altogether:
\begin{bash}
\begin{bash}
asn1c %\emph{<module1.asn1> <module2.asn1> ...}%
asn1c %\emph{<module1.asn> <module2.asn> ...}%
\end{bash}
\end{bash}
The compiler \textbf{-E} and \textbf{-EF} options are used for testing
The compiler \textbf{-E} and \textbf{-EF} options are used for testing
the parser and the semantic fixer, respectively. These options will
the parser and the semantic fixer, respectively. These options will
...
@@ -175,7 +177,7 @@ is involved) ASN.1 specification as it was understood
...
@@ -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
by the compiler. It might be useful to check whether a particular
syntactic construct is properly supported by the compiler.
syntactic construct is properly supported by the compiler.
\begin{bash}
\begin{bash}
asn1c %\textbf{-EF} \emph{<module-to-test.asn1>}%
asn1c %\textbf{-EF} \emph{<module-to-test.asn>}%
\end{bash}
\end{bash}
The \textbf{-P} option is used to dump the compiled output on the
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
screen instead of creating a bunch of .c and .h files on disk in the
...
@@ -187,36 +189,40 @@ files.
...
@@ -187,36 +189,40 @@ files.
Print the compiled output instead of creating multiple source files:
Print the compiled output instead of creating multiple source files:
The \cmd{asn1c} compiler produces a number of files:
\begin{itemize}
\begin{itemize}
\item A set of .c and .h files for each type defined
\item A set of .c and .h files for each type defined
in the ASN.1 specification. These files will be named similarly to
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
the ASN.1 types (\textbf{Rectangle.c} and \textbf{Rectangle.h} for the
RectangleTest ASN.1 module defined in the beginning of this document).
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,
\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
of them are not even always necessary, but the overall amount of code
after compilation will be rather small anyway.
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 \textbf{Makefile.am.libasncodecs} file which explicitly lists all the
\item A \emph{Makefile.am.libasncodecs} file mentioning all the files created
generated files.
at the earlier steps. The accompanying \emph{Makefile.am.example} file is
This makefile can be used on its own to build the just the codec library.
suitable for either automake suite or the plain `make` utility.
\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.
Just rename it into \emph{Makefile}.
\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}
\end{itemize}
It is possible to compile everything with just a couple of instructions:
It is possible to compile everything with just a couple of instructions:
\begin{bash}
\begin{bash}
asn1c -pdu=%\emph{Rectangle}% *.asn1
asn1c -pdu=%\emph{Rectangle}% *.asn
make -f Makefile.am.example # If you use `make`
make -f Makefile.am.example # If you use `make`
\end{bash}
\end{bash}
or
or
\begin{bash}
\begin{bash}
asn1c *.asn1
asn1c *.asn
cc -I. -DPDU=%\emph{Rectangle}% -o rectangle.exe *.c # ... or like this
cc -I. -DPDU=%\emph{Rectangle}% -o rectangle.exe *.c # ... or like this
\end{bash}
\end{bash}
Refer to the Chapter \ref{cha:Step-by-step-examples} for a sample
Refer to the Chapter \ref{cha:Step-by-step-examples} for a sample
...
@@ -226,7 +232,7 @@ with the supplied \emph{converter-example.c}.
...
@@ -226,7 +232,7 @@ with the supplied \emph{converter-example.c}.
\clearpage{}
\clearpage{}
\section{\label{sec:Command-line-options}Command line options}
\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}
\renewcommand{\arraystretch}{1.33}
\begin{longtable}{lp{4in}}
\begin{longtable}{lp{4in}}
...
@@ -278,7 +284,8 @@ may produce a shorter executable.}\\
...
@@ -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.}\\\\
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}\\
\textbf{Output Options}&\textbf{Description}\\
\midrule
\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.}\\
to explain its internal understanding of subtype constraints.}\\
This code defines a \emph{rect} pointer which points to the Rectangle\_t
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
structure which needs to be freed. The second line uses a generic
ASN\_STRUCT\_FREE() macro which invokes the memory deallocation routine
\code{ASN\_STRUCT\_FREE()} macro which invokes the memory deallocation routine
created specifically for this Rectangle\_t structure.
created specifically for this Rectangle\_t structure.
The \emph{asn\_DEF\_Rectangle} is the type descriptor which holds
The \emph{asn\_DEF\_Rectangle} is the type descriptor which holds
a collection of routines and operations defined for the Rectangle\_t structure.
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
...
@@ -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}.
structure. See Section~\ref{sub:Freeing-the-target}.
\end{description}
\end{description}
Each of the above function takes the type descriptor (\emph{asn\_DEF\_\ldots{}})
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}
\subsection{\label{sub:Generic-Encoding}Generic encoders and decoders}
Before we start describing specific encoders and decoders, let's step back
Before we start describing specific encoders and decoders, let's step back
a little and check out a simple high level way.
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: