From d16a480a43a858d604d1ac8d644589be3f49dda1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 23 Jan 2014 17:36:57 +0100 Subject: Update documentation --- lib/asn1/doc/src/asn1_ug.xml | 90 ++++++++++++++++++++------------------------ lib/asn1/doc/src/asn1ct.xml | 25 +++++++++++- 2 files changed, 64 insertions(+), 51 deletions(-) (limited to 'lib/asn1') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 74c4aa9948..eb9f000e75 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -653,7 +653,7 @@ Day1 = saturday, Bits1 ::= BIT STRING Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)} -

There are five different notations available for representation of +

There are two notations available for representation of BIT STRING values in Erlang and as input to the encode functions.

A bitstring. By default, a BIT STRING with no @@ -661,43 +661,10 @@ Bits2 ::= BIT STRING {foo(0),bar(1),gnu(2),gnome(3),punk(14)} A list of atoms corresponding to atoms in the NamedBitList in the BIT STRING definition. A BIT STRING with symbolic names will always be decoded to this format. - 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 legacy_bit_string option - has been given. This format may be withdrawn in a future - release. - - As {Unused,Binary} where Unused denotes how - many trailing zero-bits 0 to 7 that are unused in the least - significant byte in Binary. This format is always - accepted as input to the encode functions. A BIT STRING will - be decoded to this format if compact_bit_string has - been given. This format may be withdrawn in a future - release. - - A hexadecimal number (or an integer). This format should be - avoided, since it is easy to misinterpret a BIT STRING - value in this format. This format may be withdrawn in a future - release. - - -

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. -

- +

Example:

 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]
-
-

Note that Bits1Val1, Bits1Val2, Bits1Val3, - and Bits1Val1 denote the same value.

- 
 Bits2Val1 = [gnu,punk],
 Bits2Val2 = <<2#1110:4>>,
 Bits2Val3 = [bar,gnu,gnome],
@@ -708,37 +675,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.

-      
The compact notation equivalent to the empty BIT STRING is
-        >}]]>, which in the other notations is
-	>]]>, [], or
-        0.

       
BIT STRINGS may also be sub-typed with, for example, a SIZE
         specification:

       
 Bits3 ::= BIT STRING (SIZE(0..31))      

       
This means that no bit higher than 31 can ever be set.

+
+      

+	Deprecated representations for BIT STRING
+	
In addition to the representations described above, the
+	following deprecated representations are available if the
+	specification has been compiled with the
+	legacy_erlang_types option:

+	
+	  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
+	  legacy_bit_string option has been given.
+	  
+	  As {Unused,Binary} where Unused denotes
+	  how many trailing zero-bits 0 to 7 that are unused in the
+	  least significant byte in Binary. This format is
+	  accepted as input to the encode functions, and a BIT
+	  STRING will be decoded to this format if
+	  compact_bit_string has been given.
+	  
+	  A hexadecimal number (or an integer). This format
+	  should be avoided, since it is easy to misinterpret a BIT
+	  STRING value in this format.
+	  
+	
+      

     
 
     

       
       OCTET STRING
-      
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.

+      
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.

       
It is possible to have the following ASN.1 type definitions:

       
 O1 ::= OCTET STRING
 O2 ::= OCTET STRING (SIZE(28))      

       
With the following example assignments in Erlang:

       
-O1Val = [17,13,19,20,0,0,255,254],
-O2Val = "must be exactly 28 chars....",      

-      
Observe that O1Val is assigned a series of numbers between 0 
-        and 255 i.e. octets.
-        O2Val is assigned using the string notation.
-        

+O1Val = <<17,13,19,20,0,0,255,254>>,
+O2Val = <<"must be exactly 28 chars....">>,
+

By default, an OCTET STRING is always represented as + an Erlang binary. If the specification has been compiled with + the legacy_erlang_types option, the encode functions + will accept both lists and binaries, and the decode functions + will decode an OCTET STRING to a list.

diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index ada2aace87..5871c8ad68 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -41,6 +41,17 @@ 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).

+ +

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 BIT STRING and OCTET STRING in User's + Guide.

+

To revert to the old representation of the types, use the + legacy_erlang_types option.

+

In R16, the options have been simplified. The back-end is chosen using one of the options ber, per, or uper. @@ -64,7 +75,7 @@ Asn1module = atom() | string() Options = [Option| OldOption] 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 @@ -163,6 +174,7 @@ File3.asn BIT STRING type section in the Users Guide .

+

This option implies the legacy_erlang_types option.

legacy_bit_string @@ -175,8 +187,19 @@ File3.asn BIT STRING type section in the Users Guide . +

This option implies the legacy_erlang_types option.

 + legacy_erlang_types + +

Use the same Erlang types to represent BIT STRING and + OCTET STRING as in R16. For details see BIT STRING and + OCTET + STRING in User's Guide.

+

This option is not recommended for + new code.

+ {n2n, EnumTypeName}

-- cgit v1.2.3