From 70c48be27e74916dfbcee48343ede1882658832c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 06:58:48 +0100 Subject: Document the asn1_OPENTYPE wrapper --- lib/asn1/doc/src/asn1_ug.xml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index ee54fdffd7..cef7945226 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -1438,6 +1438,23 @@ StartMessage ::= SEQUENCE { in the class. The msgId field is always encoded as a PrintableString, since the field refers to a fixed type in the class.

+

In practice, object sets are usually declared to be extensible so + so that more objects can be added to the set later. Extensibility is + indicated like this:

+ 
+GENERAL-PROCEDURES GENERAL-PROCEDURE ::= {
+    object1 | object2, ...}
+

When decoding a type that uses an extensible set constraint, + there is always the possibility that the value in the UNIQUE + field is unknown (i.e. the type has been encoded with a later + version of the ASN.1 specification). When that happens, the + unencoded data will be returned wrapped in a tuple like this:

+ + 
+{asn1_OPENTYPE,Binary}
+

where Binary is an Erlang binary that contains the encoded + data. (If the option legacy_erlang_types has been given, + just the binary will be returned.)

-- cgit v1.2.3 From 3c3eeceb484079b47ce1d754eac63c5f07834225 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 06:59:59 +0100 Subject: Fix an ampersand --- lib/asn1/doc/src/asn1_ug.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index cef7945226..18aa0b1d87 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -1435,7 +1435,7 @@ StartMessage ::= SEQUENCE {

StartMessage can in the content field be encoded with a value of any type that an object in the GENERAL-PROCEDURES object set has in its NEW MESSAGE field. This field refers to a type field - in the class. The msgId field is always + &Message in the class. The msgId field is always encoded as a PrintableString, since the field refers to a fixed type in the class.

In practice, object sets are usually declared to be extensible so -- cgit v1.2.3 From ae7a4c5db89851b34ef90352d0ce7463f8e66365 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 08:14:59 +0100 Subject: Shorten the Introduction section, keeping only the essential details We can assume that anyone that reads the documentation for the Asn1 documentation already knows about ASN.1, so we don't need three paragraphs of introductory. Keep one short paragraph explaining what ASN.1 is in case a reader unfamiliar with ASN.1 stumbles upon the manual. While we are at it, reformat the paragraphs in Introduction to shorter lines that don't wrap. --- lib/asn1/doc/src/asn1_ug.xml | 104 ++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 66 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 18aa0b1d87..e39b47ff20 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -34,23 +34,25 @@

Features -

The Asn1 application provides: -

+

The Asn1 application provides:

An ASN.1 compiler for Erlang, which generates encode and decode functions to be used by Erlang programs sending and receiving ASN.1 specified data. Run-time functions used by the generated code. - The supported encoding rules are: + Support for the following encoding rules: Basic Encoding Rules (BER) - Distinguished Encoding Rules (DER), a specialized form of BER that is used in security-conscious applications. + Distinguished Encoding Rules (DER), a specialized + form of BER that is used in security-conscious + applications. - Packed Encoding Rules (PER) both the aligned and unaligned variant. + Packed Encoding Rules (PER); both the aligned and + unaligned variant. @@ -59,71 +61,41 @@
Overview -

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 - lower layers in the stack of communication protocols e.g. - TCP/IP or encapsulated within UDP packets. This way, two - different applications written in two completely different - programming languages running on different computers with - different internal representation of data can exchange - instances of structured data types (instead of exchanging - bytes or bits). This makes programming faster and easier since no code - has to be written to process the transport format of the - data. -

-

To write a network application which processes ASN.1 encoded - messages, it is prudent and sometimes essential to have a set - of off-line development tools such as an ASN.1 compiler which - can generate the encode and decode logic for the specific ASN.1 - data types. It is also necessary to combine this with some - general language-specific runtime support for ASN.1 encoding and - decoding. -

-

The ASN.1 compiler must be directed towards a target language - or a set of closely related languages. This manual describes a - compiler which is directed towards the functional language - Erlang. In order to use this compiler, familiarity with the - language Erlang is essential. Therefore, the runtime support for ASN.1 is - also closely related to the language Erlang and - consist of a number of functions, which the - compiler uses. The types in ASN.1 and how to represent - values of those types in Erlang are described in this manual. -

-

The following document is structured so that the first part describes - how to use ASN.1 compiler, and then there are descriptions of all - the primitive and constructed ASN.1 types and their representation - in Erlang, -

+

ASN.1 (Abstract Syntax Notation One) 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 any type of communication + channel. This way, two applications written in different + programming languages running on different computers with + different internal representation of data can exchange instances + of structured data types.

Prerequisites -

It is assumed that the reader is familiar with the ASN.1 notation - as documented in the standard definition [] which is - the primary text. It may also be helpful, but not necessary, - to read the standard definitions - [] [] [] - [] [].

-

A very good book explaining those reference texts is - [], free to download at - http://www.oss.com/asn1/dubuisson.html . +

It is assumed that the reader is familiar with the ASN.1 + notation as documented in the standard definition [] which is the primary text. It may also be + helpful, but not necessary, to read the standard definitions + [] [] [] [] [].

+

A good book explaining those reference texts is + [], which is free to download at + http://www.oss.com/asn1/dubuisson.html.

- Capability + Capabilities

This application covers all features of ASN.1 up to the 1997 - 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:

+ edition of the specification. In the 2002 edition of ASN.1 a + number of new features were introduced. The following features + of the 2002 edition are fully or partly supported as shown + below:

Decimal notation (e.g., "1.5e3") for REAL values. The @@ -131,7 +103,7 @@ supported.

 -

The RELATIVE-OID type for relative object identifiers are +

The RELATIVE-OID type for relative object identifiers is fully supported.

 @@ -141,16 +113,16 @@ constraint is not a PER-visible constraint.

 -

The subtype constraint by regular expressions (PATTERN) for character string types is parsed when compiling, but no further action is taken. This constraint is not a PER-visible constraint.

+

The subtype constraint by regular expressions (PATTERN) + for character string types is parsed when compiling, but no + further action is taken. This constraint is not a + PER-visible constraint.

Multiple-line comments as in C, /* ... */, are supported.

 -

It should also be added here that the encoding formats - supported are BER, DER, PER aligned - basic variant and PER unaligned basic variant.

-- cgit v1.2.3 From e3db20e7a0a9855dbf45e017db2f23eb91b914bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 08:37:48 +0100 Subject: Correct and modernize the "A First Example" section Replace "IMPLICIT TAGS" with "AUTOMATIC TAGS" since AUTOMATIC TAGS is recommended for all new ASN.1 specifications. --- lib/asn1/doc/src/asn1_ug.xml | 45 +++++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 24 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index e39b47ff20..dfa8db32dd 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -134,19 +134,17 @@ A First Example

The following example demonstrates the basic functionality used to run the Erlang ASN.1 compiler.

-

First, create a file called People.asn containing the following:

+

Create a file called People.asn containing the following:

-People DEFINITIONS IMPLICIT TAGS ::=
-
+People DEFINITIONS AUTOMATIC TAGS ::=
 BEGIN
-EXPORTS Person;
-
-Person ::= [PRIVATE 19] SEQUENCE {
-        name PrintableString,
-        location INTEGER {home(0),field(1),roving(2)},
-        age INTEGER OPTIONAL }
+  Person ::= SEQUENCE {
+    name PrintableString,
+    location INTEGER {home(0),field(1),roving(2)},
+    age INTEGER OPTIONAL
+  }
 END
-

This file (people.asn) must be compiled before it can be +

This file (People.asn) must be compiled before it can be used. The ASN.1 compiler checks that the syntax is correct and that the text represents proper ASN.1 code before generating an abstract @@ -158,14 +156,14 @@ END The following shows how the compiler can be called from the Erlang shell:

-1>asn1ct:compile("People", [ber]).
+1> asn1ct:compile("People", [ber]).
 ok
 2>

The verbose option can be given to have information about the generated files printed:

-2>asn1ct:compile("People", [ber,verbose]).
+2> asn1ct:compile("People", [ber,verbose]).
 Erlang ASN.1 compiling "People.asn" 
 --{generated,"People.asn1db"}--
 --{generated,"People.hrl"}--
@@ -173,17 +171,17 @@ Erlang ASN.1 compiling "People.asn"
 ok
 3>
-

The ASN.1 module People is now accepted and the abstract syntax tree - is saved in the People.asn1db file, the - generated Erlang code is compiled using the Erlang compiler and - loaded into the Erlang runtime system. Now there is a user interface - for encode/2 and decode/2 in the module People, - which is invoked by: -

-,),]]>

