aboutsummaryrefslogtreecommitdiffstats
path: root/lib/asn1/doc/src/asn1ct.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/asn1/doc/src/asn1ct.xml')
-rw-r--r--lib/asn1/doc/src/asn1ct.xml128
1 files changed, 42 insertions, 86 deletions
diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml
index 3be58cbc8e..f04bac9fec 100644
--- a/lib/asn1/doc/src/asn1ct.xml
+++ b/lib/asn1/doc/src/asn1ct.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1997</year><year>2012</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -41,6 +41,19 @@
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>
+ <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
+ are no longer necessary (and the ASN.1 compiler will print a
+ warning if they are used). The options <c>ber_bin</c>, <c>per_bin</c>,
+ 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.
+ The <c>encode/2</c> function for the BER back-end used to return
+ an iolist.</p>
+ </note>
</description>
<funcs>
<func>
@@ -50,9 +63,10 @@
<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 |
- nif | asn1config | undec_rest | {inline, OutputName} | inline |
+ <v>Option = ber | per | uper | der | compact_bit_string |
+ legacy_bit_string |
+ noobj | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} |
+ asn1config | undec_rest |
{macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose | warnings_as_errors</v>
<v>OldOption = ber | per</v>
<v>Reason = term()</v>
@@ -107,12 +121,10 @@ File3.asn </pre>
<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:
+ Available options are:
</p>
<taglist>
- <tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag>
+ <tag><c>ber | per | uper</c></tag>
<item>
<p>
The encoding rule to be used. The supported encoding rules
@@ -120,23 +132,12 @@ File3.asn </pre>
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>
@@ -144,7 +145,7 @@ File3.asn </pre>
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.
+ with the <c>ber</c> option.
This option
sometimes adds sorting and value checks when encoding, which
implies a slower encoding. The decoding routines are the same
@@ -154,22 +155,26 @@ File3.asn </pre>
<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:
+ The BIT STRING type will be decoded to the "compact notation".
+ <em>This option is not recommended for new code.</em>
+ </p>
+ <p>For details see
+ <seealso marker="asn1_ug#BIT STRING">
+ BIT STRING type section in the Users Guide
+ </seealso>.
</p>
- <pre>
-BitString = {Unused, Binary},
-Unused = integer(),
-Binary = binary()
- </pre>
+ </item>
+ <tag><c>legacy_bit_string</c></tag>
+ <item>
<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
+ The BIT STRING type will be decoded to the legacy
+ format, i.e. a list of zeroes and ones.
+ <em>This option is not recommended for new code.</em>
+ </p>
+ <p>For details see
<seealso marker="asn1_ug#BIT STRING">
- BIT STRING type section in users guide
- </seealso>.
+ BIT STRING type section in the Users Guide
+ </seealso>.
</p>
</item>
<tag><c>{n2n, EnumTypeName}</c></tag>
@@ -206,28 +211,6 @@ Binary = binary()
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 nif. 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>As of R15B this means the same as the <c>nif</c> option. Kept for
- backwards compatability reasons.</p>
- </item>
- <tag><c>nif</c></tag>
- <item>
- <p>Option valid together with <c>ber_bin</c> and <c>optimize</c>
- options. It enables the use of several nifs that gives faster
- encode and decode. Nifs are only enabled by the explicit use of
- the option <c>nif</c></p>
- </item>
<tag><c>asn1config</c></tag>
<item>
<p>When one of the specialized decodes, exclusive or
@@ -255,32 +238,6 @@ Binary = binary()
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>
- <p>When used together with <c>nif</c> for <c>ber_bin</c>, the
- asn1 nifs will be used if the <c>asn1rt_nif</c> module is
- available. If it is not available, a slower erlang fallback
- will be used.</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
@@ -327,13 +284,12 @@ Binary = binary()
<type>
<v>Module = Type = atom()</v>
<v>Value = term()</v>
- <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+ <v>Bytes = binary()</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
+ <c>Module</c>. 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
@@ -348,10 +304,10 @@ Binary = binary()
<type>
<v>Module = Type = atom()</v>
<v>Value = Reason = term()</v>
- <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+ <v>Bytes = binary()</v>
</type>
<desc>
- <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes
+ <p>Decodes <c>Type</c> from <c>Module</c> from the binary
<c>Bytes</c>. Returns <c>{ok, Value}</c> if successful.</p>
</desc>
</func>