asn1ct

MODULE

asn1ct

MODULE SUMMARY

ASN.1 compiler and compile-time support functions

DESCRIPTION

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. 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).

EXPORTS

compile(Asn1module) -> ok | {error,Reason}
compile(Asn1module , Options) -> ok | {error,Reason}

Types:
Asn1module = atom() | string()
Options = [Option]
Option = ber|per|noobj|{outdir,Dir}|{i,IncludeDir}
Reason = term()

Compiles the ASN.1 module Asn1module and generates an Erlang module Asn1module.erl with encode 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 ".asn" is assumed and then ".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.

Options is a list with some of the following available options:

ber | per

The encoding rule to be used. EncodingRule is ber or per. If this option is omitted ber 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 consequnce of this only one encoding rule per ASN.1 module can be used at runtime.


{i,IncludeDir}

Adds 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

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.


{out_dir,Dir}

Specifies the directory 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}
encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}

Types:
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}

Types:
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}
validate(Module,Type,Value) -> ok | {error,Reason}

Types:
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

Types:
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.

stop() -> void

Stops the ASN.1 database server. The database server is only used by the compile-time functions.

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) -> 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). 

AUTHORS

Kenneth Lundin - support@erlang.ericsson.se