Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
asn1ct - ASN.1 compiler and compile-time support functions
DESCRIPTION
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:
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 (and asn1rt:encode/3) always
returns a binary. The encode/2 function for the BER back-end used to return an iolist.
EXPORTS
compile(Asn1module) -> ok | {error, Reason}
compile(Asn1module, Options) -> ok | {error, Reason}
Types:
Asn1module = atom() | string()
Options = [Option| OldOption]
Option = ber | per | uper | der | compact_bit_string | legacy_bit_string | 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 .
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 .
{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}
Types:
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.
decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason}
Types:
Module = Type = atom()
Value = Reason = term()
Bytes = binary()
Decodes Type from Module from the binary Bytes. Returns {ok, Value} if successful.
value(Module, Type) -> {ok, Value} | {error, Reason}
Types:
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}
Types:
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 in Module.
* test/2 tests type Type with a random value.
* test/3 tests type Type with Value.
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.