asn1ct

ASN.1 compiler and compile-time support functions

The ASN.1 compiler takes an ASN.1 module as input and genarates a
corresponding Erlang module which can encode and decode the datatypes
specified. Alternatively the compiler takes a specification module
(se below) specifying all input modules and generates one module with
encode/decode functions. There are also some generic functions which
can be used in during development of applications which handles ASN.1
data (encoded as BER or PER).

Compiles the ASN.1 module Asn1module and generates an
Erlang module Asn1module.erl with encode and decode
functions for the types defined in Asn1module. For each
ASN.1 value defined in the module an Erlang function which
returns the value in Erlang representation is generated.

If Asn1module is a filename without extension first
".asn1" is assumed, then ".asn" and finally
".py" (to be compatible with the old ASN.1 compiler).
Of course Asn1module can be a full pathname (relative or
absolute) including filename with (or without) extension.

If one wishes to compile a set of Asn1 modules into one
Erlang file with encode/decode functions one has to list all
involved files in a configuration file. This configuration
file must have a double extension ".set.asn", (".asn" can
alternatively be ".asn1" or ".py"). The input files' names
must be listed, within qoutation marks (""), one at each row
in the file. If the input files are File1.asn,
File2.asn and File3.asn the configuration file
shall look like:

File1.asn
File2.asn
File3.asn

The output files will in this case get their names from the
configuration file. If the configuration file has the name
SetOfFiles.set.asn the name of the output files will be
SetOfFiles.hrl, SetOfFiles.hrl and SetOfFiles.asn1db.

Sometimes in a system of ASN.1 modules there are different
default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The
multi file compilation resolves the default tagging as if
the modules were compiled separetely.

Another unwanted effect that may occure in multi file compilation
is name collisions. The compiler solves this problem in two
ways: If the definitions are identical then the output module
keeps only one definition with the original name. But if
definitions only have same name and differs in the definition,
then they will be renamed. The new names will be the definition
name and the original module name concatenated.

If any name collision have occured the compiler reports a
"NOTICE: ..." message that tells if a definition was renamed,
and the new name that must be used to encode/decode data.

Options is a list with options specific for the asn1
compiler and options that are applied to the Erlang compiler.
The latter are those that not is recognized as asn1 specific.
Available options are:

ber | ber_bin | per | per_bin | uper_bin

The encoding rule to be used. EncodingRule is BER or
PER with the variants aligned or
unaligned. If this option is omitted ber is
the default. The per option means the aligned
variant. To use the unaligned variant the uper_bin
option has to be used.

The generated Erlang module always gets the same name
as the ASN.1 module and as a consequence of this only one
encoding rule per ASN.1 module can be used at runtime.

The ber_bin and per_bin options are
equivalent with the ber and per options with
the difference that the generated encoding/decoding
functions take advantage of the bit syntax, which in most
cases increases the performance considerably. The result
from encoding is a binary or a list (mayby nested) with
Erlang terms, including binaries.

der

By this option the Distinguished Encoding Rule (DER) is chosed.
DER is regarded as a specialized variant of the BER encoding
rule, therefore the der option only makes sense when
the ber or ber_bin option is used. This option
sometimes adds sorting and value checks when encoding, which
implies a slower encoding. The decoding rutines are the same
as for ber.

compact_bit_string

Makes it possible to use a compact notation for values
of the BIT STRING type in Erlang. The notation:

Adds IncludeDir to the search-path for
.asn1db and asn1 source files. The compiler tries
to open a .asn1db file when a module imports
definitions from another ASN.1 module. If no
.asn1db file is found the asn1 source file is
parsed. Several {i,IncludeDir} can be given.

noobj

Do not compile (i.e do not produce object code) the generated
.erl file. If this option is omitted the generated Erlang module
will be compiled.

{outdir,Dir}

Specifies the directory Dir where all generated files
shall be placed. If omitted the files are placed in the
current directory.

optimize

This option is only valid together with one of the
per_bin
or ber_bin option. It gives time optimized code
generated and it uses another runtime module and
in the per_bin case a linked-in driver. The result
in the per_bin case from an encode when compiled
with this option will be a binary.

driver

Option valid together with ber_bin and optimize
options. It enables the use of a linked-in driver that gives
considerable faster decode. In ber_bin the driver is
enabled only by explicit use of the option driver.

asn1config

When one of the specialized decodes, exclusive or
selective decode, is wanted one has to give instructions in
a configuration file. The option asn1config enables
specialized decodes and takes the configuration file, which
has the same name as the ASN.1 spec but with extension
.asn1config, in concern.

You can also find the instructions for selective decode
in the
User's Guide.

undec_rest

A buffer that holds a message, beeing decoded may
also have some following bytes. Now it is possible to get
those following bytes returned together with the decoded
value. If an asn1 spec is compiled with this option a tuple
{ok,Value,Rest} is returned. Rest may be a
list or a binary. Earlier versions of the compiler ignored
those following bytes.

{inline,OutputName}

Compiling with this option gives one output module
containing all asn1 run-time functionality. The asn1 specs
are provided in a target module Module.set.asn as described
above. The name of the
resulting module containing generated encode/decode functions
and inlined run-time functions will be
OutputName.erl. The merging/inlining of code is done
by the igor module of syntax_tools. By default
the functions generated from the first asn1 spec in the
.set.asn are exported, unless a
{export,[atom()]} or {export_all,true} option
are provided. The list of atoms are names of choosen asn1
specs from the .set.asn file.

inline

It is also possible to use the sole argument inline.
It is as {inline,OutputName}, but the output file gets the
default name of the source .set.asn file.

Any additional option that is applied will be passed to
the final step when the generated .erl file is compiled.

The compiler generates the following files:

Asn1module.hrl (if any SET or SEQUENCE is defined)

Asn1module.erl the Erlang module with encode, decode and value functions.

Asn1module.asn1db intermediate format used by the compiler when modules IMPORTS
definitions from each other.

encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}

Module = Type = atom()

Value = term()

Bytes = [Int] when integer(Int), Int >= 0, Int =< 255

Reason = term()

Encodes Value of Type defined in the ASN.1 module
Module. Returns a list of bytes if successful. To get as fast execution as
possible the
encode function only performs rudimentary tests that the input
Value
is a correct instance of Type. The length of strings is for example
not always checked. Returns {ok,Bytes} if successful or
{error,Reason} if an error occured.

decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}

Module = Type = atom()

Value = Reason = term()

Bytes = [Int] when integer(Int), Int >= 0, Int =< 255

Decodes Type from Module from the list of bytes
Bytes. Returns {ok,Value} if successful.

validate(Module,Type,Value) -> ok | {error,Reason}

Module = Type = atom()

Value = term()

Validates that Value conforms to Type
from Module. Not implemented in this version of the ASN.1 application.

value(Module ,Type) -> {ok,Value} | {error,Reason}

Module = Type = atom()

Value = term()

Reason = term()

Returns an Erlang term which is an example of a valid Erlang
representation of a value of the ASN.1 type Type. The value
is a random value and subsequent calls to this function will for most
types return different values.

test(Module) -> ok | {error,Reason}

test(Module,Type) -> ok | {error,Reason}

test(Module,Type,Value) -> ok | {error,Reason}

Performs a test of encode and decode of all types in Module.
The generated functions are called by this function.
This function is useful during test to secure that the generated
encode and decode functions and the general runtime support work
as expected. test/1 iterates over all types in Module. test/2 tests type Type with a random value. test/3 tests type <c>Type with Value.
Schematically the following happens for each type in the module.