aboutsummaryrefslogtreecommitdiffstats
path: root/lib/asn1/doc
diff options
context:
space:
mode:
authorKenneth Lundin <[email protected]>2010-09-10 09:57:45 +0200
committerKenneth Lundin <[email protected]>2010-09-10 10:04:36 +0200
commit94f7e0867fb3367fe86b2220df414f9133d911ec (patch)
treec349d40997adc5e0df4f8bcdcb613150eacce04d /lib/asn1/doc
parent6e66a59544a4816c49d2d4ae4bfa4f408403a1ab (diff)
downloadotp-94f7e0867fb3367fe86b2220df414f9133d911ec.tar.gz
otp-94f7e0867fb3367fe86b2220df414f9133d911ec.tar.bz2
otp-94f7e0867fb3367fe86b2220df414f9133d911ec.zip
Add warning about since long unsupported [{Cname,Val}] repr. of SEQUENCE/SET
Othe minor corrections as well.
Diffstat (limited to 'lib/asn1/doc')
-rw-r--r--lib/asn1/doc/src/asn1_ug.xml113
1 files changed, 62 insertions, 51 deletions
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index f2cd073ec8..12d986308f 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2010</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -22,7 +22,7 @@
</legalnotice>
<title>Asn1</title>
- <prepared>ETX/DN/SP Kenneth. Lundin</prepared>
+ <prepared>Kenneth Lundin</prepared>
<docno></docno>
<date>1999-03-25</date>
<rev>D</rev>
@@ -41,17 +41,28 @@
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>Encoding rules supported are <em>BER</em>, the
- specialized BER version <em>DER</em> and the basic form of
- aligned and unaligned variants of <em>PER</em>.</item>
+ <item>The supported encoding rules are:
+ <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 1) defines the abstract
- syntax of information. The purpose of ASN.1 is to have
- a platform independent language to express types using a
+ <p>ASN.1 (Abstract Syntax Notation 1) 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 a communication channel set up by the
@@ -102,20 +113,16 @@
[<cite id="DUBUISSON"></cite>], free to download at
<url href="http://www.oss.com/asn1/dubuisson.html">http://www.oss.com/asn1/dubuisson.html </url>.
</p>
- <p>Knowledge of Erlang programming is also essential and reading the book
- <em>Concurrent Programming in ERLANG</em>,
- [<cite id="erlbook2"></cite>], is recommended. Part 1 of this is available on the web in
- <url href="http://www.erlang.org/download/erlang-book-part1.pdf">PDF</url> format.
- </p>
</section>
<section>
<title>Capability</title>
<p>This application covers all features of ASN.1 up to the 1997
- edition of the specification. In the 2002 edition some new
- extensions came up of which there are support only for some of
- them. ECN (Cncoding Control Notation) and XML notation are still
- unsupported. Though, the other features of 2002 edition are
+ edition of the specification. In the 2002 edition of ASN.1 a number of
+ new features where introduced of which some are supported while
+ others are not. For example the
+ ECN (Encoding Control Notation) and XML notation are still
+ unsupported. Though, the other features of the 2002 edition are
fully or partly supported as shown below:</p>
<list type="bulleted">
<item>
@@ -308,7 +315,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
<p>Choice of encoding rules, if omitted <c>ber</c> is the
default. The <c>ber_bin</c> and <c>per_bin</c> options
allows for optimizations and are therefore recommended
- instaed of the <c>ber</c> and <c>per</c> options.</p>
+ instead of the <c>ber</c> and <c>per</c> options.</p>
</item>
<tag><c>-o OutDirectory</c></tag>
<item>
@@ -629,7 +636,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
<c>driver</c> options does not affect the encode or decode
result, just the time spent in run-time. When <c>ber_bin</c> and
<c>driver</c> or <c>per_bin, optimize</c> and <c>driver</c> is
- combined the C-code driver is used in choosen parts of encode /
+ combined the C-code driver is used in chosen parts of encode /
decode procedure.
</p>
<table>
@@ -749,11 +756,11 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
you may want to continue running the old asn1 run-time
functionality.</item>
<item>Performance issues: If you have an asn1 system with a lot
- of cross references you may gain in performance. Meassurements
+ of cross references you may gain in performance. Measurements
must be done for each case.</item>
</list>
<p>You may choose either the plain multi file compilation that just
- merges the choosen asn1 specs or the <c>{inline,OutputModule}</c>
+ merges the chosen asn1 specs or the <c>{inline,OutputModule}</c>
that also includes the used asn1 run-time functionality.</p>
<p>For both cases you need to specify which asn1 specs you will
compile in a module that must have the extension
@@ -919,7 +926,7 @@ 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 \011<c>Named NumberList</c> (see T6 above)
+ 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>
@@ -934,7 +941,7 @@ T6value3 = white
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 NumberList.</p>
+ symbol in the Named Number List.</p>
</section>
<section>
@@ -978,8 +985,9 @@ N1 = 'NULL',
<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),
-\011wednesday(4),thursday(5),friday(6),saturday(7) }
+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>
@@ -1273,11 +1281,14 @@ Pdu ::= SEQUENCE {
<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>It is also possible to specify the value for each component in
- a SEQUENCE or a SET as <c>{ComponentName,Value}</c>. It is not
- recommended and is not supported if the flags <c>per_bin</c> or
- <c>ber_bin</c> and <c>optimize</c> were used when the module was
- compiled.</p>
+<note>
+ <p>
+ In very early versions of the asn1 compiler it was also possible to
+ specify the values of the components in
+ a SEQUENCE or a SET as a list of tuples <c>{ComponentName,Value}</c>.
+ This is no longer supported.
+ </p>
+</note>
<p>The decode functions will return a record as result when decoding
a <c>SEQUENCE</c> or a <c>SET</c>.
<marker id="DEFAULT"></marker>
@@ -1293,13 +1304,13 @@ MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}. </pre>
<p>For instance, if the following types exists in a file "File.asn":</p>
<pre>
Seq1 ::= SEQUENCE {
-\011a INTEGER DEFAULT 1,
-\011b Seq2 DEFAULT {aa TRUE, bb 15}
+ a INTEGER DEFAULT 1,
+ b Seq2 DEFAULT {aa TRUE, bb 15}
}
Seq2 ::= SEQUENCE {
-\011aa BOOLEAN,
-\011bb INTEGER
+ aa BOOLEAN,
+ bb INTEGER
}
</pre>
<p>Some values and the corresponding encoding in an Erlang terminal
@@ -1331,7 +1342,7 @@ ok
<marker id="DEFAULT DER"></marker>
</p>
<p>But, the DER encoding format has stronger requirements regarding
- default\011values both for SET and SEQUENCE. A more elaborate and time
+ default values both for SET and SEQUENCE. A more elaborate and time
expensive check of default values will take place. The following is
an example with the same types and values as above but with der
encoding format.</p>
@@ -1409,7 +1420,7 @@ Bad ::= SET {i INTEGER,
values is the same for SET as for SEQUENCE, and is supported by
the compiler, <seealso marker="#DEFAULT DER">see above</seealso>.</p>
<p>Moreover, in DER the elements of a SET will be sorted. If a
- component is an untagged choice the sorting have to take place
+ component is an un-tagged choice the sorting have to take place
in run-time. This fact emphasizes the following recommendation
if DER encoding format is used.</p>
<p>The concept of SET is an unusual
@@ -1425,7 +1436,7 @@ Bad ::= SET {i INTEGER,
</section>
<section>
- <title>Notes about Extendability for SEQUENCE and SET</title>
+ <title>Notes about Extend-ability for SEQUENCE and SET</title>
<p>When a SEQUENCE or SET contains an extension marker and
extension components like this:</p>
<pre>
@@ -1498,9 +1509,9 @@ C2 ::= CHOICE {
<section>
<title>Extendable CHOICE</title>
<p>When a CHOICE contains an extension marker and the decoder detects
- an unknown alternative of the CHIOCE the value is represented as:</p>
+ an unknown alternative of the CHOICE the value is represented as:</p>
<pre>
-\011 {asn1_ExtAlt, BytesForOpenType}
+{asn1_ExtAlt, BytesForOpenType}
</pre>
<p>Where <c>BytesForOpenType</c> is a list of bytes constituting the
encoding of the "unknown" CHOICE alternative. </p>
@@ -1630,15 +1641,15 @@ V = #'Emb'{a=["qqqq",[1,2,255]],
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 recordname.</p>
+ be added to the record-name.</p>
<p>For example:</p>
<pre>
Seq ::= SEQUENCE{
- a\011CHOICE{
-\011b SEQUENCE {
-\011 c INTEGER
-\011 }
-\011}
+ a CHOICE{
+ b SEQUENCE {
+ c INTEGER
+ }
+ }
} </pre>
<p>will result in the following record:</p>
<pre>
@@ -1650,10 +1661,10 @@ Seq ::= SEQUENCE{
<pre>
Seq ::= SEQUENCE {
a SEQUENCE OF SEQUENCE {
-\011 b
+ b
}
c SET OF SEQUENCE {
-\011 d
+ d
}
} </pre>
<p>This results in the records:</p>
@@ -1802,16 +1813,16 @@ GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
<pre>
StartMessage ::= SEQUENCE {
msgId GENERAL-PROCEDURE.&amp;id ({GENERAL-PROCEDURES}),
- content GENERAL-PROCEDURE.&amp;Message\011({GENERAL-PROCEDURES}{@msgId}),
+ 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 choosen by the <c>msgId</c>
+ 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 choosen a value from a
+ 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
@@ -1831,7 +1842,7 @@ StartMessage ::= SEQUENCE {
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 typename to express the intention. This
+ purpose, one want the type-name to express the intention. This
can be done with parameterization.</p>
<p>When many types (or an other ASN.1 entity) only differs in some
minor cases, but the structure of the types are similar, only