.TH asn1ct 3erl "asn1 3.0.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
asn1ct \- ASN.1 compiler and compile-time support functions
.SH DESCRIPTION
.LP
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)\&.
.LP

.RS -4
.B
Note:
.RE
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\&. Also, an undecoded open type will now be wrapped in a \fIasn1_OPENTYPE\fR\& tuple\&. For details see \fBBIT STRING\fR\&, \fBOCTET STRING\fR\&, and \fBASN\&.1 Information Objects\fR\& in User\&'s Guide\&.
.LP
To revert to the old representation of the types, use the \fIlegacy_erlang_types\fR\& option\&.

.LP

.RS -4
.B
Note:
.RE
In R16, the options have been simplified\&. The back-end is chosen using one of the options \fIber\fR\&, \fIper\fR\&, or \fIuper\fR\&\&. The options \fIoptimize\fR\&, \fInif\fR\&, and \fIdriver\fR\& options are no longer necessary (and the ASN\&.1 compiler will print a warning if they are used)\&. The options \fIber_bin\fR\&, \fIper_bin\fR\&, and \fIuper_bin\fR\& options will still work, but will print a warning\&.
.LP
Another change in R16 is that the generated \fIencode/2\fR\& function always returns a binary\&. The \fIencode/2\fR\& function for the BER back-end used to return an iolist\&.

.SH EXPORTS
.LP
.B
compile(Asn1module) -> ok | {error, Reason}
.br
.B
compile(Asn1module, Options) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Asn1module = atom() | string()
.br
Options = [Option| OldOption]
.br
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
.br
OldOption = ber | per
.br
Reason = term()
.br
Prefix = string()
.br
.RE
.RE
.RS
.LP
Compiles the ASN\&.1 module \fIAsn1module\fR\& and generates an Erlang module \fIAsn1module\&.erl\fR\& with encode and decode functions for the types defined in \fIAsn1module\fR\&\&. For each ASN\&.1 value defined in the module an Erlang function which returns the value in Erlang representation is generated\&.
.LP
If \fIAsn1module\fR\& is a filename without extension first \fI"\&.asn1"\fR\& is assumed, then \fI"\&.asn"\fR\& and finally \fI"\&.py"\fR\& (to be compatible with the old ASN\&.1 compiler)\&. Of course \fIAsn1module\fR\& can be a full pathname (relative or absolute) including filename with (or without) extension\&. 
.LP
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 \fIFile1\&.asn\fR\&, \fIFile2\&.asn\fR\& and \fIFile3\&.asn\fR\& the configuration file shall look like:
.LP
.nf

File1.asn
File2.asn
File3.asn        
.fi
.LP
The output files will in this case get their names from the configuration file\&. If the configuration file has the name \fISetOfFiles\&.set\&.asn\fR\& the name of the output files will be \fISetOfFiles\&.hrl, SetOfFiles\&.erl and SetOfFiles\&.asn1db\fR\&\&.
.LP
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\&.
.LP
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\&.
.LP
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\&.
.LP
\fIOptions\fR\& 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:
.RS 2
.TP 2
.B
\fIber | per | uper\fR\&:
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 \fIber\fR\& is the default\&.
.RS 2
.LP
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\&.
.RE

.TP 2
.B
\fIder\fR\&:
By this option the Distinguished Encoding Rules (DER) is chosen\&. DER is regarded as a specialized variant of the BER encoding rule, therefore the \fIder\fR\& option only makes sense together with the \fIber\fR\& option\&. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding\&. The decoding routines are the same as for \fIber\fR\&\&.
.TP 2
.B
\fIcompact_bit_string\fR\&:
The BIT STRING type will be decoded to the "compact notation"\&. \fIThis option is not recommended for new code\&.\fR\& 
.RS 2
.LP
For details see \fB BIT STRING type section in the Users Guide \fR\&\&.
.RE

.RS 2
.LP
This option implies the \fIlegacy_erlang_types\fR\& option\&.
.RE

.TP 2
.B
\fIlegacy_bit_string\fR\&:
The BIT STRING type will be decoded to the legacy format, i\&.e\&. a list of zeroes and ones\&. \fIThis option is not recommended for new code\&.\fR\& 
.RS 2
.LP
For details see \fB BIT STRING type section in the Users Guide \fR\&\&. 
.LP
This option implies the \fIlegacy_erlang_types\fR\& option\&. 
.RE

.TP 2
.B
\fIlegacy_erlang_types\fR\&:
Use the same Erlang types to represent BIT STRING and OCTET STRING as in R16\&. For details see \fBBIT STRING\fR\& and \fBOCTET STRING\fR\& in User\&'s Guide\&.
.RS 2
.LP
\fIThis option is not recommended for new code\&.\fR\&
.RE