- +

The ASN.1 module People is now accepted and the + abstract syntax tree is saved in the People.asn1db file; + the generated Erlang code is compiled using the Erlang compiler + and loaded into the Erlang runtime system. Now there is an API + for encode/2 and decode/2 in the module + People, which is invoked by:

+ , )]]> +

or

-,),]]>

+, )]]>

+

Assume there is a network application which receives instances of the ASN.1 defined type Person, modifies and sends them back again:

@@ -206,8 +204,7 @@ receive constructed and encoded using 'People':encode('Person',Answer) which takes an instance of a defined ASN.1 type and transforms it to a - binary according to the BER or PER - encoding-rules. + binary according to the BER or PER encoding rules.

The encoder and the decoder can also be run from the shell.

-- cgit v1.2.3 From 70fa960771aecee7cc9c07c0786c5b5641e7ae08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 08:44:34 +0100 Subject: Remove all uses of the deprecated asn1{ct,rt}:{en,de}code/2 functions --- lib/asn1/doc/src/asn1_ug.xml | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index dfa8db32dd..fb379214fc 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -335,10 +335,6 @@ asn1ct:compile("H323-MESSAGES.asn1",[ber]). asn1ct:compile("H323-MESSAGES.asn1",[per]).

The generic encode and decode functions can be invoked like this:

-asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
-asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes).
-

Or, preferable like:

- 
 'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
 'H323-MESSAGES':decode('SomeChoiceType',Bytes).
@@ -466,7 +462,7 @@ Operational ::= BOOLEAN --ASN.1 definition

In Erlang code it may look like:

 Val = true,
-{ok,Bytes}=asn1rt:encode(MyModule,'Operational',Val),
+{ok,Bytes} = MyModule:encode('Operational', Val),

Below follows a description of how values of each type can be represented in Erlang.

@@ -731,17 +727,17 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] BMP ::= BMPString then using BER encoding (ber option)the input/output format will be:

-1> {ok,Bytes1} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,45,56}]).
+1> {ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).
 {ok,[30,4,"55-8"]}
-2> asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes1)).
+2> 'PrimStrings':decode('BMP', list_to_binary(Bytes1)).
 {ok,[{0,0,53,53},{0,0,45,56}]}
-3> {ok,Bytes2} = asn1rt:encode('PrimStrings','BMP',[{0,0,53,53},{0,0,0,65}]).
+3> {ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).
 {ok,[30,4,[53,53,0,65]]}
-4> asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes2)).
+4> 'PrimStrings':decode('BMP', list_to_binary(Bytes2)).
 {ok,[{0,0,53,53},65]}
-5> {ok,Bytes3} = asn1rt:encode('PrimStrings','BMP',"BMP string").
+5> {ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").
 {ok,[30,20,[0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103]]}
-6> asn1rt:decode('PrimStrings','BMP',list_to_binary(Bytes3)).
+6> 'PrimStrings':decode('BMP', list_to_binary(Bytes3)).
 {ok,"BMP string"}

The UTF8String is represented in Erlang as a list of integers, where each integer represents the unicode value of one -- cgit v1.2.3 From 0a633e1fa9e475e6260c35e33befc49e02f90c81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 09:43:08 +0100 Subject: Correct the PrimStrings example The decode functions now return a binary, not an iolist, so we must both change the output and remove the call to list_to_binary when decoding. --- lib/asn1/doc/src/asn1_ug.xml | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index fb379214fc..1da4cce5a9 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -720,24 +720,33 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] characters are all represented by quadruples beginning with three zeros like {0,0,0,65} for the 'A' character. When decoding a value for these strings the result is a list of - quadruples, or integers when the value is an ASCII character. - The following example shows how it works:

