Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 403 lines (394 sloc) 18.593 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2011</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 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).</p>
  </description>
  <funcs>
    <func>
      <name>compile(Asn1module) -> ok | {error,Reason}</name>
      <name>compile(Asn1module , Options) -> ok | {error,Reason}</name>
      <fsummary>Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER.</fsummary>
      <type>
        <v>Asn1module = atom() | string()</v>
        <v>Options = [Option| OldOption]</v>
        <v>Option = ber_bin | per_bin | uper_bin | der | compact_bit_string |
noobj | {n2n,EnumTypeName} |{outdir,Dir} | {i,IncludeDir} | optimize |
driver | asn1config | undec_rest | {inline,OutputName} | inline |
{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 ASN.1 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 which
          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).
          Of course <c>Asn1module</c> can be a full pathname (relative or
          absolute) including filename with (or without) extension.
                    <marker id="asn1set"></marker>
</p>
        <p>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 <c>File1.asn</c>,
          <c>File2.asn</c> and <c>File3.asn</c> the configuration file
          shall look like:</p>
        <pre>
File1.asn
File2.asn
File3.asn </pre>
        <p>The output files will in this case get their names from the
          configuration file. If the configuration file has the name
          <c>SetOfFiles.set.asn</c> the name of the output files will be
          <c>SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db</c>.</p>
        <p>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.</p>
        <p>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.</p>
        <p>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.</p>

        <p>
<c>Options</c> 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.
For <em>preferred option use</em> see <seealso
marker="asn1_ug#preferred option use">Preferred Option Use
section in users guide</seealso>. Available options are:
</p>
<taglist>
          <tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag>
          <item>
            <p>
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 <c>ber</c>
is the default.
The <c>per_bin</c> option means the aligned
variant. To use the unaligned variant the <c>uper_bin</c>
option has to be used.
</p>
<p>
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.
</p>
<p>
The <c>ber_bin</c> and <c>per_bin</c> options are
equivalent with the <c>OldOptions</c> <c>ber</c> and <c>per</c>
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 binary or an iolist.
</p>
          </item>
          <tag><c>der</c></tag>
          <item>
            <p>
By this option the Distinguished Encoding Rules (DER) is chosen.
DER is regarded as a specialized variant of the BER encoding
              rule, therefore the <c>der</c> option only makes sense together
with the <c>ber</c> or <c>ber_bin</c> option.
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>
Makes it possible to use a compact notation for values
              of the BIT STRING type in Erlang. The notation:
</p>
            <pre>
BitString = {Unused,Binary},
Unused = integer(),
Binary = binary()
</pre>
            <p>
