asn1ct(3erl) Erlang Module Definition asn1ct(3erl)
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 cor-
responding Erlang module, which can encode and decode the specified
data types. Alternatively, the compiler takes a specification module
specifying all input modules, and generates a module with encode/decode
functions. In addition, some generic functions can be used during de-
velopment of applications that 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 were changed. BIT STRING values are now
Erlang bit strings and OCTET STRING values are binaries. Also, an unde-
coded open type is now wrapped in an asn1_OPENTYPE tuple. For details,
see BIT STRING, OCTET STRING, and ASN.1 Information Objects in the
User's Guide.
To revert to the old representation of the types, use option legacy_er-
lang_types.
Note:
In OTP R16, the options were simplified. The back end is chosen using
one of the options ber, per, uper or jer. Options optimize, nif, and
driver options are no longer necessary (and the ASN.1 compiler gener-
ates a warning if they are used). Options ber_bin, per_bin, and
uper_bin options still work, but generates a warning.
Another change in OTP R16 is that the generated function encode/2 al-
ways returns a binary. Function encode/2 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 | jer | der | compact_bit_string |
legacy_bit_string | legacy_erlang_types | noobj | {n2n, Enum-
TypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | un-
dec_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 that returns the value in Erlang rep-
resentation 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). Asn1module can be a full pathname (rel-
ative or absolute) including filename with (or without) exten-
sion.
If it is needed to compile a set of ASN.1 modules into an Erlang
file with encode/decode functions, ensure 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"). List the input file names 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 must
look as follows:
File1.asn
File2.asn
File3.asn
The output files in this case get their names from the configu-
ration file. If the configuration file is named SetOf-
Files.set.asn, the names of the output files are SetOfFiles.hrl,
SetOfFiles.erl, and SetOfFiles.asn1db.
Sometimes in a system of ASN.1 modules, different default tag
modes, for example, AUTOMATIC, IMPLICIT, or EXPLICIT. The multi-
file compilation resolves the default tagging as if the modules
were compiled separately.
Name collisions is another unwanted effect that can occur in
multi file-compilation. The compiler solves this problem in one
of two ways:
* If the definitions are identical, the output module keeps
only one definition with the original name.
* If the definitions have the same name and differs in the
definition, they are renamed. The new names are the defini-
tion name and the original module name concatenated.
If a name collision occurs, 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 ASN.1 compiler
and options that are applied to the Erlang compiler. The latter
are not recognized as ASN.1 specific. The available options are
as follows:
ber | per | uper | jer:
The encoding rule to be used. The supported encoding rules
are Basic Encoding Rules (ber), Packed Encoding Rules (per)
aligned, PER unaligned (uper) and JSON Encoding Rules (jer).
The jer option can be used by itself to generate a module
that only supports encoding/decoding to JER or it can be
used as a supplementary option to ber, per and uper. In the
latter case a module with for both the main encoding rules
and JER will be generated. The exported functions for JER
will then be jer_encode(Type, Value) and jer_decode(Type,
Bytes).
The jer encoding rules (ITU-T X.697) are experimental in OTP
22. There is support for a subset of the X.697 standard, for
example there is no support for:
* JER encoding instructions
* the REAL type
Also note that when using the jer encoding rules the gener-
ated module will get a dependency to an external json compo-
nent. The generated code is currently tested together with:
* jsx which currently is the default.
* jsone can be chosen instead of jsx by providing the option
{d,jsone}.
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. Therefore, only one encoding rule per ASN.1
module can be used at runtime.
der:
With this option the Distinguished Encoding Rules (der) is
chosen. DER is regarded as a specialized variant of the BER
encoding rule. Therefore, this option only makes sense to-
gether with option ber. This option sometimes adds sorting
and value checks when encoding, which implies a slower en-
coding. The decoding routines are the same as for ber.
maps:
This option changes the representation of the types SEQUENCE
and SET to use maps (instead of records). This option also
suppresses the generation of .hrl files.
For details, see Section Map representation for SEQUENCE
and SET in the User's Guide.
compact_bit_string:
The BIT STRING type is decoded to "compact notation". This
option is not recommended for new code. This option cannot
be combined with the option maps.
For details, see Section BIT STRING in the User's Guide.
This option implies option legacy_erlang_types.
legacy_bit_string:
The BIT STRING type is decoded to the legacy format, that
is, a list of zeroes and ones. This option is not recom-
mended for new code. This option cannot be combined with the
option maps.
For details, see Section BIT STRING in the User's Guide
This option implies option legacy_erlang_types.
legacy_erlang_types:
Use the same Erlang types to represent BIT STRING and OCTET
STRING as in OTP R16.
For details, see Section BIT STRING and Section OCTET STRING
in the User's Guide.
This option is not recommended for new code. This option
cannot be combined with the option maps.
{n2n, EnumTypeName}:
Tells the compiler to generate functions for conversion be-
tween names (as atoms) and numbers and conversely for the
specified EnumTypeName. There can be multiple occurrences of
this option to specify several type names. The type names
must be declared as ENUMERATIONS in the ASN.1 specification.
If EnumTypeName does not exist in the ASN.1 specification,
the compilation stops with an error code.
The generated conversion functions are named name2num_Enum-
TypeName/1 and num2name_EnumTypeName/1.
noobj:
Do not compile (that is, do not produce object code) the
generated .erl file. If this option is omitted, the gener-
ated Erlang module is compiled.
{i, IncludeDir}:
Adds IncludeDir to the search-path for .asn1db and ASN.1
source files. The compiler tries to open an .asn1db file
when a module imports definitions from another ASN.1 module.
If no .asn1db file is found, the ASN.1 source file is
parsed. Several {i, IncludeDir} can be given.
{outdir, Dir}:
Specifies directory Dir where all generated files are to be
placed. If this option is omitted, the files are placed in
the current directory.
asn1config:
When using one of the specialized decodes, exclusive or se-
lective decode, instructions must be given in a configura-
tion file. Option asn1config enables specialized decodes and
takes the configuration file in concern. The configuration
file has the same name as the ASN.1 specification, but with
extension .asn1config.
For instructions for exclusive decode, see Section Exclusive
Decode in the User's Guide.
For instructions for selective decode, see Section Selective
Decode in the User's Guide.
undec_rest:
A buffer that holds a message, being decoded it can also
have some following bytes. Those following bytes can now be
returned together with the decoded value. If an ASN.1 speci-
fication is compiled with this option, a tuple {ok, Value,
Rest} is returned. Rest can be a list or a binary. Earlier
versions of the compiler ignored those following bytes.
no_ok_wrapper:
With this option, the generated encode/2 and decode/2 func-
tions do not wrap a successful return value in an {ok,...}
tuple. If any error occurs, an exception will be raised.
{macro_name_prefix, Prefix}:
All macro names generated by the compiler are prefixed with
Prefix. This is useful when multiple protocols that contain
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 contain
records with identical names are included in a single mod-
ule.
verbose:
Causes more verbose information from the compiler describing
what it is doing.
warnings_as_errors:
Causes warnings to be treated as errors.
Any more option that is applied is 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 - Erlang module with encode, decode, and
value functions
* Asn1module.asn1db - Intermediate format used by the compiler
when modules IMPORT definitions from each other.
value(Module, Type) -> {ok, Value} | {error, Reason}
Types:
Module = Type = atom()
Value = term()
Reason = term()
Returns an Erlang term that is an example of a valid Erlang rep-
resentation 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.
Note:
Currently, the value function has many limitations. Essentially,
it will mostly work for old specifications based on the 1997
standard for ASN.1, but not for most modern-style applications.
Another limitation is that the value function may not work if
options that change code generations strategies such as the op-
tions macro_name_prefix and record_name_prefix have been used.
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 as well as the general runtime support work as
expected.
Note:
Currently, the test functions have many limitations. Essen-
tially, they will mostly work for old specifications based on
the 1997 standard for ASN.1, but not for most modern-style ap-
plications. Another limitation is that the test functions may
not work if options that change code generations strategies such
as the options macro_name_prefix and record_name_prefix have
been used.
* 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 occurs for each type in the module:
{ok, Value} = asn1ct:value(Module, Type),
{ok, Bytes} = Module:encode(Type, Value),
{ok, Value} = Module:decode(Type, Bytes).
The test functions use the *.asn1db files for all included mod-
ules. If they are located in a different directory than the cur-
rent 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.
Ericsson AB asn1 5.0.13 asn1ct(3erl)