-

In a file PrimStrings.asn1 the type BMP is defined as -

-BMP ::= BMPString then using BER encoding (ber - option)the input/output format will be:

+ quadruples, or integers when the value is an ASCII character.

+ +

The following example shows how it works. We have the following + specification in the file PrimStrings.asn1.

+ 
+PrimStrings DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+   BMP ::= BMPString
+END
+
+ +

Encoding and decoding some strings:

+ 
-1> {ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).
-{ok,[30,4,"55-8"]}
-2> 'PrimStrings':decode('BMP', list_to_binary(Bytes1)).
+1> asn1ct:compile('PrimStrings', [ber]).
+ok
+2> {ok,Bytes1} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,45,56}]).
+{ok,<<30,4,53,54,45,56>>}
+3> 'PrimStrings':decode('BMP', Bytes1).
 {ok,[{0,0,53,53},{0,0,45,56}]}
-3> {ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).
-{ok,[30,4,[53,53,0,65]]}
-4> 'PrimStrings':decode('BMP', list_to_binary(Bytes2)).
+4> {ok,Bytes2} = 'PrimStrings':encode('BMP', [{0,0,53,53},{0,0,0,65}]).
+{ok,<<30,4,53,53,0,65>>}
+5> 'PrimStrings':decode('BMP', Bytes2).
 {ok,[{0,0,53,53},65]}
