path: root/lib/asn1/doc/src/asn1ct.xml

<?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>