.TP 2
.B
\fI{n2n, EnumTypeName}\fR\&:
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 \fIname2num_EnumTypeName/1\fR\& and \fInum2name_EnumTypeName/1\fR\&\&.
.TP 2
.B
\fInoobj\fR\&:
Do not compile (i\&.e do not produce object code) the generated \fI\&.erl\fR\& file\&. If this option is omitted the generated Erlang module will be compiled\&.
.TP 2
.B
\fI{i, IncludeDir}\fR\&:
Adds \fIIncludeDir\fR\& to the search-path for \fI\&.asn1db\fR\& and asn1 source files\&. The compiler tries to open a \fI\&.asn1db\fR\& file when a module imports definitions from another ASN\&.1 module\&. If no \fI\&.asn1db\fR\& file is found the asn1 source file is parsed\&. Several \fI{i, IncludeDir}\fR\& can be given\&.
.TP 2
.B
\fI{outdir, Dir}\fR\&:
Specifies the directory \fIDir\fR\& where all generated files shall be placed\&. If omitted the files are placed in the current directory\&.
.TP 2
.B
\fIasn1config\fR\&:
When one of the specialized decodes, exclusive or selective decode, is wanted one has to give instructions in a configuration file\&. The option \fIasn1config\fR\& enables specialized decodes and takes the configuration file, which has the same name as the ASN\&.1 spec but with extension \fI\&.asn1config\fR\&, in concern\&.
.RS 2
.LP
The instructions for exclusive decode must follow the \fBinstruction and grammar in the User\&'s Guide\fR\&\&.
.RE

.RS 2
.LP
You can also find the instructions for selective decode in the \fBUser\&'s Guide\fR\&\&.
.RE

.TP 2
.B
\fIundec_rest\fR\&:
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 \fI{ok, Value, Rest}\fR\& is returned\&. \fIRest\fR\& may be a list or a binary\&. Earlier versions of the compiler ignored those following bytes\&.
.TP 2
.B
\fIno_ok_wrapper\fR\&:
If this option is given, the generated \fIencode/2\fR\& and \fIdecode/2\fR\& functions will not wrap a successful return value in an \fI{ok,\&.\&.\&.}\fR\& tuple\&. If any error occurs, there will be an exception\&.
.TP 2
.B
\fI{macro_name_prefix, Prefix}\fR\&:
All macro names generated by the compiler are prefixed with \fIPrefix\fR\&\&. This is useful when multiple protocols that contains macros with identical names are included in a single module\&.
.TP 2
.B
\fI{record_name_prefix, Prefix}\fR\&:
All record names generated by the compiler are prefixed with \fIPrefix\fR\&\&. This is useful when multiple protocols that contains records with identical names are included in a single module\&.
.TP 2
.B
\fIverbose\fR\&:
Causes more verbose information from the compiler describing what it is doing\&.
.TP 2
.B
\fIwarnings_as_errors\fR\&:
Causes warnings to be treated as errors\&.
.RE
.LP
Any additional option that is applied will be passed to the final step when the generated \&.erl file is compiled\&.
.LP
The compiler generates the following files:
.RS 2
.TP 2
*
\fIAsn1module\&.hrl\fR\& (if any SET or SEQUENCE is defined)
.LP
.TP 2
*
\fIAsn1module\&.erl\fR\& the Erlang module with encode, decode and value functions\&.
.LP
.TP 2
*
\fIAsn1module\&.asn1db\fR\& intermediate format used by the compiler when modules IMPORTS definitions from each other\&.
.LP
.RE

.RE

.LP
.B
encode(Module, Type, Value)-> {ok, Bytes} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Bytes = binary()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Encodes \fIValue\fR\& of \fIType\fR\& defined in the ASN\&.1 module \fIModule\fR\&\&. To get as fast execution as possible the encode function only performs rudimentary tests that the input \fIValue\fR\& is a correct instance of \fIType\fR\&\&. The length of strings is for example not always checked\&. Returns \fI{ok, Bytes}\fR\& if successful or \fI{error, Reason}\fR\& if an error occurred\&.
.LP
This function is deprecated\&. Use \fIModule:encode(Type, Value)\fR\& instead\&.
.RE

.LP
.B
decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = Reason = term()
.br
Bytes = binary()
.br
.RE
.RE
.RS
.LP
Decodes \fIType\fR\& from \fIModule\fR\& from the binary \fIBytes\fR\&\&. Returns \fI{ok, Value}\fR\& if successful\&.
.LP
This function is deprecated\&. Use \fIModule:decode(Type, Bytes)\fR\& instead\&.
.RE

.LP
.B
value(Module, Type) -> {ok, Value} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns an Erlang term which is an example of a valid Erlang representation of a value of the ASN\&.1 type \fIType\fR\&\&. The value is a random value and subsequent calls to this function will for most types return different values\&.
.RE

.LP
.B
test(Module) -> ok | {error, Reason}
.br
.B
test(Module, Type | Options) -> ok | {error, Reason}
.br
.B
test(Module, Type, Value | Options) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Options = [{i, IncludeDir}]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Performs a test of encode and decode of types in \fIModule\fR\&\&. 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\&.
.RS 2
.TP 2
*
\fItest/1\fR\& iterates over all types in \fIModule\fR\&\&.
.LP
.TP 2
*
\fItest/2\fR\& tests type \fIType\fR\& with a random value\&.
.LP
.TP 2
*
\fItest/3\fR\& tests type \fIType\fR\& with \fIValue\fR\&\&.
.LP
.RE

.LP
Schematically the following happens for each type in the module:
.LP
.nf

{ok, Value} = asn1ct:value(Module, Type),
{ok, Bytes} = asn1ct:encode(Module, Type, Value),
{ok, Value} = asn1ct:decode(Module, Type, Bytes).
.fi
.LP
The \fItest\fR\& functions utilizes the \fI*\&.asn1db\fR\& 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 \fIValue\fR\& no options are needed\&.
.RE