-5> {ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").
-{ok,[30,20,[0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103]]}
-6> 'PrimStrings':decode('BMP', list_to_binary(Bytes3)).
+6> {ok,Bytes3} = 'PrimStrings':encode('BMP', "BMP string").
+{ok,<<30,20,0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103>>}
+7> 'PrimStrings':decode('BMP', Bytes3).
 {ok,"BMP string"}

The UTF8String is represented in Erlang as a list of integers, where each integer represents the unicode value of one -- cgit v1.2.3 From c5651a54b7248a6100c546a1104f23db414ff8f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 10:22:48 +0100 Subject: Correct the UTF8String description and example --- lib/asn1/doc/src/asn1_ug.xml | 93 ++++++++++++++++++++++++-------------------- 1 file changed, 50 insertions(+), 43 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 1da4cce5a9..2475eaa153 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -748,51 +748,58 @@ ok {ok,<<30,20,0,66,0,77,0,80,0,32,0,115,0,116,0,114,0,105,0,110,0,103>>} 7> 'PrimStrings':decode('BMP', Bytes3). {ok,"BMP string"} -

The UTF8String is represented in Erlang as a list of integers, - where each integer represents the unicode value of one - character. When a value shall be encoded one first has to - transform it to a UTF8 encoded binary, then it can be encoded by - asn1. When decoding the result is a UTF8 encoded binary, which - may be transformed to an integer list. The transformation - functions, utf8_binary_to_list and - utf8_list_to_binary, are in the asn1rt module. In - the example below we assume an asn1 definition UTF ::= UTF8String in a module UTF.asn:

+ +

The UTF8String type is represented as a UTF-8 encoded binary in + Erlang. Such binaries can be created directly using the binary syntax + or by converting from a list of Unicode code points using the + unicode:characters_to_binary/1 function.

+ +

Here are some examples showing how UTF-8 encoded binaries can + be created and manipulated:

+ + 
+1> Gs = "Мой маленький Гном".
+[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
+ 1081,32,1043,1085,1086,1084]
+2> Gbin = unicode:characters_to_binary(Gs).
+<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
+  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
+  208,...>>
+3> Gbin = <<"Мой маленький Гном"/utf8>>.
+<<208,156,208,190,208,185,32,208,188,208,176,208,187,208,
+  181,208,189,209,140,208,186,208,184,208,185,32,208,147,
+  208,...>>
+4> Gs = unicode:characters_to_list(Gbin).
+[1052,1086,1081,32,1084,1072,1083,1077,1085,1100,1082,1080,
+ 1081,32,1043,1085,1086,1084]
+
+ +

See the unicode module + for more details.

+ +

In the following example we will use this ASN.1 specification:

-1> asn1ct:compile('UTF',[ber]).
-Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn" 
-Compiler Options: [ber]
---{generated,"UTF.asn1db"}--
---{generated,"UTF.erl"}--
+UTF DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+   UTF ::= UTF8String
+END
+
+ +

Encoding and decoding a string with Unicode characters:

+ + 
+5> asn1ct:compile('UTF', [ber]).
+ok
+6> {ok,Bytes1} = 'UTF':encode('UTF', <<"Гном"/utf8>>).
+{ok,<<12,8,208,147,208,189,208,190,208,188>>}
+7> {ok,Bin1} = 'UTF':decode('UTF', Bytes1).
+{ok,<<208,147,208,189,208,190,208,188>>}
+8> io:format("~ts\n", [Bin1]).
+Гном
 ok
-2> UTF8Val1 = "hello".
-"hello"
-3> {ok,UTF8bin1} = asn1rt:utf8_list_to_binary(UTF8Val1).
-{ok,<<104,101,108,108,111>>}
-4> {ok,B}='UTF':encode('UTF',UTF8bin1).
-{ok,[12,
-     5,
-     <<104,101,108,108,111>>]}
-5> Bin = list_to_binary(B).
-<<12,5,104,101,108,108,111>>
-6> {ok,UTF8bin1}='UTF':decode('UTF',Bin).
-{ok,<<104,101,108,108,111>>}
-7> asn1rt:utf8_binary_to_list(UTF8bin1).
-{ok,"hello"}           
-8> UTF8Val2 = [16#00,16#100,16#ffff,16#ffffff].
-[0,256,65535,16777215]
-9> {ok,UTF8bin2} = asn1rt:utf8_list_to_binary(UTF8Val2).
-{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
-10> {ok,B2} = 'UTF':encode('UTF',UTF8bin2).
-{ok,[12,
-     11,
-     <<0,196,128,239,191,191,248,191,191,191,191>>]}
-11> Bin2 = list_to_binary(B2).
-<<12,11,0,196,128,239,191,191,248,191,191,191,191>>
-12> {ok,UTF8bin2} = 'UTF':decode('UTF',Bin2).
-{ok,<<0,196,128,239,191,191,248,191,191,191,191>>}
-13> asn1rt:utf8_binary_to_list(UTF8bin2).
-{ok,[0,256,65535,16777215]}
-14>
+9> unicode:characters_to_list(Bin1). +[1043,1085,1086,1084] +
-- cgit v1.2.3 From 9058cd48435dca77d59b0010d14fb879e6ae2a9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 25 Mar 2014 13:22:49 +0100 Subject: Correct and modernize the examples for DEFAULT It turns out that the current BER back-end can recognize complex DEFAULT values, so I had to commit up with a more elaborate example to show a difference between the BER and DER back-ends. --- lib/asn1/doc/src/asn1_ug.xml | 119 ++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 65 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 2475eaa153..a16aac0e03 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -879,19 +879,31 @@ Pdu ::= SEQUENCE { 
 MyPdu = #'Pdu'{a=22,b=77.99,c={0,1,2,3,4},d='NULL'}.

The decode functions will return a record as result when decoding - a SEQUENCE or a SET. - -

-

A SEQUENCE and a SET may contain a component with a - DEFAULT key word followed by the actual value that is the - default value. In case of BER encoding it is optional to encode the - value if it equals the default value. If the application uses the - atom asn1_DEFAULT as value or if the value is a primitive value - that equals the default value the encoding omits the bytes for - this value, which is more efficient and it results in fever - bytes to send to the receiving application.

-

For instance, if the following types exists in a file "File.asn":

+ a SEQUENCE or a SET.

+ +

A SEQUENCE and a SET may contain a component + with a DEFAULT key word followed by the actual value that + is the default value. The DEFAULT keyword means that the + application doing the encoding can omit encoding of the value, + thus resulting in fewer bytes to send to the receiving + application.

+ +

An application can use the atom asn1_DEFAULT to indicate + that the encoding should be omitted for that position in + the SEQUENCE.

+ +

Depending on the encoding rules, the encoder may also compare + the given value to the default value and automatically omit the + encoding if they are equal. How much effort the encoder makes to + to compare the values depends on the encoding rules. The DER + encoding rules forbids encoding a value equal to the default value, + so it has a more thorough and time-consuming comparison than the + encoders for the other encoding rules.

+ +

In the following example we will use this ASN.1 specification:

+File DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
 Seq1 ::= SEQUENCE {
     a INTEGER DEFAULT 1,
     b Seq2 DEFAULT {aa TRUE, bb 15}
@@ -901,60 +913,37 @@ Seq2 ::= SEQUENCE {
     aa BOOLEAN,
     bb INTEGER
 }
-
-

Some values and the corresponding encoding in an Erlang terminal - is shown below:

+ +Seq3 ::= SEQUENCE { + bs BIT STRING {a(0), b(1), c(2)} DEFAULT {a, c} +} +END +

Here is an example where the BER encoder is able to omit encoding + of the default values:

-1> asn1ct:compile('File').
-Erlang ASN.1 version "1.3.2" compiling "File.asn1" 
-Compiler Options: []
---{generated,"File.asn1db"}--
---{generated,"File.hrl"}--
---{generated,"File.erl"}--
+1> asn1ct:compile('File', [ber]).
 ok
-2> 'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).
-{ok,["0",[0],[[],[]]]}
-3> lists:flatten(["0",[0],[[],[]]]).
-[48,0]
-4> 'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).
-{ok,["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]}
-5> lists:flatten(["0","\\b",[[],["\\241",[6],[[[128],[1],"\\377"],[[129],[1],[15]]]]]]).
-[48,8,161,6,128,1,255,129,1,15]
-6>
-

The result after command line 3, in the example above,shows that the - encoder omits the encoding of default values when they are specific - by asn1_DEFAULT. Line 5 shows that even primitive values that equals - the default value are detected and not encoded. But the constructed - value of component b in Seq1 is not recognized as the - default value. Checking of default values in BER is not done - in case of complex values, because it would be to expensive. - -

-

But, the DER encoding format has stronger requirements regarding - 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.

- 
-1> asn1ct:compile('File',[der]).
-Erlang ASN.1 version "1.3.2" compiling "File.asn1" 
-Compiler Options: [der]
---{generated,"File.asn1db"}--
---{generated,"File.hrl"}--
---{generated,"File.erl"}--
+2> 'File':encode('Seq1', {'Seq1',asn1_DEFAULT,asn1_DEFAULT}).
+{ok,<<48,0>>}
+3> 'File':encode('Seq1', {'Seq1',1,{'Seq2',true,15}}).
+{ok,<<48,0>>}
+ +

And here is an example with a named BIT STRING where the BER + encoder will not omit the encoding:

+ 
+4> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT).
+{ok,<<48,0>>}
+5> 'File':encode('Seq3', {'Seq3',<<16#101:3>>).
+{ok,<<48,4,128,2,5,160>>}
+ +

The DER encoder will omit the encoding for the same BIT STRING:

+ 
+6> asn1ct:compile('File', [ber,der]).
 ok
-2> 'File':encode('Seq1',{'Seq1',asn1_DEFAULT,asn1_DEFAULT}).
-{ok,["0",[0],[[],[]]]}
-3> lists:flatten(["0",[0],[[],[]]]).
-[48,0]
-4> 'File':encode('Seq1',{'Seq1',1,{'Seq2',true,15}}).
-{ok,["0",[0],[[],[]]]}
-5> lists:flatten(["0",[0],[[],[]]]).
-[48,0]
-6> 
-
-

Line 5 shows that even values of constructed types is checked and if - it equals the default value it will not be encoded.

+7> 'File':encode('Seq3', {'Seq3',asn1_DEFAULT). +{ok,<<48,0>>} +8> 'File':encode('Seq3', {'Seq3',<<16#101:3>>). +{ok,<<48,0>>}
@@ -1005,9 +994,9 @@ Bad ::= SET {i INTEGER, [].

Encoding of a SET with components with DEFAULT values behaves - similar as a SEQUENCE, see above. The DER encoding format restrictions on DEFAULT + similar as a SEQUENCE. The DER encoding format restrictions on DEFAULT values is the same for SET as for SEQUENCE, and is supported by - the compiler, see above.

+ the compiler.

Moreover, in DER the elements of a SET will be sorted. If a component is an un-tagged choice the sorting have to take place in run-time. This fact emphasizes the following recommendation -- cgit v1.2.3 From bb39f598ad77f5fc5b0e9ebd4e188f7e6f16c620 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 27 Mar 2014 10:22:25 +0100 Subject: Don't waste words describing the SET type Since the SET type is used exactly the same way as the SEQUENCE type in Erlang, we can simply say so and note that decoding will be less efficient for the BER and DER encoding rules. --- lib/asn1/doc/src/asn1_ug.xml | 66 +++----------------------------------------- 1 file changed, 4 insertions(+), 62 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index a16aac0e03..dd08eb1817 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -949,68 +949,10 @@ ok

SET -

The SET type is an unusual construct and normally the SEQUENCE - type is more appropriate to use. Set is also inefficient compared with SEQUENCE, as the components can be in any order. Hence, it must be possible - to distinguish every component in 'SET', both when - encoding and decoding a value of a type defined to be a SET. - The tags of all components must be different from each other - in order to be easily recognizable.

-

A SET may be defined as:

- 
-Pdu2 ::= SET {
-    a INTEGER,
-    b BOOLEAN,
-    c ENUMERATED {on(0),off(1)} }
-

A SET is represented as an Erlang record. - For each SEQUENCE and SET in - an ASN.1 module an Erlang record declaration is generated. For - Pdu2 above a record is defined like this:

- 
--record('Pdu2',{a, b, c}).
-

The record declarations for a module M are placed in a - separate M.hrl file.

-

Values can be assigned in Erlang as demonstrated below:

- 
-V = #'Pdu2'{a=44,b=false,c=off}.
-

The decode functions will return a record as result when decoding - a SET. -

-

The difference between SET and SEQUENCE is that the order of - the components (in the BER encoded format) is undefined for SET - and defined as the lexical order from the ASN.1 definition for - SEQUENCE. The ASN.1 compiler for Erlang will always encode a - SET in the lexical order. The decode routines can handle SET - components encoded in any order but will always return the - result as a record. Since all components of the SET must be - distinguishable both in the encoding phase as well as the - decoding phase the following type is not allowed in a module - with EXPLICIT or IMPLICIT as tag-default :

-

- 
-Bad ::= SET {i INTEGER,
-             j INTEGER }
-

The ASN.1 to Erlang compiler rejects the above type. We - shall not explain the concept of tag further here, we refer to - []. -

-

Encoding of a SET with components with DEFAULT values behaves - similar as a SEQUENCE. The DER encoding format restrictions on DEFAULT - values is the same for SET as for SEQUENCE, and is supported by - the compiler.

-

Moreover, in DER the elements of a SET will be sorted. If a - 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.

-

The concept of SET is an unusual - construct and one cannot think of one single application - where the set type is essential. (Imagine if someone - "invented'' the shuffled array in 'C') People tend to think - that 'SET' sounds nicer and more mathematical than 'SEQUENCE' - and hence use it when 'SEQUENCE' would have been more - appropriate. It is also most inefficient, since every correct - implementation of SET must always be prepared to accept the - components in any order. So, if possible use SEQUENCE instead - of SET.

+

In Erlang, the SET type is used exactly as SEQUENCE. Note + that if the BER or DER encoding rules are used, decoding a + SET is slower than decoding a SEQUENCE because the components + must be sorted.

-- cgit v1.2.3 From 7d609a59278e639ef2ea6fc621b6e40aa89a4f25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 27 Mar 2014 11:58:52 +0100 Subject: Bring information about tags up to date Since 1994 when the AUTOMATIC TAGS was introduced, ASN.1 users no long need to worry about tagging, and the following sentence no longer makes any sense: It is essential for all users of ASN.1 to understand all the details about tags. Therefore, remove the entire existing section of tags, and replace it with a shorter section explaining why we no longer need to know about tags. Remove all tags from the examples. --- lib/asn1/doc/src/asn1_ug.xml | 164 +++++++++++++++---------------------------- 1 file changed, 57 insertions(+), 107 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index dd08eb1817..ce8da39e6d 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -391,6 +391,40 @@ File3.asn

+
+ A quick note about tags + +

Tags used to be important for all users of ASN.1, because it + was necessary to manually add tags to certain constructs in order + for the ASN.1 specification to be valid. Here is an example of + an old-style specification:

+ + 
+Tags DEFINITIONS ::=
+BEGIN
+  Afters ::= CHOICE { cheese [0] IA5String,
+                      dessert [1] IA5String }
+END
+ +

Without the tags (the numbers in square brackets) the ASN.1 + compiler would refuse to compile the file.

+ +

In 1994 the global tagging mode AUTOMATIC TAGS was introduced. + By putting AUTOMATIC TAGS in the module header, the ASN.1 compiler + will automatically add tags when needed. Here is the same + specification in AUTOMATIC TAGS mode:

+ + 
+Tags DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
+  Afters ::= CHOICE { cheese IA5String,
+                      dessert IA5String }
+END
+
+ +

Tags will not be mentioned any more in this manual.

+
+
The ASN.1 Types @@ -983,47 +1017,24 @@ SExt ::= SEQUENCE { CHOICE

The CHOICE type is a space saver and is similar to the concept of a - 'union' in the C-language. As with the previous SET-type, the - tags of all components of a CHOICE need to be distinct. If - AUTOMATIC TAGS are defined for the module (which is - preferable) the tags can be omitted completely in the ASN.1 - specification of a CHOICE. -

+ 'union' in the C language.

Assume:

+SomeModuleName DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
 T ::= CHOICE {
-        x [0] REAL,
-        y [1] INTEGER,
-        z [2] OBJECT IDENTIFIER }
-
+ x REAL, + y INTEGER, + z OBJECT IDENTIFIER } +END

It is then possible to assign values:

 TVal1 = {y,17},
 TVal2 = {z,{0,1,2}},
-

A CHOICE value is always represented as the tuple +

A CHOICE value is always represented as the tuple {ChoiceAlternative, Val} where ChoiceAlternative - is an atom denoting the selected choice - alternative. -

-

It is also allowed to have a CHOICE type tagged as follow:

-

- 
-C ::= [PRIVATE 111] CHOICE {
-        C1,
-        C2 }
-
-C1 ::= CHOICE { 
-         a [0] INTEGER,
-         b [1] BOOLEAN }
-
-C2 ::= CHOICE {
-         c [2] INTEGER,
-         d [3] OCTET STRING }
-

In this case, the top type C appears to have no tags at all in - its components, however, both C1 and C2 are also defined as - CHOICE types and they have distinct tags among themselves. - Hence, the above type C is both legal and allowed. + is an atom denoting the selected choice alternative.

@@ -1104,20 +1115,23 @@ Arr2Val = ["abc",[14,34,54],"Octets"], Where Value may be a value of yet another type T2.

For example:

+EmbeddedExample DEFINITIONS AUTOMATIC TAGS ::=
+BEGIN
 B ::= SEQUENCE {
         a Arr1,
-        b [0] T }
+        b T }
 
 Arr1 ::= SET SIZE (5) OF INTEGER (4..9) 
 
 T ::= CHOICE {
-        x [0] REAL,
-        y [1] INTEGER,
-        z [2] OBJECT IDENTIFIER }
-

The above example can be assigned like this in Erlang:

+ x REAL, + y INTEGER, + z OBJECT IDENTIFIER } + END +

The SEQUENCE b can be encoded like this in Erlang:

-V2 = #'B'{a=[4,5,6,7,8], b={x,7.77}}.
-
+1> 'EmbeddedExample':encode('B', {'B',[4,5,6,7,8],{x,"7.77"}}). +{ok,<<5,56,0,8,3,55,55,55,46,69,45,50>>}
@@ -1139,8 +1153,8 @@ V2 = #'B'{a=[4,5,6,7,8], b={x,7.77}}. Emb ::= SEQUENCE { a SEQUENCE OF OCTET STRING, b SET { - a [0] INTEGER, - b [1] INTEGER DEFAULT 66}, + a INTEGER, + b INTEGER DEFAULT 66}, c CHOICE { a INTEGER, b FooType } } @@ -1211,7 +1225,7 @@ PType{T} ::= SEQUENCE{

Types may refer to themselves. Suppose:

 Rec ::= CHOICE {
-     nothing [0] NULL,
+     nothing NULL,
      something SEQUENCE {
           a INTEGER,
           b OCTET STRING,
@@ -1243,7 +1257,7 @@ tt TT ::= {a 77,b {"kalle","kula"}}
Firstly, it could be used as the value in some DEFAULT component:

 SS ::= SET {
-    s [0] OBJECT IDENTIFIER,
+    s OBJECT IDENTIFIER,
     val TT DEFAULT tt }

It could also be used from inside an Erlang program. If the above ASN.1 code was defined in ASN.1 module Values, then the ASN.1 value @@ -1402,70 +1416,6 @@ T2 ::= General{BIT STRING}

-
- Tags -

Every built-in ASN.1 type, except CHOICE and ANY have a universal tag. - This is a unique number that clearly identifies the type.

- - It is essential for all users of ASN.1 to - understand all the details about tags.

-

Tags are implicitly encoded in the BER encoding as shown below, but - are hardly not accounted for in the PER encoding. In PER tags are - used for instance to sort the components of a SET.

-

There are four different types of tags.

- - universal - -

For types whose meaning is the same in all - applications. Such as integers, sequences and so on; that is, all the built in - types.

- - application - -

For application specific types for example, the types in - X.400 Message handling service have this sort of tag.

- - private - -

For your own private types.

- - context - -

This is used to distinguish otherwise indistinguishable - types in a specific context. For example, if we have two - components of a - CHOICE type that are both INTEGER values, there is no - way for the decoder to - decipher which component was actually chosen, since both - components will be - tagged as INTEGER. When this or similar situations occur, - one or both of the components should be given a context specific - to resolve the ambiguity.

- - -

The tag in the case of the 'Apdu' type [PRIVATE 1] is encoded to a - sequence of bytes making it possible for a - decoder to look at the (initial) bytes that arrive and determine - whether the rest of the bytes must be of the type associated - with that particular sequence of bytes. This means that each - tag must be uniquely associated with only one ASN.1 - type. -

-

Immediately following the tag is a sequence of bytes - informing the decoder of the length of the instance. This is - sometimes referred to as TLV (Tag length value) encoding. - Hence, the structure of a BER encoded series of bytes is as shown in the table below.

-

- - - Tag - Len - Value - - Structure of a BER encoded series of bytes -
-
-
Encoding Rules

When the first recommendation on ASN.1 was released 1988 it was -- cgit v1.2.3 From d4e091122ceabcbd5a38d9fbe433fdcdb21b6a9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 27 Mar 2014 12:59:14 +0100 Subject: Remove the section about encoding rules The section about encoding rules serves no useful purpose. Most users already know which encoding rule to use for their specifications. The few users that have their own specification and need to decide on which encoding rule to use will need much more information. --- lib/asn1/doc/src/asn1_ug.xml | 57 -------------------------------------------- 1 file changed, 57 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index ce8da39e6d..2522333d77 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -1415,62 +1415,5 @@ T2 ::= General{BIT STRING} encode/decode functions will only be generated for T1 and T2.

- -
- Encoding Rules -

When the first recommendation on ASN.1 was released 1988 it was - accompanied with the Basic Encoding Rules, BER, as the only - alternative for encoding. - BER is a somewhat verbose protocol. It adopts a so-called TLV (type, - length, value) approach to encoding in which every element of the - encoding carries some type information, some length information and - then the value of that element. Where the element is itself - structured, then the Value part of the element is itself a series of - embedded TLV components, to whatever depth is necessary. In summary, - BER is not a compact encoding but is relatively fast and easy to - produce.

-

The DER (Distinguished Encoding Rule) encoding format was included in - the standard in 1994. It is a specialized form of BER, which gives - the encoder the option to encode some entities differently. For - instance, is the value for TRUE any octet with any bit set to one. But, - DER does not leave any such choices. The value for TRUE in the DER - case is encoded as the octet 11111111. So, the same value - encoded by two different DER encoders must result in the same bit - stream.

-

A more compact encoding is achieved with the Packed Encoding - Rules PER which was introduced together with the revised - recommendation in 1994. PER takes a rather different approach from - that taken by BER. The first difference is that the tag part in - the TLV is omitted from the encodings, and any tags in the - notation are not encoded. The potential ambiguities are resolved - as follows:

- - -

A CHOICE is encoded by first encoding a choice index which - identifies the chosen - alternative by its position in the notation.

- - -

The elements of a SEQUENCE are transmitted in textual - order. OPTIONAL or DEFAULT elements are preceded by a bit map - to identify which elements are present. After sorting the - elements of a SET in the "canonical tag order" as defined in - X.680 8.6 they are treated as a SEQUENCE regarding OPTIONAL - and DEFAULT elements. A SET is transferred in the sorted - order.

- - -

A second difference is that PER takes full account of the sub-typing - information in that the encoded bytes are affected by the constraints. - The BER encoded bytes are unaffected by the constraints. - PER uses the sub-typing information to for example omit length fields - whenever possible.

-

The run-time functions, sometimes take the constraints into account - both for BER and PER. For instance are SIZE constrained strings checked.

-

There are two variants of PER, aligned and unaligned. - In summary, PER results in compact encodings which require much more - computation to produce than BER. -

-
-- cgit v1.2.3 From b8e71bffc15a1c0a668cabb7e52a90838cba027f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Fri, 28 Mar 2014 06:33:19 +0100 Subject: Replace "extend-ability" with "extensibility" While "extendability" (without the hyphen) is an English word, "extensibility" is the established term used when talking about the extensibility of ASN.1 types. --- lib/asn1/doc/src/asn1_ug.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 2522333d77..497ea9bd2b 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -990,7 +990,7 @@ ok
- Notes about Extend-ability for SEQUENCE and SET + Notes about extensibility for SEQUENCE and SET

When a SEQUENCE or SET contains an extension marker and extension components like this:

@@ -1038,7 +1038,7 @@ TVal2 = {z,{0,1,2}},
         

 
       

-        Extendable CHOICE
+        Extensible CHOICE
         
When a CHOICE contains an extension marker and the decoder detects
           an unknown alternative of the CHOICE the value is represented as:

         
-- 
cgit v1.2.3


From e7a5051a43f9adcc564745c9c62f471fbdf253fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 
Date: Fri, 28 Mar 2014 06:39:38 +0100
Subject: Correct description of the REAL type

REAL is implemented, sort of. But real numbers must be given in
a string.
---
 lib/asn1/doc/src/asn1_ug.xml | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

(limited to 'lib/asn1/doc/src/asn1_ug.xml')

diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index 497ea9bd2b..83de80e906 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -562,20 +562,18 @@ T6value3 = white
     

       
       REAL
-      
In this version reals are not implemented. When they are, 
-        the following
-        ASN.1 type is used:

+      
The following ASN.1 type is used for real numbers:

       
 R1 ::= REAL
       

-      
Can be assigned a value in Erlang as:

+      
It can be assigned a value in Erlang as:

       
-R1value1 = 2.14,
+R1value1 = "2.14",
 R1value2 = {256,10,-2},
       

       
In the last line note that the tuple {256,10,-2} is the real number
         2.56 in a special notation, which will encode faster than simply 
-        stating the number as 2.56. The arity three tuple is 
+        stating the number as "2.56". The arity three tuple is
         {Mantissa,Base,Exponent} i.e. Mantissa * Base^Exponent.

     

 
-- 
cgit v1.2.3


From cb236e7561d77bf5ef453af284abfabe6790d8a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 
Date: Fri, 28 Mar 2014 06:51:36 +0100
Subject: Correct description of the undec_rest option

The trailing bytes returned are now always a binary. Also condense
and clean up the language.
---
 lib/asn1/doc/src/asn1_ug.xml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

(limited to 'lib/asn1/doc/src/asn1_ug.xml')

diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index 83de80e906..769d15cd02 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -298,13 +298,13 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
         
         +undec_rest
         
-          
A buffer that holds a message, being decoded may
-            also have some following bytes. Now it is possible to get
-            those following bytes returned together with the decoded
-            value. If an asn1 spec is compiled with this option a tuple
-            {ok,Value,Rest} is returned. Rest may be a
-            list or a binary. Earlier versions of the compiler ignored
-            those following bytes.

+          
A buffer that holds a message being decoded may also have
+          trailing bytes. If those trailing bytes are important they
+          can be returned along with the decoded value by compiling
+          the ASN.1 specification with the +undec_rest option.
+          The return value from the decoder will be
+          {ok,Value,Rest} where Rest is a binary
+          containing the trailing bytes.

         
         +'Any Erlc Option'
         
-- 
cgit v1.2.3


From 6df8ca5af49e5ceadbc473d2de68962cb892e8dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 
Date: Fri, 28 Mar 2014 06:43:06 +0100
Subject: Correct some spelling, grammar and punctation issues

---
 lib/asn1/doc/src/asn1_ug.xml | 44 ++++++++++++++++++++++----------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

(limited to 'lib/asn1/doc/src/asn1_ug.xml')

diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml
index 769d15cd02..297f542f40 100644
--- a/lib/asn1/doc/src/asn1_ug.xml
+++ b/lib/asn1/doc/src/asn1_ug.xml
@@ -174,7 +174,7 @@ ok
       
The ASN.1 module People is now accepted and the
       abstract syntax tree is saved in the People.asn1db file;
       the generated Erlang code is compiled using the Erlang compiler
-      and loaded into the Erlang runtime system. Now there is an API
+      and loaded into the Erlang run-time system. Now there is an API
       for encode/2 and decode/2 in the module
       People, which is invoked by: 


       , )]]>
@@ -227,7 +227,7 @@ The encoder and the decoder can also be run from
         were imported from had to be compiled before the module that
         imported. This caused problems when asn1 modules had circular
         dependencies.

-      
Now are referenced modules parsed when the compiler finds an
+      
Referenced modules are now parsed when the compiler finds an
         entity that is imported. There will not be any code generated for
         the referenced module. However, the compiled module rely on
         that the referenced modules also will be compiled.

@@ -291,8 +291,8 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
         
         +asn1config
         
-          
This functionality works together with the flags
-            ber. It enables the
+          
This functionality works together with the
+            ber option. It enables the
             specialized decodes, see the Specialized Decode chapter.
             

         
@@ -310,7 +310,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn
         
           
You may add any option to the Erlang compiler when
             compiling the generated Erlang files. Any option
-            unrecognised by the asn1 compiler will be passed to the
+            unrecognized by the asn1 compiler will be passed to the
             Erlang compiler.

         
       
@@ -354,7 +354,7 @@ asn1ct:compile("H323-MESSAGES.asn1",[per]).      

         compile time appear on the screen together with
         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.

+        be created.

       
The run-time encoders and decoders execute within a catch and
       returns {ok, Data} or
         {error, {asn1, Description}} where
@@ -365,12 +365,12 @@ asn1ct:compile("H323-MESSAGES.asn1",[per]).
- Multi File Compilation -

There are various reasons for using a multi file compilation:

+ Multi-file Compilation +

There are various reasons for using multi-file compilation:

- You want to choose name for the generated module by - any reason. Maybe you need to compile the same specs for - different encoding/decoding standards. + You want to choose the name for the generated module, + perhaps because you need to compile the same specs for + different encoding rules. You want only one resulting module.

You need to specify which asn1 specs you will @@ -733,13 +733,11 @@ O2Val = <<"must be exactly 28 chars....">>, specified for a type are especially important for PER, where they affect the encoding.

-

Please note that all the Character strings are - supported and it is possible to use the following ASN.1 type - definitions:

+

Here are some examples:

 Digs ::= NumericString (SIZE(1..3))
 TextFile ::= IA5String (SIZE(0..64000))
-

and the following Erlang assignments:

+

with corresponding Erlang assignments:

 DigsVal1 = "456",
 DigsVal2 = "123",
@@ -866,9 +864,11 @@ OidVal1 = {1,2,55},
     

       
       Object Descriptor
-      
Values of this type can be assigned a value as an ordinary string i.e.        


+      
Values of this type can be assigned a value as an ordinary string
+      like this:

 
-        "This is the value of an Object descriptor"

+      
+      "This is the value of an Object descriptor"

     

 
     

@@ -1289,8 +1289,8 @@ SS ::= SET {
     
     ASN.1 Information Objects (X.681)
     
Information Object Classes, Information Objects and Information
-      Object Sets, (in the following called classes, objects and
-      object sets respectively), are defined in the standard
+      Object Sets (in the following called classes, objects and
+      object sets respectively) are defined in the standard
       definition []. In the following only a brief
       explanation is given. 

     
These constructs makes it possible to define open types,
@@ -1407,9 +1407,9 @@ T1 ::= General{PrintableString}
 T2 ::= General{BIT STRING}

An example of a value that can be encoded as type T1 is {12,"hello"}.

-

Observe that the compiler not generates encode/decode functions for - parameterized types, only for the instances of the parameterized - types. So, if a file contains the types General{}, T1 and T2 above, +

Note that the compiler does not generate encode/decode functions for + parameterized types, but only for the instances of the parameterized + types. Therefore, if a file contains the types General{}, T1 and T2 above, encode/decode functions will only be generated for T1 and T2.

-- cgit v1.2.3 From 84c9ffdb90cc63bdd7a99be5348f49a01c1edbd6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Fri, 28 Mar 2014 07:22:37 +0100 Subject: Consistenly use ASN.1 instead of asn1 When talking about the ASN.1 standard, ASN.1 specifications, and the ASN.1 compiler, consistently use "ASN.1" instead of "asn1". --- lib/asn1/doc/src/asn1_ug.xml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'lib/asn1/doc/src/asn1_ug.xml') diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 297f542f40..020e58c615 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -221,11 +221,11 @@ The encoder and the decoder can also be run from
Module dependencies -

It is common that asn1 modules import defined types, values and - other entities from another asn1 module.

-

Earlier versions of the asn1 compiler required that modules that +

It is common that ASN.1 modules import defined types, values and + other entities from another ASN.1 module.

+

Earlier versions of the ASN.1 compiler required that modules that were imported from had to be compiled before the module that - imported. This caused problems when asn1 modules had circular + imported. This caused problems when ASN.1 modules had circular dependencies.

Referenced modules are now parsed when the compiler finds an entity that is imported. There will not be any code generated for @@ -279,7 +279,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn -I IncludeDir -

Where to search for .asn1db files and asn1 +

Where to search for .asn1db files and ASN.1 source specs in order to resolve references to other modules. This option can be repeated many times if there are several places to search in. The compiler will always @@ -310,7 +310,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

You may add any option to the Erlang compiler when compiling the generated Erlang files. Any option - unrecognized by the asn1 compiler will be passed to the + unrecognized by the ASN.1 compiler will be passed to the Erlang compiler.

@@ -373,10 +373,10 @@ asn1ct:compile("H323-MESSAGES.asn1",[per]). different encoding rules. You want only one resulting module. -

You need to specify which asn1 specs you will +

You need to specify which ASN.1 specs you will compile in a module that must have the extension .set.asn. You chose name of the module and provide the - names of the asn1 specs. For instance, if you have the specs + names of the ASN.1 specs. For instance, if you have the specs File1.asn, File2.asn and File3.asn your module MyModule.set.asn will look like:

@@ -387,7 +387,7 @@ File3.asn
~> erlc MyModule.set.asn

the result will be one merged module MyModule.erl with - the generated code from the three asn1 specs. + the generated code from the three ASN.1 specs.

@@ -1135,7 +1135,7 @@ T ::= CHOICE {
Naming of Records in .hrl Files -

When an asn1 specification is compiled all defined types of +

When an ASN.1 specification is compiled all defined types of type SET or SEQUENCE will result in a corresponding record in the generated hrl file. This is because the values for SET/SEQUENCE as mentioned in sections above are represented as records.

-- cgit v1.2.3