<c>Unused</c> must be a number in the range 0 to 7. It
tells how many bits in the least significant byte in
<c>Binary</c> that is unused.
For details see
<seealso marker="asn1_ug#BIT STRING">
BIT STRING type section in users guide
</seealso>.
</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 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
<c>name2num_EnumTypeName/1</c> and
<c>num2name_EnumTypeName/1</c>.
</p>
          </item>
          <tag><c>noobj</c></tag>
          <item>
            <p>Do not compile (i.e do not produce object code) the generated
              <c>.erl</c> file. If this option is omitted the generated Erlang module
              will be compiled.</p>
          </item>
          <tag><c>{i,IncludeDir}</c></tag>
          <item>
            <p>Adds <c>IncludeDir</c> to the search-path for
              <c>.asn1db</c> and asn1 source files. The compiler tries
              to open a <c>.asn1db</c> file when a module imports
              definitions from another ASN.1 module. If no
              <c>.asn1db</c> file is found the asn1 source file is
              parsed. Several <c>{i,IncludeDir}</c> can be given.
              </p>
          </item>
          <tag><c>{outdir,Dir}</c></tag>
          <item>
            <p>Specifies the directory <c>Dir</c> where all generated files
              shall be placed. If omitted the files are placed in the
              current directory.</p>
          </item>
          <tag><c>optimize</c></tag>
          <item>
            <p>This option is only valid together with one of the
              <c>per_bin</c>
              or <c>ber_bin</c> option. It gives time optimized code
              generated and it uses another runtime module and
              in the <c>per_bin</c> case a linked-in driver. The result
              in the <c>per_bin</c> case from an encode when compiled
              with this option will be a binary.</p>
          </item>
          <tag><c>driver</c></tag>
          <item>
            <p>Option valid together with <c>ber_bin</c> and <c>optimize</c>
              options. It enables the use of a linked-in driver that gives
              considerable faster decode. In <c>ber_bin</c> the driver is
              enabled only by explicit use of the option <c>driver</c>.</p>
          </item>
          <tag><c>asn1config</c></tag>
          <item>
            <p>When one of the specialized decodes, exclusive or
              selective decode, is wanted one has to give instructions in
              a configuration file. The option <c>asn1config</c> enables
              specialized decodes and takes the configuration file, which
              has the same name as the ASN.1 spec but with extension
              <c>.asn1config</c>, in concern.
              </p>
            <p>The instructions for exclusive decode must follow the
              <seealso marker="asn1_spec#Exclusive Instruction">instruction and grammar in the User's Guide</seealso>.
              </p>
            <p>You can also find the instructions for selective decode
              in the
              <seealso marker="asn1_spec#Selective Instruction">User's Guide</seealso>.
              </p>
          </item>
          <tag><c>undec_rest</c></tag>
          <item>
            <p>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
              <c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a
              list or a binary. Earlier versions of the compiler ignored
              those following bytes.</p>
          </item>
          <tag><c>{inline,OutputName}</c></tag>
          <item>
            <p>Compiling with this option gives one output module
              containing all asn1 run-time functionality. The asn1 specs
              are provided in a target module Module.set.asn as described
              <seealso marker="#asn1set">above</seealso>. The name of the
              resulting module containing generated encode/decode functions
              and in-lined run-time functions will be
              <c>OutputName.erl</c>. The merging/in-lining of code is done
              by the <c>igor</c> module of <c>syntax_tools</c>. By default
              the functions generated from the first asn1 spec in the
              <c>.set.asn</c> are exported, unless a
              <c>{export,[atom()]}</c> or <c>{export_all,true}</c> option
              are provided. The list of atoms are names of chosen asn1
              specs from the <c>.set.asn</c> file.</p>
          </item>
          <tag><c>inline</c></tag>
          <item>
            <p>It is also possible to use the sole argument <c>inline</c>.
              It is as <c>{inline,OutputName}</c>, but the output file gets the
              default name of the source <c>.set.asn</c> file.</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 contains
              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 contains
              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 additional option that is applied will be passed to
          the final step when the generated .erl file is compiled.
          </p>
        <p>The compiler generates the following files:</p>
        <list type="bulleted">
          <item>
            <p><c>Asn1module.hrl</c> (if any SET or SEQUENCE is defined)</p>
          </item>
          <item>
            <p><c>Asn1module.erl</c> the Erlang module with encode, decode and value functions.</p>
          </item>
          <item>
            <p><c>Asn1module.asn1db</c> intermediate format used by the compiler when modules IMPORTS
              definitions from each other.</p>
          </item>
        </list>
      </desc>
    </func>
    <func>
      <name>encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}</name>
      <fsummary>Encode an ASN.1 value.</fsummary>
      <type>
        <v>Module = Type = atom()</v>
        <v>Value = term()</v>
        <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module
          <c>Module</c>. Returns a list of bytes if successful. To get as fast execution as
          possible the
          encode function only performs rudimentary tests that the input
          <c>Value</c>
          is a correct instance of <c>Type</c>. The length of strings is for example
          not always checked. Returns <c>{ok,Bytes}</c> if successful or
          <c>{error,Reason}</c> if an error occurred.
          </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 = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
      </type>
      <desc>
        <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes
          <c>Bytes</c>. Returns <c>{ok,Value}</c> if successful.</p>
      </desc>
    </func>
    <func>
      <name>validate(Module,Type,Value) -> ok | {error,Reason}</name>
      <fsummary>Validate an ASN.1 value.</fsummary>
      <type>
        <v>Module = Type = atom()</v>
        <v>Value = term()</v>
      </type>
      <desc>
        <p>Validates that <c>Value</c> conforms to <c>Type</c>
          from <c>Module</c>. <em>Not implemented in this version of the ASN.1 application.</em></p>
      </desc>
    </func>
    <func>
      <name>value(Module ,Type) -> {ok,Value} | {error,Reason}</name>
      <fsummary>Create 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 which is an example of a valid Erlang
          representation of a value of the ASN.1 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) -> ok | {error,Reason}</name>
      <name>test(Module,Type,Value) -> ok | {error,Reason}</name>
      <fsummary>Perform a test of encode and decode for types in an ASN.1 module.</fsummary>
      <desc>
        <p>Performs a test of encode and decode of all 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 and the general runtime support work
          as expected. <br></br>
<c>test/1</c> iterates over all types in <c>Module</c>. <br></br>
<c>test/2</c> tests type <c>Type</c> with a random value. <br></br>
<c><![CDATA[test/3 tests type <c>Type]]></c> with <c>Value</c>. <br></br>

          Schematically the following happens for each type in the module.</p>
        <p></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>
      </desc>
    </func>
  </funcs>
  
</erlref>

Something went wrong with that request. Please try again.