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).
compile(Asn1module) -> ok | {error,Reason}
compile(Asn1module , Options) -> ok | {error,Reason}
Asn1module = atom() | string()Options = [Option]Option = ber|per|ber_bin|per_bin|der|compact_bit_string|noobj|
{outdir,Dir}|{i,IncludeDir}Reason = term()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.
Options is a list with
some of
the following available options:
ber | ber_bin | per | per_binber is the
default. The per option means the aligned variant,
the unaligned variant of PER is not supported in this
version of the compiler.
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.
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 list (mayby
nested) with Erlang terms, including binaries. Note that the
erlang virtual machine that will execute the generated code
must be of version R7 or higher.
derder 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_stringBitString = {Unused,Binary},
Unused = integer(),
Binary = binary()
Unused must be a number in the range 0 to 7. It
tells how many bits in the least significant byte in
Binary that is unused. For details see BIT STRING type section
in users guide.
{i,IncludeDir}IncludeDir to the search-path for .asn1db
files. The compiler tries to open a .asn1db file when a
module imports definitions from another ASN.1 module.
Several {i,IncludeDir} can be given.
noobj.erl file. If this option is omitted the generated Erlang module
will be compiled.
{out_dir,Dir}Dir where all generated files
shall be placed. If omitted the files are placed in the
current directory.
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 =< 255Reason = 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 =< 255Decodes 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.
start(IncludePaths) -> ok | already_started
IncludePaths = [IncludeDirectory]IncludeDirectory = string()Starts the ASN.1 database server and initiates it with IncludePaths.
IncludePaths is a list of directories where the data base server
should search for
.asn1db files when a new module should be loaded into the database.
Stops the ASN.1 database server. The database server is only used by the compile-time functions.
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.
{ok,Value} = asn1ct:value(Module,Type),
{ok,Bytes} = asn1ct:encode(Module,Type,Value),
{ok,Value} = asn1:decode(Module,Type,Bytes).