aboutsummaryrefslogtreecommitdiffstats
path: root/lib/asn1/doc/src/asn1_ug.xml
diff options
context:
space:
mode:
authorxsipewe <[email protected]>2015-04-14 23:21:36 +0200
committerBjörn Gustavsson <[email protected]>2015-05-08 10:49:04 +0200
commite95095457c4d83c02850b811fb28711c0b3d1c23 (patch)
tree49f92986c46decee1aabb6f91f252b8947302a84 /lib/asn1/doc/src/asn1_ug.xml
parent77484f2430133ec98ce0c63e037c3e3d183910be (diff)
downloadotp-e95095457c4d83c02850b811fb28711c0b3d1c23.tar.gz
otp-e95095457c4d83c02850b811fb28711c0b3d1c23.tar.bz2
otp-e95095457c4d83c02850b811fb28711c0b3d1c23.zip
Update asn1 documentation
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson.
Diffstat (limited to 'lib/asn1/doc/src/asn1_ug.xml')
-rw-r--r--lib/asn1/doc/src/asn1_ug.xml1417
1 files changed, 0 insertions, 1417 deletions
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
deleted file mode 100644
index 8b33497dd3..0000000000
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ /dev/null
@@ -1,1417 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE chapter SYSTEM "chapter.dtd">
-
-<chapter>
- <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>Asn1</title>
- <prepared>Kenneth Lundin</prepared>
- <docno></docno>
- <date>1999-03-25</date>
- <rev>D</rev>
- <file>asn1_ug.xml</file>
- </header>
-
- <section>
- <title>Introduction</title>
-
- <section>
- <title>Features</title>
- <p>The Asn1 application provides:</p>
- <list type="bulleted">
- <item>An ASN.1 compiler for Erlang, which generates encode and
- decode functions to be used by Erlang programs sending and
- receiving ASN.1 specified data.</item>
- <item>Run-time functions used by the generated code.</item>
- <item>Support for the following encoding rules:
- <list>
- <item>
- Basic Encoding Rules (<em>BER</em>)
- </item>
- <item>
- Distinguished Encoding Rules (<em>DER</em>), a specialized
- form of BER that is used in security-conscious
- applications.
- </item>
- <item>
- Packed Encoding Rules (<em>PER</em>); both the aligned and
- unaligned variant.
- </item>
- </list>
- </item>
- </list>
- </section>
-
- <section>
- <title>Overview</title>
- <p>ASN.1 (Abstract Syntax Notation One) is a formal language for
- describing data structures to be exchanged between distributed
- computer systems. The purpose of ASN.1 is to have a platform
- and programming language independent notation to express types
- using a standardized set of rules for the transformation of
- values of a defined type into a stream of bytes. This stream of
- bytes can then be sent on any type of communication
- channel. This way, two applications written in different
- programming languages running on different computers with
- different internal representation of data can exchange instances
- of structured data types.</p>
- </section>
-
- <section>
- <title>Prerequisites</title>
- <p>It is assumed that the reader is familiar with the ASN.1
- notation as documented in the standard definition [<cite
- id="X.680"></cite>] which is the primary text. It may also be
- helpful, but not necessary, to read the standard definitions
- [<cite id="X.681"></cite>] [<cite id="X.682"></cite>] [<cite
- id="X.683"></cite>] [<cite id="X.690"></cite>] [<cite
- id="X.691"></cite>]. </p>
- <p>A good book explaining those reference texts is
- [<cite id="DUBUISSON"></cite>], which is free to download at
- <url href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html</url>.
- </p>
- </section>
-
- <section>
- <title>Capabilities</title>
- <p>This application covers all features of ASN.1 up to the 1997
- edition of the specification. In the 2002 edition of ASN.1 a
- number of new features were introduced. The following features
- of the 2002 edition are fully or partly supported as shown
- below:</p>
- <list type="bulleted">
- <item>
- <p>Decimal notation (e.g., "1.5e3") for REAL values. The
- NR1, NR2 and NR3 formats as explained in ISO6093 are
- supported.</p>
- </item>
- <item>
- <p>The RELATIVE-OID type for relative object identifiers is
- fully supported.</p>
- </item>
- <item>
- <p>The subtype constraint (CONTAINING/ENCODED BY) to
- constrain the content of an octet string or a bit string is
- parsed when compiling, but no further action is taken. This
- constraint is not a PER-visible constraint.</p>
- </item>
- <item>
- <p>The subtype constraint by regular expressions (PATTERN)
- for character string types is parsed when compiling, but no
- further action is taken. This constraint is not a
- PER-visible constraint.</p>
- </item>
- <item>
- <p>Multiple-line comments as in C, <c>/* ... */</c>, are
- supported.</p>
- </item>
- </list>
- </section>
-
- </section>
-
- <section>
- <title>Getting Started with Asn1</title>
-
- <section>
- <title>A First Example</title>
- <p>The following example demonstrates the basic functionality used to run
- the Erlang ASN.1 compiler.</p>
- <p>Create a file called <c>People.asn</c> containing the following:</p>
- <pre>
-People DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
- Person ::= SEQUENCE {
- name PrintableString,
- location INTEGER {home(0),field(1),roving(2)},
- age INTEGER OPTIONAL
- }
-END </pre>
- <p>This file (<c>People.asn</c>) must be compiled before it can be
- used.
- The ASN.1 compiler checks that the syntax is correct and that the
- text represents proper ASN.1 code before generating an abstract
- syntax tree. The code-generator then uses the abstract syntax
- tree in order to generate code.
- </p>
- <p>The generated Erlang files will be placed in the current directory or
- in the directory specified with the <c>{outdir,Dir}</c> option.
- The following shows how the compiler
- can be called from the Erlang shell:</p>
- <pre>
-1><input> asn1ct:compile("People", [ber]).</input>
-ok
-2> </pre>
-
- <p>The <c>verbose</c> option can be given to have information
- about the generated files printed:</p>
- <pre>
-2><input> asn1ct:compile("People", [ber,verbose]).</input>
-Erlang ASN.1 compiling "People.asn"
---{generated,"People.asn1db"}--
---{generated,"People.hrl"}--
---{generated,"People.erl"}--
-ok
-3> </pre>
-
- <p>The ASN.1 module <c>People</c> is now accepted and the
- abstract syntax tree is saved in the <c>People.asn1db</c> file;
- the generated Erlang code is compiled using the Erlang compiler
- and loaded into the Erlang run-time system. Now there is an API
- for <c>encode/2</c> and <c>decode/2</c> in the module
- <c>People</c>, which is invoked by: <br></br>
- <c><![CDATA['People':encode(<Type name>, <Value>)]]></c>
- <br></br>
- or <br></br>
-<c><![CDATA['People':decode(<Type name>, <Value>)]]></c></p>
-
- <p>Assume there is a network
- application which receives instances of the ASN.1 defined
- type Person, modifies and sends them back again:</p>
- <code type="none">
-receive
- {Port,{data,Bytes}} ->
- case 'People':decode('Person',Bytes) of
- {ok,P} ->
- {ok,Answer} = 'People':encode('Person',mk_answer(P)),
- Port ! {self(),{command,Answer}};
- {error,Reason} ->
- exit({error,Reason})
- end
- end, </code>
- <p>In the example above, a series of bytes is received from an
- external source and the bytes are then decoded into a valid
- Erlang term. This was achieved with the call
- <c>'People':decode('Person',Bytes)</c> which returned
- an Erlang value of the ASN.1 type <c>Person</c>. Then an answer was
- constructed and encoded using
- <c>'People':encode('Person',Answer)</c> which takes an
- instance of a defined ASN.1 type and transforms it to a
- binary according to the BER or PER encoding rules.
- <br></br>
-The encoder and the decoder can also be run from
- the shell.</p>
- <pre>
-2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input>
-{'Person',"Some Name",roving,50}
-3> <input>{ok,Bin} = 'People':encode('Person',Rockstar).</input>
-{ok,&lt;&lt;243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
- 2,1,50&gt;&gt;}
-4> <input>{ok,Person} = 'People':decode('Person',Bin).</input>
-{ok,{'Person',"Some Name",roving,50}}
-5> </pre>
- </section>
-
- <section>
- <title>Module dependencies</title>
- <p>It is common that ASN.1 modules import defined types, values and
- other entities from another ASN.1 module.</p>
- <p>Earlier versions of the ASN.1 compiler required that modules that
- were imported from had to be compiled before the module that
- imported. This caused problems when ASN.1 modules had circular
- dependencies.</p>
- <p>Referenced modules are now parsed when the compiler finds an
- entity that is imported. There will not be any code generated for
- the referenced module. However, the compiled module rely on
- that the referenced modules also will be compiled.</p>
- </section>
- </section>
-
- <section>
- <title>The Asn1 Application User Interface</title>
- <p>The Asn1 application provides two separate user interfaces:</p>
- <list type="bulleted">
- <item>
- <p>The module <c>asn1ct</c> which provides the compile-time functions
- (including the compiler).</p>
- </item>
- <item>
- <p>The module <c>asn1rt_nif</c> which provides the run-time functions
- for the ASN.1 decoder for the BER back-end.</p>
- </item>
- </list>
- <p>The reason for the division of the interface into compile-time
- and run-time
- is that only run-time modules (<c>asn1rt*</c>) need to be loaded in
- an embedded system.
- </p>
-
- <section>
- <title>Compile-time Functions</title>
- <p>The ASN.1 compiler can be invoked directly from the command-line
- by means of the <c>erlc</c> program. This is convenient when compiling
- many ASN.1 files from the command-line or when using Makefiles.
- Here are some examples of how the <c>erlc</c> command can be used to invoke the
- ASN.1 compiler:</p>
- <pre>
-erlc Person.asn
-erlc -bper Person.asn
-erlc -bber ../Example.asn
-erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn </pre>
- <p>The useful options for the ASN.1 compiler are:</p>
- <taglist>
- <tag><c>-b[ber | per | uper]</c></tag>
- <item>
- <p>Choice of encoding rules, if omitted <c>ber</c> is the
- default.</p>
- </item>
- <tag><c>-o OutDirectory</c></tag>
- <item>
- <p>Where to put the generated files, default is the current
- directory.</p>
- </item>
- <tag><c>-I IncludeDir</c></tag>
- <item>
- <p>Where to search for <c>.asn1db</c> files and ASN.1
- source specs in order to resolve references to other
- modules. This option can be repeated many times if there
- are several places to search in. The compiler will always
- search the current directory first.</p>
- </item>
- <tag><c>+der</c></tag>
- <item>
- <p>DER encoding rule. Only when using <c>-ber</c> option.</p>
- </item>
- <tag><c>+asn1config</c></tag>
- <item>
- <p>This functionality works together with the
- <c>ber</c> option. It enables the
- specialized decodes, see the <seealso marker="asn1_spec">Specialized Decode</seealso> chapter.
- </p>
- </item>
- <tag><c>+undec_rest</c></tag>
- <item>
- <p>A buffer that holds a message being decoded may also have
- trailing bytes. If those trailing bytes are important they
- can be returned along with the decoded value by compiling
- the ASN.1 specification with the <c>+undec_rest</c> option.
- The return value from the decoder will be
- <c>{ok,Value,Rest}</c> where <c>Rest</c> is a binary
- containing the trailing bytes.</p>
- </item>
- <tag><c>+'Any Erlc Option'</c></tag>
- <item>
- <p>You may add any option to the Erlang compiler when
- compiling the generated Erlang files. Any option
- unrecognized by the ASN.1 compiler will be passed to the
- Erlang compiler.</p>
- </item>
- </taglist>
- <p>For a complete description of <c>erlc</c> see Erts Reference Manual.</p>
- <p>The compiler and other compile-time functions can also be invoked from
- the Erlang shell. Below follows a brief
- description of the primary functions, for a
- complete description of each function see
- <seealso marker="asn1ct">the Asn1 Reference Manual</seealso>, the
- <c>asn1ct</c> module.</p>
- <p>The compiler is invoked by using <c>asn1ct:compile/1</c> with
- default options, or <c>asn1ct:compile/2</c> if explicit options
- are given.
- Example:</p>
- <pre>
-asn1ct:compile("H323-MESSAGES.asn1"). </pre>
- <p>which equals:</p>
- <pre>
-asn1ct:compile("H323-MESSAGES.asn1",[ber]). </pre>
- <p>If one wants PER encoding:</p>
- <pre>
-asn1ct:compile("H323-MESSAGES.asn1",[per]). </pre>
- <p>The generic encode and decode functions can be invoked like this:</p>
- <pre>
-'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
-'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre>
- </section>
-
- <section>
- <title>Run-time Functions</title>
- <p>When an ASN.1 specification is compiled with the <c>ber</c>
- option, the module <c>asn1rt_nif</c> module and the NIF library in
- <c>asn1/priv_dir</c> will be needed at run-time.</p>
- <p>By invoking the function <c>info/0</c> in a generated module, one
- gets information about which compiler options were used.</p>
- </section>
-
- <section>
- <title>Errors</title>
- <p>Errors detected at
- compile time appear on the screen together with
- a line number indicating where in the source file the error
- was detected. If no errors are found, an Erlang ASN.1 module will
- be created.</p>
- <p>The run-time encoders and decoders execute within a catch and
- returns <c>{ok, Data}</c> or
- <c>{error, {asn1, Description}}</c> where
- <c>Description</c> is
- an Erlang term describing the error. </p>
- </section>
- </section>
-
- <section>
- <marker id="inlineExamples"></marker>
- <title>Multi-file Compilation</title>
- <p>There are various reasons for using multi-file compilation:</p>
- <list type="bulleted">
- <item>You want to choose the name for the generated module,
- perhaps because you need to compile the same specs for
- different encoding rules.</item>
- <item>You want only one resulting module.</item>
- </list>
- <p>You need to specify which ASN.1 specs you will
- compile in a module that must have the extension
- <c>.set.asn</c>. You chose name of the module and provide the
- names of the ASN.1 specs. For instance, if you have the specs
- <c>File1.asn</c>, <c>File2.asn</c> and <c>File3.asn</c> your
- module <c>MyModule.set.asn</c> will look like:</p>
- <pre>
-File1.asn
-File2.asn
-File3.asn </pre>
- <p>If you compile with:</p>
- <code type="none">
-~> erlc MyModule.set.asn </code>
- <p>the result will be one merged module <c>MyModule.erl</c> with
- the generated code from the three ASN.1 specs.
- </p>
- </section>
-
- <section>
- <title>A quick note about tags</title>
-
- <p>Tags used to be important for all users of ASN.1, because it
- was necessary to manually add tags to certain constructs in order
- for the ASN.1 specification to be valid. Here is an example of
- an old-style specification:</p>
-
- <pre>
-Tags DEFINITIONS ::=
-BEGIN
- Afters ::= CHOICE { cheese [0] IA5String,
- dessert [1] IA5String }
-END </pre>
-
- <p>Without the tags (the numbers in square brackets) the ASN.1
- compiler would refuse to compile the file.</p>
-
- <p>In 1994 the global tagging mode AUTOMATIC TAGS was introduced.
- By putting AUTOMATIC TAGS in the module header, the ASN.1 compiler
- will automatically add tags when needed. Here is the same
- specification in AUTOMATIC TAGS mode:</p>
-
- <pre>
-Tags DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
- Afters ::= CHOICE { cheese IA5String,
- dessert IA5String }
-END
-</pre>
-
- <p>Tags will not be mentioned any more in this manual.</p>
- </section>
-
- <section>
- <marker id="ASN1Types"></marker>
- <title>The ASN.1 Types</title>
- <p>This section describes the ASN.1 types including their
- functionality, purpose and how values are assigned in Erlang.
- </p>
- <p>ASN.1 has both primitive and constructed types:</p>
- <p></p>
- <table>
- <row>
- <cell align="left" valign="middle"><em>Primitive types</em></cell>
- <cell align="left" valign="middle"><em>Constructed types</em></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#BOOLEAN">BOOLEAN</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#SEQUENCE">SEQUENCE</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#INTEGER">INTEGER</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#SET">SET</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#REAL">REAL</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#CHOICE">CHOICE</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#NULL">NULL</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#SOF">SET OF and SEQUENCE OF</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#ENUMERATED">ENUMERATED</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#ANY">ANY</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#BIT STRING">BIT STRING</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#ANY">ANY DEFINED BY</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#OCTET STRING">OCTET STRING</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EXTERNAL</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#Character Strings">Character Strings</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">EMBEDDED PDV</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#OBJECT IDENTIFIER">OBJECT IDENTIFIER</seealso></cell>
- <cell align="left" valign="middle"><seealso marker="#NegotiationTypes">CHARACTER STRING</seealso></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#Object Descriptor">Object Descriptor</seealso></cell>
- <cell align="left" valign="middle"></cell>
- </row>
- <row>
- <cell align="left" valign="middle"><seealso marker="#The TIME types">The TIME types</seealso></cell>
- <cell align="left" valign="middle"></cell>
- </row>
- <tcaption>The supported ASN.1 types</tcaption>
- </table>
- <marker id="TypeNameValue"></marker>
- <note>
- <p>Values of each ASN.1 type has its own representation in Erlang
- described in the following subsections. Users shall provide
- these values for encoding according to the representation, as
- in the example below.</p>
- </note>
- <pre>
-Operational ::= BOOLEAN --ASN.1 definition </pre>
- <p>In Erlang code it may look like:</p>
- <pre>
-Val = true,
-{ok,Bytes} = MyModule:encode('Operational', Val), </pre>
- <p>Below follows a description of how
- values of each type can be represented in Erlang.
- </p>
-
- <section>
- <marker id="BOOLEAN"></marker>
- <title>BOOLEAN</title>
- <p>Booleans in ASN.1 express values that can be either
- TRUE or FALSE.
- The meanings assigned to TRUE or FALSE is beyond the scope
- of this text. <br></br>
-
- In ASN.1 it is possible to have:</p>
- <pre>
-Operational ::= BOOLEAN
- </pre>
- <p>Assigning a value to the type Operational in Erlang is possible by
- using the following Erlang code:</p>
- <code type="erl">
-Myvar1 = true,
- </code>
- <p>Thus, in Erlang the atoms <c>true</c> and <c>false</c> are used
- to encode a boolean value.</p>
- </section>
-
- <section>
- <marker id="INTEGER"></marker>
- <title>INTEGER</title>
- <p>ASN.1 itself specifies indefinitely large integers, and the Erlang
- systems with versions 4.3 and higher, support very large
- integers, in practice indefinitely large integers.</p>
- <p>The concept of sub-typing can be applied to integers as well
- as to other ASN.1 types. The details of sub-typing are not
- explained here, for further info see [<cite id="X.680"></cite>]. A variety
- of syntaxes are allowed when defining a type as an integer:</p>
- <pre>
-T1 ::= INTEGER
-T2 ::= INTEGER (-2..7)
-T3 ::= INTEGER (0..MAX)
-T4 ::= INTEGER (0&lt;..MAX)
-T5 ::= INTEGER (MIN&lt;..-99)
-T6 ::= INTEGER {red(0),blue(1),white(2)}
- </pre>
- <p>The Erlang representation of an ASN.1 INTEGER is an integer or
- an atom if a so called <c>Named Number List</c> (see T6 above)
- is specified.</p>
- <p>Below is an example of Erlang code which assigns values for the
- above types: </p>
- <pre>
-T1value = 0,
-T2value = 6,
-T6value1 = blue,
-T6value2 = 0,
-T6value3 = white
- </pre>
- <p>The Erlang variables above are now bound to valid instances of
- ASN.1 defined types. This style of value can be passed directly
- to the encoder for transformation into a series of bytes.</p>
- <p>The decoder will return an atom if the value corresponds to a
- symbol in the Named Number List.</p>
- </section>
-
- <section>
- <marker id="REAL"></marker>
- <title>REAL</title>
- <p>The following ASN.1 type is used for real numbers:</p>
- <pre>
-R1 ::= REAL
- </pre>
- <p>It can be assigned a value in Erlang as:</p>
- <pre>
-R1value1 = "2.14",
-R1value2 = {256,10,-2},
- </pre>
- <p>In the last line note that the tuple {256,10,-2} is the real number
- 2.56 in a special notation, which will encode faster than simply
- stating the number as <c>"2.56"</c>. The arity three tuple is
- <c>{Mantissa,Base,Exponent}</c> i.e. Mantissa * Base^Exponent.</p>
- </section>
-
- <section>
- <marker id="NULL"></marker>
- <title>NULL</title>
- <p>Null is suitable in cases where supply and recognition of a value
- is important but the actual value is not.</p>
- <pre>
-Notype ::= NULL
- </pre>
- <p>The NULL type can be assigned in Erlang:</p>
- <pre>
-N1 = 'NULL',
- </pre>
- <p>The actual value is the quoted atom 'NULL'.</p>
- </section>
-
- <section>
- <marker id="ENUMERATED"></marker>
- <title>ENUMERATED</title>
- <p>The enumerated type can be used, when the value we wish to
- describe, may only take one of a set of predefined values.</p>
- <pre>
-DaysOfTheWeek ::= ENUMERATED {
- sunday(1),monday(2),tuesday(3),
- wednesday(4),thursday(5),friday(6),saturday(7) }
- </pre>
- <p>For example to assign a weekday value in Erlang use the same atom
- as in the <c>Enumerations</c> of the type definition:</p>
- <pre>
-Day1 = saturday,
- </pre>
- <p>The enumerated type is very similar to an integer type, when
- defined with a set of predefined values. An enumerated type
- differs from an integer in that it may only have specified
- values, whereas an integer can also have any other value.</p>
- </section>
-
- <section>
- <marker id="BIT STRING"></marker>
- <title>BIT STRING</title>
- <p>The BIT STRING type can be used to model information which
- is made up of arbitrary length series of bits. It is intended
- to be used for a selection of flags, not for binary files. <br></br>
-
- In ASN.1 BIT STRING definitions may look like:
- </p>
- <pre>
-Bits1 ::= BIT STRING
-Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
- </pre>
- <p>There are two notations available for representation of
- BIT STRING values in Erlang and as input to the encode functions.</p>
- <list type="ordered">
- <item>A bitstring. By default, a BIT STRING with no
- symbolic names will be decoded to an Erlang bitstring.</item>
- <item>A list of atoms corresponding to atoms in the <c>NamedBitList</c>
- in the BIT STRING definition. A BIT STRING with symbolic
- names will always be decoded to this format.</item>
- </list>
- <p>Example:</p>
- <pre>
-Bits1Val1 = &lt;&lt;0:1,1:1,0:1,1:1,1:1&gt;&gt;,
-Bits2Val1 = [gnu,punk],
-Bits2Val2 = &lt;&lt;2#1110:4&gt;&gt;,
-Bits2Val3 = [bar,gnu,gnome],
- </pre>
- <p><c>Bits2Val2</c> and <c>Bits2Val3</c> above denote the same value.</p>
- <p><c>Bits2Val1</c> is assigned symbolic values. The assignment means
- that the bits corresponding to <c>gnu</c> and <c>punk</c> i.e. bits
- 2 and 14 are set to 1 and the rest set to 0. The symbolic values
- appear as a list of values. If a named value appears, which is not
- specified in the type definition, a run-time error will occur.</p>
- <p>BIT STRINGS may also be sub-typed with, for example, a SIZE
- specification:</p>
- <pre>
-Bits3 ::= BIT STRING (SIZE(0..31)) </pre>
- <p>This means that no bit higher than 31 can ever be set.</p>
-
- <section>
- <title>Deprecated representations for BIT STRING</title>
- <p>In addition to the representations described above, the
- following deprecated representations are available if the
- specification has been compiled with the
- <c>legacy_erlang_types</c> option:</p>
- <list type="ordered">
- <item>A list of binary digits (0 or 1). This format is
- accepted as input to the encode functions, and a BIT STRING
- will be decoded to this format if the
- <em>legacy_bit_string</em> option has been given.
- </item>
- <item>As <c>{Unused,Binary}</c> where <c>Unused</c> denotes
- how many trailing zero-bits 0 to 7 that are unused in the
- least significant byte in <c>Binary</c>. This format is
- accepted as input to the encode functions, and a <c>BIT
- STRING</c> will be decoded to this format if
- <em>compact_bit_string</em> has been given.
- </item>
- <item>A hexadecimal number (or an integer). This format
- should be avoided, since it is easy to misinterpret a BIT
- STRING value in this format.
- </item>
- </list>
- </section>
- </section>
-
- <section>
- <marker id="OCTET STRING"></marker>
- <title>OCTET STRING</title>
- <p>The OCTET STRING is the simplest of all ASN.1 types. The
- OCTET STRING only moves or transfers e.g. binary files or other
- unstructured information complying to two rules. Firstly, the
- bytes consist of octets and secondly, encoding is not
- required.</p>
- <p>It is possible to have the following ASN.1 type definitions:</p>
- <pre>
-O1 ::= OCTET STRING
-O2 ::= OCTET STRING (SIZE(28)) </pre>
- <p>With the following example assignments in Erlang:</p>
- <pre>
-O1Val = &lt;&lt;17,13,19,20,0,0,255,254&gt;&gt;,
-O2Val = &lt;&lt;"must be exactly 28 chars...."&gt;&gt;,</pre>
- <p>By default, an OCTET STRING is always represented as
- an Erlang binary. If the specification has been compiled with
- the <c>legacy_erlang_types</c> option, the encode functions
- will accept both lists and binaries, and the decode functions
- will decode an OCTET STRING to a list.</p>
- </section>
-
- <section>
- <marker id="Character Strings"></marker>
- <title>Character Strings</title>
- <p>ASN.1 supports a wide variety of character sets. The main difference
- between OCTET STRINGS and the Character strings is that OCTET
- STRINGS have no imposed semantics on the bytes delivered.</p>
- <p>However, when using for instance the IA5String (which closely
- resembles ASCII) the byte 65 (in decimal
- notation) <em>means</em> the character 'A'.
- </p>
- <p>For example, if a defined type is to be a VideotexString and
- an octet is received with the unsigned integer value X, then
- the octet should be interpreted as specified in the standard
- ITU-T T.100,T.101.
- </p>
- <p>The ASN.1 to Erlang compiler
- will not determine the correct interpretation of each BER
- (Basic Encoding Rules) string octet value with different
- Character strings. Interpretation of octets is the
- responsibility of the application. Therefore, from the BER
- string point of view, octets appear to be very similar to
- character strings and are compiled in the same way.
- </p>
- <p>It should be noted that when PER (Packed Encoding Rules) is
- used, there is a significant difference in the encoding scheme
- between OCTET STRINGS and other strings. The constraints
- specified for a type are especially important for PER, where
- they affect the encoding.
- </p>
- <p>Here are some examples:</p>
- <pre>
-Digs ::= NumericString (SIZE(1..3))
-TextFile ::= IA5String (SIZE(0..64000)) </pre>
- <p>with corresponding Erlang assignments:</p>
- <pre>
-DigsVal1 = "456",
-DigsVal2 = "123",
-TextFileVal1 = "abc...xyz...",
-TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] </pre>
- <p>The Erlang representation for "BMPString" and
- "UniversalString" is either a list of ASCII values or a list
- of quadruples. The quadruple representation associates to the
- Unicode standard representation of characters. The ASCII
- characters are all represented by quadruples beginning with
- three zeros like {0,0,0,65} for the 'A' character. When
- decoding a value for these strings the result is a list of
- quadruples, or integers when the value is an ASCII character.</p>
-
- <p>The following example shows how it works. We have the following
- specification in the file <c>PrimStrings.asn1</c>.</p>
- <pre>
-PrimStrings DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
- BMP ::= BMPString
-END
- </pre>
-
- <p>Encoding and decoding some strings:</p>
-
- <pre>
-1> <input>asn1ct:compile('PrimStrings', [ber]).</input>
-ok
-2> <input>{ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).</input>
-{ok,&lt;&lt;30,4,53,54,45,56>>}
-3> <input>'PrimStrings':decode('BMP', Bytes1).</input>
-{ok,[{0,0,53,53},{0,0,45,56}]}
-4> <input>{ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).</input>
-{ok,&lt;&lt;30,4,53,53,0,65>>}
-5> <input>'PrimStrings':decode('BMP', Bytes2).</input>
-{ok,[{0,0,53,53},65]}
-6> <input>{ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").</input>
-{ok,&lt;&lt;30,20,0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103>>}
-7> <input>'PrimStrings':decode('BMP', Bytes3).</input>
-{ok,"BMP string"} </pre>
-
- <p>The UTF8String type is represented as a UTF-8 encoded binary in
- Erlang. Such binaries can be created directly using the binary syntax
- or by converting from a list of Unicode code points using the
- <c>unicode:characters_to_binary/1</c> function.</p>
-
- <p>Here are some examples showing how UTF-8 encoded binaries can
- be created and manipulated:</p>
-
- <pre>
-1> <input>Gs = "Мой маленький Гном".</input>
-[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
- 1081,32,1043,1085,1086,1084]
-2> <input>Gbin = unicode:characters_to_binary(Gs).</input>
-&lt;&lt;208,156,208,190,208,185,32,208,188,208,176,208,187,208,
- 181,208,189,209,140,208,186,208,184,208,185,32,208,147,
- 208,...>>
-3> <input>Gbin = &lt;&lt;"Мой маленький Гном"/utf8>>.</input>
-&lt;&lt;208,156,208,190,208,185,32,208,188,208,176,208,187,208,
- 181,208,189,209,140,208,186,208,184,208,185,32,208,147,
- 208,...>>
-4> <input>Gs = unicode:characters_to_list(Gbin).</input>
-[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
- 1081,32,1043,1085,1086,1084]
- </pre>
-
- <p>See the <seealso marker="stdlib:unicode">unicode</seealso> module
- for more details.</p>
-
- <p>In the following example we will use this ASN.1 specification:</p>
- <pre>
-UTF DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
- UTF ::= UTF8String
-END
- </pre>
-
- <p>Encoding and decoding a string with Unicode characters:</p>
-
- <pre>
-5> <input>asn1ct:compile('UTF', [ber]).</input>
-ok
-6> <input>{ok,Bytes1} = 'UTF':encode('UTF', &lt;&lt;"Гном"/utf8>>).</input>
-{ok,&lt;&lt;12,8,208,147,208,189,208,190,208,188>>}
-7> <input>{ok,Bin1} = 'UTF':decode('UTF', Bytes1).</input>
-{ok,&lt;&lt;208,147,208,189,208,190,208,188>>}
-8> <input>io:format("~ts\n", [Bin1]).</input>
-Гном
-ok
-9> <input>unicode:characters_to_list(Bin1).</input>
-[1043,1085,1086,1084]
- </pre>
- </section>
-
- <section>
- <marker id="OBJECT IDENTIFIER"></marker>
- <title>OBJECT IDENTIFIER</title>
- <p>The OBJECT IDENTIFIER is used whenever a unique identity is required.
- An ASN.1 module, a transfer syntax, etc. is identified with an
- OBJECT IDENTIFIER. Assume the example below:</p>
- <pre>
-Oid ::= OBJECT IDENTIFIER
- </pre>
- <p>Therefore, the example below is a valid Erlang instance of the
- type 'Oid'.</p>
- <pre>
-OidVal1 = {1,2,55},
- </pre>
- <p>The OBJECT IDENTIFIER value is simply a tuple with the
- consecutive values which must be integers.
- </p>
- <p>The first value is limited to the values 0, 1 or 2 and the
- second value must be in the range 0..39 when the first value
- is 0 or 1.
- </p>
- <p>The OBJECT IDENTIFIER is a very important type and it is
- widely used within different standards to uniquely identify
- various objects. In [<cite id="DUBUISSON"></cite>], there is an
- easy-to-understand description of the usage of
- OBJECT IDENTIFIER.</p>
- <p></p>
- </section>
-
- <section>
- <marker id="Object Descriptor"></marker>
- <title>Object Descriptor</title>
- <p>Values of this type can be assigned a value as an ordinary string
- like this:</p>
-
- <pre>
- "This is the value of an Object descriptor"</pre>
- </section>
-
- <section>
- <marker id="The TIME types"></marker>
- <title>The TIME Types</title>
- <p>Two different time types are defined within ASN.1, Generalized
- Time and UTC (Universal Time Coordinated), both are assigned a
- value as an ordinary string within double quotes i.e.
- "19820102070533.8".</p>
- <p>In case of DER encoding the compiler does not check the validity
- of the time values. The DER requirements upon those strings is
- regarded as a matter for the application to fulfill.</p>
- </section>
-
- <section>
- <marker id="SEQUENCE"></marker>
- <title>SEQUENCE</title>
- <p>The structured types of ASN.1 are constructed from other types
- in a manner similar to the concepts of array and struct in C.
- <br></br>
- A SEQUENCE in ASN.1 is
- comparable with a struct in C and a record in Erlang.
- A SEQUENCE may be defined as:</p>
- <pre>
-Pdu ::= SEQUENCE {
- a INTEGER,
- b REAL,
- c OBJECT IDENTIFIER,
- d NULL } </pre>
- <p>This is a 4-component structure called 'Pdu'. The major format
- for representation of SEQUENCE in Erlang is the record format.
- For each SEQUENCE and <c>SET</c> in an ASN.1 module an Erlang
- record declaration is generated. For <c>Pdu</c> above, a record
- like this is defined:</p>
- <pre>
--record('Pdu',{a, b, c, d}). </pre>
- <p>The record declarations for a module <c>M</c> are placed in a
- separate <c>M.hrl</c> file.</p>
- <p>Values can be assigned in Erlang as shown below:</p>
- <pre>
-MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre>
- <p>The decode functions will return a record as result when decoding
- a <c>SEQUENCE</c> or a <c>SET</c>.</p>
-
- <p>A <c>SEQUENCE</c> and a <c>SET</c> may contain a component
- with a <c>DEFAULT</c> key word followed by the actual value that
- is the default value. The <c>DEFAULT</c> keyword means that the
- application doing the encoding can omit encoding of the value,
- thus resulting in fewer bytes to send to the receiving
- application.</p>
-
- <p>An application can use the atom <c>asn1_DEFAULT</c> to indicate
- that the encoding should be omitted for that position in
- the SEQUENCE.</p>
-
- <p>Depending on the encoding rules, the encoder may also compare
- the given value to the default value and automatically omit the
- encoding if they are equal. How much effort the encoder makes to
- to compare the values depends on the encoding rules. The DER
- encoding rules forbids encoding a value equal to the default value,
- so it has a more thorough and time-consuming comparison than the
- encoders for the other encoding rules.</p>
-
- <p>In the following example we will use this ASN.1 specification:</p>
- <pre>
-File DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-Seq1 ::= SEQUENCE {
- a INTEGER DEFAULT 1,
- b Seq2 DEFAULT {aa TRUE, bb 15}
-}
-
-Seq2 ::= SEQUENCE {
- aa BOOLEAN,
- bb INTEGER
-}
-
-Seq3 ::= SEQUENCE {
- bs BIT STRING {a(0), b(1), c(2)} DEFAULT {a, c}
-}
-END </pre>
- <p>Here is an example where the BER encoder is able to omit encoding
- of the default values:</p>
- <pre>
-1> <input>asn1ct:compile('File', [ber]).</input>
-ok
-2> <input>'File':encode('Seq1', {'Seq1',asn1_DEFAULT,asn1_DEFAULT}).</input>
-{ok,&lt;&lt;48,0>>}
-3> <input>'File':encode('Seq1', {'Seq1',1,{'Seq2',true,15}}).</input>
-{ok,&lt;&lt;48,0>>} </pre>
-
- <p>And here is an example with a named BIT STRING where the BER
- encoder will not omit the encoding:</p>
- <pre>
-4> <input>'File':encode('Seq3', {'Seq3',asn1_DEFAULT).</input>
-{ok,&lt;&lt;48,0>>}
-5> <input>'File':encode('Seq3', {'Seq3',&lt;&lt;16#101:3>>).</input>
-{ok,&lt;&lt;48,4,128,2,5,160>>} </pre>
-
- <p>The DER encoder will omit the encoding for the same BIT STRING:</p>
- <pre>
-6> <input>asn1ct:compile('File', [ber,der]).</input>
-ok
-7> <input>'File':encode('Seq3', {'Seq3',asn1_DEFAULT).</input>
-{ok,&lt;&lt;48,0>>}
-8> <input>'File':encode('Seq3', {'Seq3',&lt;&lt;16#101:3>>).</input>
-{ok,&lt;&lt;48,0>>} </pre>
- </section>
-
- <section>
- <marker id="SET"></marker>
- <title>SET</title>
- <p>In Erlang, the SET type is used exactly as SEQUENCE. Note
- that if the BER or DER encoding rules are used, decoding a
- SET is slower than decoding a SEQUENCE because the components
- must be sorted.</p>
- </section>
-
- <section>
- <title>Notes about extensibility for SEQUENCE and SET</title>
- <p>When a SEQUENCE or SET contains an extension marker and
- extension components like this:</p>
- <pre>
-SExt ::= SEQUENCE {
- a INTEGER,
- ...,
- b BOOLEAN }
- </pre>
- <p>It means that the type may get more components in newer
- versions of the ASN.1 spec. In this case it has got a new
- component <c>b</c>. Thus, incoming messages that will be decoded
- may have more or fever components than this one.
- </p>
- <p>The component <c>b</c> will be treated as
- an original component when encoding a message. In this case, as
- it is not an optional element, it must be encoded.
- </p>
- <p>During decoding the <c>b</c> field of the record will get the decoded
- value of the <c>b</c>
- component if present and otherwise the value <c>asn1_NOVALUE</c>.</p>
- </section>
-
- <section>
- <marker id="CHOICE"></marker>
- <title>CHOICE</title>
- <p>The CHOICE type is a space saver and is similar to the concept of a
- 'union' in the C language.</p>
- <p>Assume:</p>
- <pre>
-SomeModuleName DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-T ::= CHOICE {
- x REAL,
- y INTEGER,
- z OBJECT IDENTIFIER }
-END </pre>
- <p>It is then possible to assign values:</p>
- <pre>
-TVal1 = {y,17},
-TVal2 = {z,{0,1,2}},
- </pre>
- <p>A CHOICE value is always represented as the tuple
- <c>{ChoiceAlternative, Val}</c> where <c>ChoiceAlternative</c>
- is an atom denoting the selected choice alternative.
- </p>
-
- <section>
- <title>Extensible CHOICE</title>
- <p>When a CHOICE contains an extension marker and the decoder detects
- an unknown alternative of the CHOICE the value is represented as:</p>
- <pre>
-{asn1_ExtAlt, BytesForOpenType}
- </pre>
- <p>Where <c>BytesForOpenType</c> is a list of bytes constituting the
- encoding of the "unknown" CHOICE alternative. </p>
- </section>
- </section>
-
- <section>
- <marker id="SOF"></marker>
- <title>SET OF and SEQUENCE OF</title>
- <p>The SET OF and SEQUENCE OF types correspond to the concept of an array
- found in several programming languages. The Erlang syntax for
- both of these types is straight forward. For example:</p>
- <pre>
-Arr1 ::= SET SIZE (5) OF INTEGER (4..9)
-Arr2 ::= SEQUENCE OF OCTET STRING </pre>
- <p>We may have the following in Erlang:</p>
- <pre>
-Arr1Val = [4,5,6,7,8],
-Arr2Val = ["abc",[14,34,54],"Octets"], </pre>
- <p>Please note that the definition of the SET OF type implies that
- the order of the components is undefined, but in practice there is
- no difference between SET OF and SEQUENCE OF. The ASN.1 compiler
- for Erlang does not randomize the order of the SET OF components
- before encoding.</p>
- <p>However, in case of a value of the type <c>SET OF</c>, the DER
- encoding format requires the elements to be sent in ascending
- order of their encoding, which implies an expensive sorting
- procedure in run-time. Therefore it is strongly recommended to
- use <c>SEQUENCE OF</c> instead of <c>SET OF</c> if it is possible.</p>
- </section>
-
- <section>
- <marker id="ANY"></marker>
- <title>ANY and ANY DEFINED BY</title>
- <p>The types <c>ANY</c> and <c>ANY DEFINED BY</c> have been removed
- from the standard since 1994. It is recommended not to use
- these types any more. They may, however, exist in some old ASN.1
- modules.
- The idea with this type was to leave a "hole" in a definition where
- one could put unspecified data of any kind, even non ASN.1 data.</p>
- <p>A value of this type is encoded as an <c>open type</c>.</p>
- <p>Instead of <c>ANY</c>/<c>ANY DEFINED BY</c> one should use
- <c>information object class</c>, <c>table constraints</c> and
- <c>parameterization</c>. In particular the construct
- <c>TYPE-IDENTIFIER.@Type</c> accomplish the same as the
- deprecated <c>ANY</c>.</p>
- <p>See also <seealso marker="#Information Object">Information object</seealso></p>
- </section>
-
- <section>
- <marker id="NegotiationTypes"></marker>
- <title>EXTERNAL, EMBEDDED PDV and CHARACTER STRING</title>
- <p>These types are used in presentation layer negotiation. They are
- encoded according to their associated type, see [<cite id="X.680"></cite>].</p>
- <p>The <c>EXTERNAL</c> type had a slightly different associated type
- before 1994. [<cite id="X.691"></cite>] states that encoding shall follow
- the older associate type. Therefore does generated encode/decode
- functions convert values of the newer format to the older format
- before encoding. This implies that it is allowed to use
- <c>EXTERNAL</c> type values of either format for encoding. Decoded
- values are always returned on the newer format.</p>
- </section>
-
- <section>
- <title>Embedded Named Types</title>
- <p>The structured types previously described may very well have other named types
- as their components. The general syntax to assign a value to the component C
- of a named ASN.1 type T in Erlang is the record syntax
- <c>#'T'{'C'=Value}</c>.
- Where <c>Value</c> may be a value of yet another type T2.</p>
- <p>For example:</p>
- <pre>
-EmbeddedExample DEFINITIONS AUTOMATIC TAGS ::=
-BEGIN
-B ::= SEQUENCE {
- a Arr1,
- b T }
-
-Arr1 ::= SET SIZE (5) OF INTEGER (4..9)
-
-T ::= CHOICE {
- x REAL,
- y INTEGER,
- z OBJECT IDENTIFIER }
- END </pre>
- <p>The SEQUENCE b can be encoded like this in Erlang:</p>
- <pre>
-1> 'EmbeddedExample':encode('B', {'B',[4,5,6,7,8],{x,"7.77"}}).
-{ok,&lt;&lt;5,56,0,8,3,55,55,55,46,69,45,50>>} </pre>
- </section>
- </section>
-
- <section>
- <title>Naming of Records in .hrl Files</title>
- <p>When an ASN.1 specification is compiled all defined types of
- type SET or SEQUENCE will result in a corresponding record in the
- generated hrl file. This is because the values for SET/SEQUENCE
- as mentioned in sections above are represented as records.</p>
- <p>Though there are some special cases of this functionality that
- are presented below.</p>
-
- <section>
- <title>Embedded Structured Types</title>
- <p>It is also possible in ASN.1 to have components that are themselves
- structured types.
- For example, it is possible to have:</p>
- <pre>
-Emb ::= SEQUENCE {
- a SEQUENCE OF OCTET STRING,
- b SET {
- a INTEGER,
- b INTEGER DEFAULT 66},
- c CHOICE {
- a INTEGER,
- b FooType } }
-
-FooType ::= [3] VisibleString </pre>
- <p>The following records are generated because of the type <c>Emb</c>:</p>
- <pre>
--record('Emb,{a, b, c}).
--record('Emb_b',{a, b = asn1_DEFAULT}). % the embedded SET type
- </pre>
- <p>Values of the <c>Emb</c> type can be assigned like this:</p>
- <code type="none">
-V = #'Emb'{a=["qqqq",[1,2,255]],
- b = #'Emb_b'{a=99},
- c ={b,"Can you see this"}}.
- </code>
- <p>For an embedded type of type SEQUENCE/SET in a SEQUENCE/SET
- the record name is extended with an underscore and the component
- name. If the embedded structure is deeper with SEQUENCE, SET or
- CHOICE types in the line, each component-/alternative-name will
- be added to the record-name.</p>
- <p>For example:</p>
- <pre>
-Seq ::= SEQUENCE{
- a CHOICE{
- b SEQUENCE {
- c INTEGER
- }
- }
-} </pre>
- <p>will result in the following record:</p>
- <pre>
--record('Seq_a_b',{c}). </pre>
- <p>If the structured type has a component with an embedded
- SEQUENCE OF/SET OF which embedded type in turn is a
- SEQUENCE/SET it will give a record with the SEQOF/SETOF
- addition as in the following example:</p>
- <pre>
-Seq ::= SEQUENCE {
- a SEQUENCE OF SEQUENCE {
- b
- }
- c SET OF SEQUENCE {
- d
- }
-} </pre>
- <p>This results in the records:</p>
- <pre>
--record('Seq_a_SEQOF'{b}).
--record('Seq_c_SETOF'{d}). </pre>
- <p>A parameterized type should be considered as an embedded
- type. Each time a such type is referenced an instance of it is
- defined. Thus in the following example a record with name
- <c>'Seq_b'</c> is generated in the .hrl file and used to hold
- values.</p>
- <pre>
-Seq ::= SEQUENCE {
- b PType{INTEGER}
-}
-
-PType{T} ::= SEQUENCE{
- id T
-} </pre>
- </section>
-
- <section>
- <title>Recursive Types</title>
- <p>Types may refer to themselves. Suppose:</p>
- <pre>
-Rec ::= CHOICE {
- nothing NULL,
- something SEQUENCE {
- a INTEGER,
- b OCTET STRING,
- c Rec }} </pre>
- <p>This type is recursive; that is, it refers to itself. This is allowed
- in ASN.1 and the ASN.1-to-Erlang compiler supports this recursive
- type. A value for this type is assigned in Erlang as shown below:</p>
- <pre>
-V = {something,#'Rec_something'{a = 77,
- b = "some octets here",
- c = {nothing,'NULL'}}}. </pre>
- </section>
- </section>
-
- <section>
- <title>ASN.1 Values</title>
- <p>Values can be assigned to ASN.1 type within the ASN.1 code
- itself, as opposed to the actions taken in the previous chapter where
- a value was assigned to an ASN.1 type in Erlang. The full value
- syntax of ASN.1 is supported and [X.680] describes in detail how
- to assign values in ASN.1. Below is a short example:</p>
- <pre>
-TT ::= SEQUENCE {
- a INTEGER,
- b SET OF OCTET STRING }
-
-tt TT ::= {a 77,b {"kalle","kula"}} </pre>
- <p>The value defined here could be used in several ways.
- Firstly, it could be used as the value in some DEFAULT component:</p>
- <pre>
-SS ::= SET {
- s OBJECT IDENTIFIER,
- val TT DEFAULT tt } </pre>
- <p>It could also be used from inside an Erlang program. If the above ASN.1
- code was defined in ASN.1 module <c>Values</c>, then the ASN.1 value
- <c>tt</c> can be reached from Erlang as
- a function call to <c>'Values':tt()</c> as in the example below.</p>
- <pre>
-1> <input>Val = 'Values':tt().</input>
-{'TT',77,["kalle","kula"]}
-2> <input>{ok,Bytes} = 'Values':encode('TT',Val).</input>
-{ok,&lt;&lt;48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
- 107,117,108,97&gt;&gt;}
-4> <input>'Values':decode('TT',Bytes).</input>
-{ok,{'TT',77,["kalle","kula"]}}
-5>
- </pre>
- <p>The above example shows that a function is generated by the compiler
- that returns a valid Erlang representation of the value, even though
- the value is of a complex type.</p>
- <p>Furthermore, there is a macro generated for each value in the .hrl
- file. So, the defined value <c>tt</c> can also be extracted by
- <c>?tt</c> in application code.</p>
- </section>
-
- <section>
- <title>Macros</title>
- <p>MACRO is not supported as the the type is no longer part of the
- ASN.1 standard.</p>
- </section>
-
- <section>
- <marker id="Information Object"></marker>
- <title>ASN.1 Information Objects (X.681)</title>
- <p>Information Object Classes, Information Objects and Information
- Object Sets (in the following called classes, objects and
- object sets respectively) are defined in the standard
- definition [<cite id="X.681"></cite>]. In the following only a brief
- explanation is given. </p>
- <p>These constructs makes it possible to define open types,
- i.e. values of that type can be of any ASN.1 type. It is also
- possible to define relationships between different types and
- values, since classes can hold types, values, objects, object
- sets and other classes in its fields.
- An Information Object Class may be defined in ASN.1 as:</p>
- <pre>
-GENERAL-PROCEDURE ::= CLASS {
- &amp;Message,
- &amp;Reply OPTIONAL,
- &amp;Error OPTIONAL,
- &amp;id PrintableString UNIQUE
-}
-WITH SYNTAX {
- NEW MESSAGE &amp;Message
- [REPLY &amp;Reply]
- [ERROR &amp;Error]
- ADDRESS &amp;id
-} </pre>
- <p>An object is an instance of a class and an object set is a set
- containing objects of one specified class. A definition may look like
- below.</p>
- <p>The object <c>object1</c> is an instance of the CLASS
- GENERAL-PROCEDURE and has one type field and one fixed type value
- field. The object <c>object2</c> also has an OPTIONAL field ERROR,
- which is a type field.</p>
- <pre>
-object1 GENERAL-PROCEDURE ::= {
- NEW MESSAGE PrintableString
- ADDRESS "home"
-}
-
-object2 GENERAL-PROCEDURE ::= {
- NEW MESSAGE INTEGER
- ERROR INTEGER
- ADDRESS "remote"
-} </pre>
- <p>The field ADDRESS is a UNIQUE field. Objects in an object set must
- have unique values in their UNIQUE field, as in GENERAL-PROCEDURES: </p>
- <pre>
-GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
- object1 | object2} </pre>
- <p>One can not encode a class, object or object set, only referring to
- it when defining other ASN.1 entities. Typically one refers to a
- class and to object sets by table constraints and component
- relation constraints [<cite id="X.682"></cite>] in ASN.1 types, as in: </p>
- <pre>
-StartMessage ::= SEQUENCE {
- msgId GENERAL-PROCEDURE.&amp;id ({GENERAL-PROCEDURES}),
- content GENERAL-PROCEDURE.&amp;Message ({GENERAL-PROCEDURES}{@msgId}),
- } </pre>
- <p>In the type <c>StartMessage</c> the constraint following the
- <c>content</c> field tells that in a value of type
- <c>StartMessage</c> the value in the <c>content</c> field must
- come from the same object that is chosen by the <c>msgId</c>
- field.</p>
- <p>So, the value <c>#'StartMessage'{msgId="home",content="Any Printable String"}</c> is legal to encode as a StartMessage
- value, while the value <c>#'StartMessage'{msgId="remote", content="Some String"}</c> is illegal since the constraint
- in StartMessage tells that when you have chosen a value from a
- specific object in the object set GENERAL-PROCEDURES in the
- msgId field you have to choose a value from that same object in
- the content field too. In this second case it should have been
- any INTEGER value.</p>
- <p><c>StartMessage</c> can in the <c>content</c> field be
- encoded with a value of any type that an object in the
- <c>GENERAL-PROCEDURES</c> object set has in its <c>NEW MESSAGE</c> field. This field refers to a type field
- <c>&amp;Message</c> in the class. The <c>msgId</c> field is always
- encoded as a PrintableString, since the field refers to a fixed type
- in the class.</p>
- <p>In practice, object sets are usually declared to be extensible so
- so that more objects can be added to the set later. Extensibility is
- indicated like this:</p>
- <pre>
-GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
- object1 | object2, ...} </pre>
- <p>When decoding a type that uses an extensible set constraint,
- there is always the possibility that the value in the UNIQUE
- field is unknown (i.e. the type has been encoded with a later
- version of the ASN.1 specification). When that happens, the
- unencoded data will be returned wrapped in a tuple like this:</p>
-
- <pre>
-{asn1_OPENTYPE,Binary}</pre>
- <p>where <c>Binary</c> is an Erlang binary that contains the encoded
- data. (If the option <c>legacy_erlang_types</c> has been given,
- just the binary will be returned.)</p>
- </section>
-
- <section>
- <title>Parameterization (X.683)</title>
- <p>Parameterization, which is defined in the standard [<cite id="X.683"></cite>], can be used when defining types, values, value
- sets, information object classes, information objects or
- information object sets.
- A part of a definition can be supplied as a parameter. For
- instance, if a Type is used in a definition with certain
- purpose, one want the type-name to express the intention. This
- can be done with parameterization.</p>
- <p>When many types (or another ASN.1 entity) only differs in some
- minor cases, but the structure of the types are similar, only
- one general type can be defined and the differences may be supplied
- through parameters. </p>
- <p>One example of use of parameterization is:</p>
- <pre>
-General{Type} ::= SEQUENCE
-{
- number INTEGER,
- string Type
-}
-
-T1 ::= General{PrintableString}
-
-T2 ::= General{BIT STRING}
- </pre>
- <p>An example of a value that can be encoded as type T1 is {12,"hello"}.</p>
- <p>Note that the compiler does not generate encode/decode functions for
- parameterized types, but only for the instances of the parameterized
- types. Therefore, if a file contains the types General{}, T1 and T2 above,
- encode/decode functions will only be generated for T1 and T2.
- </p>
- </section>
-</chapter>
-