<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. </legalnotice> <title>asn1ct</title> <prepared>Kenneth Lundin</prepared> <responsible>Kenneth Lundin</responsible> <docno>1</docno> <approved>Kenneth Lundin</approved> <checked></checked> <date>97-10-14</date> <rev>A</rev> <file>asn1.sgml</file> </header> <module>asn1ct</module> <modulesummary>ASN.1 compiler and compile-time support functions</modulesummary> <description> <p>The ASN.1 compiler takes an ASN.1 module as input and generates a corresponding 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 development of applications that handles ASN.1 data (encoded as <c>BER</c> or <c>PER</c>).</p> <note> <p>By default in OTP 17, the representation of the <c>BIT STRING</c> and <c>OCTET STRING</c> types as Erlang terms were changed. <c>BIT STRING</c> values are now Erlang bit strings and <c>OCTET STRING</c> values are binaries. Also, an undecoded open type is now wrapped in an <c>asn1_OPENTYPE</c> tuple. For details, see <seealso marker="asn1_getting_started#BIT STRING">BIT STRING</seealso>, <seealso marker="asn1_getting_started#OCTET STRING">OCTET STRING</seealso>, and <seealso marker="asn1_getting_started#Information Object">ASN.1 Information Objects</seealso> in the User's Guide.</p> <p>To revert to the old representation of the types, use option <c>legacy_erlang_types</c>.</p> </note> <note> <p>In OTP R16, the options were simplified. The back end is chosen using one of the options <c>ber</c>, <c>per</c>, or <c>uper</c>. Options <c>optimize</c>, <c>nif</c>, and <c>driver</c> options are no longer necessary (and the ASN.1 compiler generates a warning if they are used). Options <c>ber_bin</c>, <c>per_bin</c>, and <c>uper_bin</c> options still work, but generates a warning. </p> <p>Another change in OTP R16 is that the generated function <c>encode/2</c> always returns a binary. Function <c>encode/2</c> for the <c>BER</c> back end used to return an iolist.</p> </note> </description> <funcs> <func> <name>compile(Asn1module) -> ok | {error, Reason}</name> <name>compile(Asn1module, Options) -> ok | {error, Reason}</name> <fsummary>Compiles an ASN.1 module and generates encode/decode functions according to encoding rules BER or PER.</fsummary> <type> <v>Asn1module = atom() | string()</v> <v>Options = [Option| OldOption]</v> <v>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</v> <v>OldOption = ber | per</v> <v>Reason = term()</v> <v>Prefix = string()</v> </type> <desc> <p>Compiles the <c>ASN.1</c> module <c>Asn1module</c> and generates an Erlang module <c>Asn1module.erl</c> with encode and decode functions for the types defined in <c>Asn1module</c>. For each ASN.1 value defined in the module, an Erlang function that returns the value in Erlang representation is generated.</p> <p>If <c>Asn1module</c> is a filename without extension, first <c>".asn1"</c> is assumed, then <c>".asn"</c>, and finally <c>".py"</c> (to be compatible with the old ASN.1 compiler). <c>Asn1module</c> can be a full pathname (relative or absolute) including filename with (or without) extension. <marker id="asn1set"></marker> </p> <p>If it is needed to compile a set of <c>ASN.1</c> 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 <c>".set.asn"</c> (<c>".asn"</c> can alternatively be <c>".asn1"</c> or <c>".py"</c>). List the input file names within quotation marks (""), one at each row in the file. If the input files are <c>File1.asn</c>, <c>File2.asn</c>, and <c>File3.asn</c>, the configuration file must look as follows:</p> <pre> File1.asn File2.asn File3.asn</pre> <p>The output files in this case get their names from the configuration file. If the configuration file is named <c>SetOfFiles.set.asn</c>, the names of the output files are <c>SetOfFiles.hrl, SetOfFiles.erl, and SetOfFiles.asn1db</c>.</p> <p>Sometimes in a system of <c>ASN.1</c> modules, different default tag modes, for example, <c>AUTOMATIC</c>, <c>IMPLICIT</c>, or <c>EXPLICIT</c>. The multi-file compilation resolves the default tagging as if the modules were compiled separately.</p> <p>Name collisions is another unwanted effect that can occur in multi file-compilation. The compiler solves this problem in one of two ways:</p> <list type="bulleted"> <item>If the definitions are identical, the output module keeps only one definition with the original name.</item> <item>If the definitions have the same name and differs in the definition, they are renamed. The new names are the definition name and the original module name concatenated.</item> </list> <p>If a name collision occurs, the compiler reports a <c>"NOTICE: ..."</c> message that tells if a definition was renamed, and the new name that must be used to encode/decode data.</p> <p><c>Options</c> is a list with options specific for the <c>ASN.1</c> compiler and options that are applied to the Erlang compiler. The latter are not recognized as <c>ASN.1</c> specific. The available options are as follows: </p> <taglist> <tag><c>ber | per | uper</c></tag> <item> <p> The encoding rule to be used. The supported encoding rules are Basic Encoding Rules (BER), Packed Encoding Rules (PER) aligned, and PER unaligned. If the encoding rule option is omitted, <c>ber</c> is the default. </p> <p> The generated Erlang module always gets the same name as the <c>ASN.1</c> module. Therefore, only one encoding rule per <c>ASN.1</c> module can be used at runtime. </p> </item> <tag><c>der</c></tag> <item> <p> 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 together with option <c>ber</c>. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding. The decoding routines are the same as for <c>ber</c>. </p> </item> <tag><c>compact_bit_string</c></tag> <item> <p> The <c>BIT STRING</c> type is decoded to "compact notation". <em>This option is not recommended for new code.</em> </p> <p>For details, see Section <seealso marker="asn1_getting_started#BIT STRING"> BIT STRING</seealso> in the User's Guide. </p> <p>This option implies option <c>legacy_erlang_types</c>.</p> </item> <tag><c>legacy_bit_string</c></tag> <item> <p> The <c>BIT STRING</c> type is decoded to the legacy format, that is, a list of zeroes and ones. <em>This option is not recommended for new code.</em> </p> <p>For details, see Section <seealso marker="asn1_getting_started#BIT STRING">BIT STRING</seealso> in the User's Guide</p> <p>This option implies option <c>legacy_erlang_types</c>.</p> </item> <tag><c>legacy_erlang_types</c></tag> <item> <p>Use the same Erlang types to represent <c>BIT STRING</c> and <c>OCTET STRING</c> as in OTP R16.</p> <p>For details, see Section <seealso marker="asn1_getting_started#BIT STRING">BIT STRING</seealso> and Section <seealso marker="asn1_getting_started#OCTET STRING">OCTET STRING</seealso> in the User's Guide.</p> <p><em>This option is not recommended for new code.</em></p> </item> <tag><c>{n2n, EnumTypeName}</c></tag> <item> <p> Tells the compiler to generate functions for conversion between names (as atoms) and numbers and conversely for the specified <c>EnumTypeName</c>. There can be multiple occurrences of this option to specify several type names. The type names must be declared as <c>ENUMERATIONS</c> in the ASN.1 specification.</p> <p> If <c>EnumTypeName</c> does not exist in the ASN.1 specification, the compilation stops with an error code.</p> <p> The generated conversion functions are named <c>name2num_EnumTypeName/1</c> and <c>num2name_EnumTypeName/1</c>. </p> </item> <tag><c>noobj</c></tag> <item> <p>Do not compile (that is, do not produce object code) the generated <c>.erl</c> file. If this option is omitted, the generated Erlang module is compiled.</p> </item> <tag><c>{i, IncludeDir}</c></tag> <item> <p>Adds <c>IncludeDir</c> to the search-path for <c>.asn1db</c> and <c>ASN.1</c> source files. The compiler tries to open an <c>.asn1db</c> file when a module imports definitions from another <c>ASN.1</c> module. If no <c>.asn1db</c> file is found, the <c>ASN.1</c> source file is parsed. Several <c>{i, IncludeDir}</c> can be given. </p> </item> <tag><c>{outdir, Dir}</c></tag> <item> <p>Specifies directory <c>Dir</c> where all generated files are to be placed. If this option is omitted, the files are placed in the current directory.</p> </item> <tag><c>asn1config</c></tag> <item> <p>When using one of the specialized decodes, exclusive or selective decode, instructions must be given in a configuration file. Option <c>asn1config</c> 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 <c>.asn1config</c>. </p> <p>For instructions for exclusive decode, see Section <seealso marker="asn1_spec#Exclusive Instruction">Exclusive Decode</seealso> in the User's Guide. </p> <p>For instructions for selective decode, see Section <seealso marker="asn1_spec#Selective Instruction">Selective Decode</seealso> in the User's Guide. </p> </item> <tag><c>undec_rest</c></tag> <item> <p>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 specification is compiled with this option, a tuple <c>{ok, Value, Rest}</c> is returned. <c>Rest</c> can be a list or a binary. Earlier versions of the compiler ignored those following bytes.</p> </item> <tag><c>no_ok_wrapper</c></tag> <item> <p>With this option, the generated <c>encode/2</c> and <c>decode/2</c> functions do not wrap a successful return value in an <c>{ok,...}</c> tuple. If any error occurs, an exception will be raised.</p> </item> <tag><c>{macro_name_prefix, Prefix}</c></tag> <item> <p>All macro names generated by the compiler are prefixed with <c>Prefix</c>. This is useful when multiple protocols that contain macros with identical names are included in a single module.</p> </item> <tag><c>{record_name_prefix, Prefix}</c></tag> <item> <p>All record names generated by the compiler are prefixed with <c>Prefix</c>. This is useful when multiple protocols that contain records with identical names are included in a single module.</p> </item> <tag><c>verbose</c></tag> <item> <p>Causes more verbose information from the compiler describing what it is doing.</p> </item> <tag><c>warnings_as_errors</c></tag> <item> <p>Causes warnings to be treated as errors.</p> </item> </taglist> <p>Any more option that is applied is passed to the final step when the generated <c>.erl</c> file is compiled. </p> <p>The compiler generates the following files:</p> <list type="bulleted"> <item><c>Asn1module.hrl</c> (if any <c>SET</c> or <c>SEQUENCE</c> is defined) </item> <item><c>Asn1module.erl</c> - Erlang module with encode, decode, and value functions </item> <item><c>Asn1module.asn1db</c> - Intermediate format used by the compiler when modules <c>IMPORT</c> definitions from each other. </item> </list> </desc> </func> <func> <name>encode(Module, Type, Value)-> {ok, Bytes} | {error, Reason}</name> <fsummary>Encodes an ASN.1 value.</fsummary> <type> <v>Module = Type = atom()</v> <v>Value = term()</v> <v>Bytes = binary()</v> <v>Reason = term()</v> </type> <desc> <p>Encodes <c>Value</c> of <c>Type</c> defined in the <c>ASN.1</c> module <c>Module</c>. To get as fast execution as possible, the encode function performs only the rudimentary tests that input <c>Value</c> is a correct instance of <c>Type</c>. So, for example, the length of strings is not always checked. Returns <c>{ok, Bytes}</c> if successful or <c>{error, Reason}</c> if an error occurred. </p> <p>This function is deprecated. Use <c>Module:encode(Type, Value)</c> instead.</p> </desc> </func> <func> <name>decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason}</name> <fsummary>Decode from Bytes into an ASN.1 value.</fsummary> <type> <v>Module = Type = atom()</v> <v>Value = Reason = term()</v> <v>Bytes = binary()</v> </type> <desc> <p>Decodes <c>Type</c> from <c>Module</c> from the binary <c>Bytes</c>. Returns <c>{ok, Value}</c> if successful.</p> <p>This function is deprecated. Use <c>Module:decode(Type, Bytes)</c> instead.</p> </desc> </func> <func> <name>value(Module, Type) -> {ok, Value} | {error, Reason}</name> <fsummary>Creates an ASN.1 value for test purposes.</fsummary> <type> <v>Module = Type = atom()</v> <v>Value = term()</v> <v>Reason = term()</v> </type> <desc> <p>Returns an Erlang term that is an example of a valid Erlang representation of a value of the <c>ASN.1</c> type <c>Type</c>. The value is a random value and subsequent calls to this function will for most types return different values.</p> </desc> </func> <func> <name>test(Module) -> ok | {error, Reason}</name> <name>test(Module, Type | Options) -> ok | {error, Reason}</name> <name>test(Module, Type, Value | Options) -> ok | {error, Reason}</name> <fsummary>Performs a test of encode and decode for types in an ASN.1 module.</fsummary> <type> <v>Module = Type = atom()</v> <v>Value = term()</v> <v>Options = [{i, IncludeDir}]</v> <v>Reason = term()</v> </type> <desc> <p>Performs a test of encode and decode of types in <c>Module</c>. 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.</p> <list type="bulleted"> <item> <p><c>test/1</c> iterates over all types in <c>Module</c>.</p> </item> <item> <p><c>test/2</c> tests type <c>Type</c> with a random value.</p> </item> <item> <p><c>test/3</c> tests type <c>Type</c> with <c>Value</c>.</p> </item> </list> <p>Schematically, the following occurs for each type in the module:</p> <code type="none"> {ok, Value} = asn1ct:value(Module, Type), {ok, Bytes} = asn1ct:encode(Module, Type, Value), {ok, Value} = asn1ct:decode(Module, Type, Bytes).</code> <p>The <c>test</c> functions use the <c>*.asn1db</c> 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 <c>Value</c> no options are needed.</p> </desc> </func> </funcs> </erlref>