aboutsummaryrefslogtreecommitdiffstats
path: root/lib/asn1/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/asn1/doc')
-rw-r--r--lib/asn1/doc/src/asn1_spec.xmlsrc4
-rw-r--r--lib/asn1/doc/src/asn1_ug.xml142
-rw-r--r--lib/asn1/doc/src/asn1ct.xml33
-rw-r--r--lib/asn1/doc/src/asn1rt.xml32
-rw-r--r--lib/asn1/doc/src/book.xml4
-rw-r--r--lib/asn1/doc/src/fascicules.xml2
-rw-r--r--lib/asn1/doc/src/notes.xml2
-rw-r--r--lib/asn1/doc/src/part.xml4
-rw-r--r--lib/asn1/doc/src/ref_man.xml4
9 files changed, 112 insertions, 115 deletions
diff --git a/lib/asn1/doc/src/asn1_spec.xmlsrc b/lib/asn1/doc/src/asn1_spec.xmlsrc
index 07cba17816..9001aca65c 100644
--- a/lib/asn1/doc/src/asn1_spec.xmlsrc
+++ b/lib/asn1/doc/src/asn1_spec.xmlsrc
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>2003</year><year>2011</year>
+ <year>2003</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index 362ca9330f..ee54fdffd7 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
@@ -205,16 +205,13 @@ ok
is saved in the <c>People.asn1db</c> file, the
generated Erlang code is compiled using the Erlang compiler and
loaded into the Erlang runtime system. Now there is a user interface
- of encode/2 and decode/2 in the module People, which is invoked by:
+ for <c>encode/2</c> and <c>decode/2</c> in the module People,
+ 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> <br></br>
-
- Alternatively one can use the <c><![CDATA[asn1rt:encode(<Module name> ,<Type name>,<Value>)]]></c> and <c><![CDATA[asn1rt:decode(< Module name>,<Type name>,<Value>)]]></c> calls.
- However, they are not as efficient as the previous methods since they
- result in an additional <c>apply/3</c> call.</p>
+<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>
@@ -241,16 +238,14 @@ receive
encoding-rules.
<br></br>
The encoder and the decoder can also be run from
- the shell. The following dialogue with the shell illustrates
- how the functions
- <c>asn1rt:encode/3</c> and <c>asn1rt:decode/3</c> are used.</p>
+ the shell.</p>
<pre>
2> <input>Rockstar = {'Person',"Some Name",roving,50}.</input>
{'Person',"Some Name",roving,50}
-3> <input>{ok,Bin} = asn1rt:encode('People','Person',Rockstar).</input>
+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} = asn1rt:decode('People','Person',Bin).</input>
+4> <input>{ok,Person} = 'People':decode('Person',Bin).</input>
{ok,{'Person',"Some Name",roving,50}}
5> </pre>
</section>
@@ -279,11 +274,8 @@ The encoder and the decoder can also be run from
(including the compiler).</p>
</item>
<item>
- <p>The module <c>asn1rt</c> which provides the run-time functions.
- However, it is preferable to use the generated <c>encode/2</c> and
- <c>decode/2</c> functions in each module, ie.
- Module:encode(Type,Value), in favor of the <c>asn1rt</c>
- interface.</p>
+ <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
@@ -384,25 +376,9 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
<section>
<title>Run-time Functions</title>
- <p>A brief description of the major functions is given here. For a
- complete description of each function see
- <seealso marker="asn1rt"> the Asn1 Reference Manual</seealso>, the <c>asn1rt</c> module.</p>
- <p>The generic run-time encode and decode functions can be invoked as below:</p>
- <pre>
-asn1rt:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
-asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
- <p>Or, preferable like:</p>
- <pre>
-'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
-'H323-MESSAGES':decode('SomeChoiceType',Bytes). </pre>
- <p>The asn1 nif is enabled in two occasions: encoding of
- asn1 values when the asn1 spec is compiled with <c>per</c> and
- or decode of encoded asn1 values when the asn1 spec is
- compiled with <c>ber</c>. In
- those cases the nif will be loaded automatically at the first call
- to <c>encode</c>/<c>decode</c>. If one doesn't want the performance
- overhead of the nif being loaded at the first call it is possible
- to load the nif separately by loading the <c>asn1rt_nif</c> module.</p>
+ <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>
@@ -414,8 +390,8 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). </pre>
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 as default.</p>
- <p>The run-time encoders and decoders (in the <c>asn1rt</c> module) do
- execute within a catch and returns <c>{ok, Data}</c> or
+ <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>
@@ -653,7 +629,7 @@ Day1 = saturday,
Bits1 ::= BIT STRING
Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
</pre>
- <p>There are five different notations available for representation of
+ <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
@@ -661,43 +637,10 @@ Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)}
<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>
- <item>A list of binary digits (0 or 1). This format is always
- accepted as input to the encode functions. A BIT STRING will
- be decoded to this format if <em>legacy_bit_string</em> option
- has been given. <em>This format may be withdrawn in a future
- release.</em>
- </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 always
- accepted as input to the encode functions. A BIT STRING will
- be decoded to this format if <em>compact_bit_string</em> has
- been given. <em>This format may be withdrawn in a future
- release.</em>
- </item>
- <item>A hexadecimal number (or an integer). This format should be
- avoided, since it is easy to misinterpret a <c>BIT STRING</c>
- value in this format. <em>This format may be withdrawn in a future
- release.</em>
- </item>
</list>
- <note>
- <p>It is recommended to either use the bitstring format (for
- BIT STRINGs with no symbolic names) or a list of symbolic
- names (for BIT STRINGs with symbolic names). The other formats
- should be avoided since they may be withdrawn in a future
- release.
- </p>
- </note>
+ <p>Example:</p>
<pre>
Bits1Val1 = &lt;&lt;0:1,1:1,0:1,1:1,1:1&gt;&gt;,
-Bits1Val2 = 16#1A,
-Bits1Val3 = {3,&lt;&lt;0:1,1:1,0:1,1:1,1:1,0:3&gt;&gt;},
-Bits1Val4 = [0,1,0,1,1]
- </pre>
- <p>Note that <c>Bits1Val1</c>, <c>Bits1Val2</c>, <c>Bits1Val3</c>,
- and <c>Bits1Val1</c> denote the same value.</p>
- <pre>
Bits2Val1 = [gnu,punk],
Bits2Val2 = &lt;&lt;2#1110:4&gt;&gt;,
Bits2Val3 = [bar,gnu,gnome],
@@ -708,37 +651,60 @@ Bits2Val3 = [bar,gnu,gnome],
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>The compact notation equivalent to the empty BIT STRING is
- <c><![CDATA[{0,<<>>}]]></c>, which in the other notations is
- <c><![CDATA[<<>>]]></c>, <c>[]</c>, or
- <c>0</c>.</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>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 = [17,13,19,20,0,0,255,254],
-O2Val = "must be exactly 28 chars....", </pre>
- <p>Observe that <c>O1Val</c> is assigned a series of numbers between 0
- and 255 i.e. octets.
- <c>O2Val</c> is assigned using the string notation.
- </p>
+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>
diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml
index fcd77e9dc6..4d5a1a402a 100644
--- a/lib/asn1/doc/src/asn1ct.xml
+++ b/lib/asn1/doc/src/asn1ct.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -42,6 +42,17 @@
can be used in during development of applications which handles ASN.1
data (encoded as BER or PER).</p>
<note>
+ <p>By default in OTP 17, the representation of the BIT STRING
+ and OCTET STRING types as Erlang terms have changed. BIT
+ STRING values are now Erlang bitstrings and OCTET STRING values
+ are binaries. For details see <seealso
+ marker="asn1_ug#BIT STRING">BIT STRING</seealso> and <seealso
+ marker="asn1_ug#OCTET STRING">OCTET STRING</seealso> in User's
+ Guide.</p>
+ <p>To revert to the old representation of the types, use the
+ <c>legacy_erlang_types</c> option.</p>
+ </note>
+ <note>
<p>In R16, the options have been simplified. The back-end is chosen
using one of the options <c>ber</c>, <c>per</c>, or <c>uper</c>.
The options <c>optimize</c>, <c>nif</c>, and <c>driver</c> options
@@ -50,7 +61,7 @@
and <c>uper_bin</c> options will still work, but will print a warning.
</p>
<p>Another change in R16 is that the generated <c>encode/2</c>
- function (and <c>asn1rt:encode/3</c>) always returns a binary.
+ function always returns a binary.
The <c>encode/2</c> function for the BER back-end used to return
an iolist.</p>
</note>
@@ -64,7 +75,7 @@
<v>Asn1module = atom() | string()</v>
<v>Options = [Option| OldOption]</v>
<v>Option = ber | per | uper | der | compact_bit_string |
- legacy_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>
@@ -163,6 +174,7 @@ File3.asn </pre>
BIT STRING type section in the Users Guide
</seealso>.
</p>
+ <p>This option implies the <c>legacy_erlang_types</c> option.</p>
</item>
<tag><c>legacy_bit_string</c></tag>
<item>
@@ -175,8 +187,19 @@ File3.asn </pre>
<seealso marker="asn1_ug#BIT STRING">
BIT STRING type section in the Users Guide
</seealso>.
+ <p>This option implies the <c>legacy_erlang_types</c> option.</p>
</p>
</item>
+ <tag><c>legacy_erlang_types</c></tag>
+ <item>
+ <p>Use the same Erlang types to represent BIT STRING and
+ OCTET STRING as in R16. For details see <seealso
+ marker="asn1_ug#BIT STRING">BIT STRING</seealso> and
+ <seealso marker="asn1_ug#OCTET STRING">OCTET
+ STRING</seealso> in 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>
@@ -303,6 +326,8 @@ File3.asn </pre>
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>
@@ -316,6 +341,8 @@ File3.asn </pre>
<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>
diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml
index 2b1b108ab1..3cf56b01ca 100644
--- a/lib/asn1/doc/src/asn1rt.xml
+++ b/lib/asn1/doc/src/asn1rt.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -34,9 +34,12 @@
<module>asn1rt</module>
<modulesummary>ASN.1 runtime support functions</modulesummary>
<description>
- <p>This module is the interface module for the ASN.1 runtime support functions.
- To encode and decode ASN.1 types in runtime the functions in this module
- should be used.</p>
+ <warning>
+ <p>
+ All functions in this module are deprecated and will be
+ removed in a future release.
+ </p>
+ </warning>
</description>
<funcs>
@@ -52,6 +55,7 @@
<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>Use <c>Module:decode(Type, Bytes)</c> instead of this function.</p>
</desc>
</func>
@@ -65,16 +69,13 @@
<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 possibly nested list of bytes and or binaries
- 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. </p>
- <note>
- <p>Starting in R16, <c>Bytes</c> is always a binary.</p>
- </note>
+ <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1
+ module <c>Module</c>. Returns a binary 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. </p>
+ <p>Use <c>Module:encode(Type, Value)</c> instead of this function.</p>
</desc>
</func>
@@ -90,6 +91,7 @@
<p><c>info/1</c> returns the version of the asn1 compiler that was
used to compile the module. It also returns the compiler options
that was used.</p>
+ <p>Use <c>Module:info()</c> instead of this function.</p>
</desc>
</func>
@@ -106,6 +108,7 @@
to a list of integers, where each integer represents one
character as its unicode value. The function fails if the binary
is not a properly encoded UTF8 string.</p>
+ <p>Use <seealso marker="stdlib:unicode#characters_to_list-1">unicode:characters_to_list/1</seealso> instead of this function.</p>
</desc>
</func>
@@ -121,6 +124,7 @@
<p><c>utf8_list_to_binary/1</c> Transforms a list of integers,
where each integer represents one character as its unicode
value, to a UTF8 encoded binary.</p>
+ <p>Use <seealso marker="stdlib:unicode#characters_to_binary-1">unicode:characters_to_binary/1</seealso> instead of this function.</p>
</desc>
</func>
diff --git a/lib/asn1/doc/src/book.xml b/lib/asn1/doc/src/book.xml
index 718e6e7b17..2399267cb0 100644
--- a/lib/asn1/doc/src/book.xml
+++ b/lib/asn1/doc/src/book.xml
@@ -1,11 +1,11 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE book SYSTEM "book.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<header titlestyle="normal">
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/asn1/doc/src/fascicules.xml b/lib/asn1/doc/src/fascicules.xml
index 2488e7b57e..837b4f57f4 100644
--- a/lib/asn1/doc/src/fascicules.xml
+++ b/lib/asn1/doc/src/fascicules.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
<fascicules>
diff --git a/lib/asn1/doc/src/notes.xml b/lib/asn1/doc/src/notes.xml
index a00fc3de36..ff7962edd9 100644
--- a/lib/asn1/doc/src/notes.xml
+++ b/lib/asn1/doc/src/notes.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/lib/asn1/doc/src/part.xml b/lib/asn1/doc/src/part.xml
index 19ee64b4a0..735ec2e616 100644
--- a/lib/asn1/doc/src/part.xml
+++ b/lib/asn1/doc/src/part.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE part SYSTEM "part.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/asn1/doc/src/ref_man.xml b/lib/asn1/doc/src/ref_man.xml
index a0af1f5be3..0a0ed5416a 100644
--- a/lib/asn1/doc/src/ref_man.xml
+++ b/lib/asn1/doc/src/ref_man.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE application SYSTEM "application.dtd">
<application xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-01 21:17:35 +0000