diff options
Diffstat (limited to 'lib/asn1/doc/src')
| -rw-r--r-- | lib/asn1/doc/src/asn1_spec.xmlsrc | 4 | ||||
| -rw-r--r-- | lib/asn1/doc/src/asn1_ug.xml | 142 | ||||
| -rw-r--r-- | lib/asn1/doc/src/asn1ct.xml | 33 | ||||
| -rw-r--r-- | lib/asn1/doc/src/asn1rt.xml | 32 | ||||
| -rw-r--r-- | lib/asn1/doc/src/book.xml | 4 | ||||
| -rw-r--r-- | lib/asn1/doc/src/fascicules.xml | 2 | ||||
| -rw-r--r-- | lib/asn1/doc/src/notes.xml | 2 | ||||
| -rw-r--r-- | lib/asn1/doc/src/part.xml | 4 | ||||
| -rw-r--r-- | lib/asn1/doc/src/ref_man.xml | 4 |
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,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2, 2,1,50>>} -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 = <<0:1,1:1,0:1,1:1,1:1>>, -Bits1Val2 = 16#1A, -Bits1Val3 = {3,<<0:1,1:1,0:1,1:1,1:1,0:3>>}, -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 = <<2#1110:4>>, 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 = <<17,13,19,20,0,0,255,254>>, +O2Val = <<"must be exactly 28 chars....">>,</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> |