asn1ct
ASN.1 compiler and compile-time support functions
The ASN.1 compiler takes an ASN.1 module as input and generates a corresponding Erlang module which can encode and decode the data-types 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).
Note!
By default in OTP 17, the representation of the BIT STRING and OCTET STRING types as Erlang terms have changed. BIT STRING values are now Erlang bitstrings and OCTET STRING values are binaries. For details see BIT STRING and OCTET STRING in User's Guide.
To revert to the old representation of the types, use the
legacy_erlang_types
option.
Note!
In R16, the options have been simplified. The back-end is chosen
using one of the options ber
, per
, or uper
.
The options optimize
, nif
, and driver
options
are no longer necessary (and the ASN.1 compiler will print a
warning if they are used). The options ber_bin
, per_bin
,
and uper_bin
options will still work, but will print a warning.
Another change in R16 is that the generated encode/2
function always returns a binary.
The encode/2
function for the BER back-end used to return
an iolist.
Functions
compile(Asn1module) -> ok | {error, Reason}
compile(Asn1module, Options) -> ok | {error, Reason}
Asn1module = atom() | string()
Options = [Option| OldOption]
Option = ber | per | uper | der | compact_bit_string | legacy_bit_string | legacy_erlang_types | noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | undec_rest | no_ok_wrapper | {macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors
OldOption = ber | per
Reason = term()
Prefix = string()
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 quotation 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.erl 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 separately.
Another unwanted effect that may occur 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 occurred 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 | per | uper
The encoding rule to be used. The supported encoding rules
are BER (Basic Encoding Rules),
PER aligned (Packed Encoding Rules) and PER unaligned.
If the encoding rule option is omitted ber
is the default.
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.
der
By this option the Distinguished Encoding Rules (DER) is chosen.
DER is regarded as a specialized variant of the BER encoding
rule, therefore the der
option only makes sense together
with the ber
option.
This option
sometimes adds sorting and value checks when encoding, which
implies a slower encoding. The decoding routines are the same
as for ber
.
compact_bit_string
The BIT STRING type will be decoded to the "compact notation". This option is not recommended for new code.
For details see BIT STRING type section in the Users Guide .
This option implies the legacy_erlang_types
option.
legacy_bit_string
The BIT STRING type will be decoded to the legacy format, i.e. a list of zeroes and ones. This option is not recommended for new code.
For details see BIT STRING type section in the Users Guide .
This option implies the legacy_erlang_types
option.
legacy_erlang_types
Use the same Erlang types to represent BIT STRING and OCTET STRING as in R16. For details see BIT STRING and OCTET STRING in User's Guide.
This option is not recommended for new code.
{n2n, EnumTypeName}
Tells the compiler to generate functions for conversion between
names (as atoms) and numbers and vice versa for the EnumTypeName specified. There can be multiple occurrences of this option in order to specify several type names. The type names must be declared as ENUMERATIONS in the ASN.1 spec.
If the EnumTypeName does not exist in the ASN.1 spec the
compilation will stop with an error code.
The generated conversion functions are named
name2num_EnumTypeName/1
and
num2name_EnumTypeName/1
.
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.
{i, IncludeDir}
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.
{outdir, Dir}
Specifies the directory Dir
where all generated files
shall be placed. If omitted the files are placed in the
current directory.
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.
The instructions for exclusive decode must follow the instruction and grammar in the User's Guide.
You can also find the instructions for selective decode in the User's Guide.
undec_rest
A buffer that holds a message, being 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.
no_ok_wrapper
If this option is given, the generated encode/2
and decode/2
functions will not wrap a successful
return value in an {ok,...}
tuple. If any error
occurs, there will be an exception.
{macro_name_prefix, Prefix}
All macro names generated by the compiler are prefixed with
Prefix
. This is useful when multiple protocols that contains
macros with identical names are included in a single module.
{record_name_prefix, Prefix}
All record names generated by the compiler are prefixed with
Prefix
. This is useful when multiple protocols that contains
records with identical names are included in a single module.
verbose
Causes more verbose information from the compiler describing what it is doing.
warnings_as_errors
Causes warnings to be treated as errors.
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 = binary()
Reason = term()
Encodes Value
of Type
defined in the ASN.1 module
Module
. 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 occurred.
This function is deprecated.
Use Module:encode(Type, Value)
instead.
decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason}
Module = Type = atom()
Value = Reason = term()
Bytes = binary()
Decodes Type
from Module
from the binary
Bytes
. Returns {ok, Value}
if successful.
This function is deprecated.
Use Module:decode(Type, Bytes)
instead.
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 | Options) -> ok | {error, Reason}
test(Module, Type, Value | Options) -> ok | {error, Reason}
Module = Type = atom()
Value = term()
Options = [{i, IncludeDir}]
Reason = term()
Performs a test of encode and decode of 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 inModule
. -
test/2
tests typeType
with a random value. -
test/3
tests typeType
withValue
.
Schematically the following happens for each type in the module:
{ok, Value} = asn1ct:value(Module, Type), {ok, Bytes} = asn1ct:encode(Module, Type, Value), {ok, Value} = asn1ct:decode(Module, Type, Bytes).
The test
functions utilizes the *.asn1db
files
for all included modules. If they are located in a different
directory than the current working directory, use the include
option to add paths. This is only needed when automatically
generating values. For static values using Value
no
options are needed.