From 058eba7c2f6661bac25eeacfb97e53fda162d141 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 15 Nov 2012 09:34:06 +0100 Subject: Update documentation for the asn1 application --- lib/asn1/doc/src/asn1_ug.xml | 389 ++++--------------------------------------- 1 file changed, 33 insertions(+), 356 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 09b9e7315a..6cb251c3e2 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -186,13 +186,21 @@ END The following shows how the compiler can be called from the Erlang shell:

-1>asn1ct:compile("People",[ber_bin]).
+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]).
 Erlang ASN.1 compiling "People.asn" 
 --{generated,"People.asn1db"}--
 --{generated,"People.hrl"}--
 --{generated,"People.erl"}--
 ok
-2>
+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 @@ -229,7 +237,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 - (possibly) nested list of bytes according to the BER or PER + binary according to the BER or PER encoding-rules.

The encoder and the decoder can also be run from @@ -239,24 +247,12 @@ The encoder and the decoder can also be run from 

 2> Rockstar = {'Person',"Some Name",roving,50}.
 {'Person',"Some Name",roving,50}
-3> {ok,Bytes} = asn1rt:encode('People','Person',Rockstar).
-{ok,[<<243>>,
-     [17],
-     [19,9,"Some Name"],
-     [2,1,[2]],
-     [2,1,"2"]]}
-4> Bin = list_to_binary(Bytes).
-<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,2,1,50>>
-5> {ok,Person} = asn1rt:decode('People','Person',Bin).
+3> {ok,Bin} = asn1rt:encode('People','Person',Rockstar).
+{ok,<<243,17,19,9,83,111,109,101,32,78,97,109,101,2,1,2,
+      2,1,50>>}
+4> {ok,Person} = asn1rt:decode('People','Person',Bin).
 {ok,{'Person',"Some Name",roving,50}}
-6>
-

Notice that the result from encode is a nested list which - must be turned into a binary before the call to decode. A - binary is necessary as input to decode since the module was compiled - with the ber_bin option - The reason for returning a nested list is that it is faster to produce - and the list_to_binary operation is - performed automatically when the list is sent via the Erlang port mechanism.

+5>
@@ -305,17 +301,15 @@ The encoder and the decoder can also be run from ASN.1 compiler:

 erlc Person.asn
-erlc -bper_bin Person.asn
-erlc -bber_bin +optimize ../Example.asn
+erlc -bper Person.asn
+erlc -bber ../Example.asn
 erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

The useful options for the ASN.1 compiler are:

- -b[ber | per | ber_bin | per_bin | uper_bin] + -b[ber | per | uper]

Choice of encoding rules, if omitted ber is the - default. The ber_bin and per_bin options - allows for optimizations and are therefore recommended - instead of the ber and per options.

+ default.

 -o OutDirectory @@ -339,42 +333,12 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn +der -

DER encoding rule. Only when using -ber or - -ber_bin option.

- - +optimize - -

This flag has effect only when used together with one of - per_bin or ber_bin flags. It gives time optimized - code in the generated modules and it uses another runtime module. - In the per_bin case a nif is used. The - result from an encode is a binary.

-

When this flag is used you cannot use the old format{TypeName,Value} when you encode values. Since it is - an unnecessary construct it has been removed in favor of - performance. It - is neither admitted to construct SEQUENCE or SET component values - with the format {ComponentName,Value} since it also is - unnecessary. The only case were it is necessary is in a CHOICE, - were you have to pass values to the right component by specifying - {ComponentName,Value}. See also about - {Typename,Value} below - and in the sections for each type.

- - +driver - -

As of R15B this means the same as the nif option. Kept for - backwards compatability reasons.

- - +nif - -

Together with the flags ber_bin - and optimize you choose to use a nif for considerable - faster encode and decode.

+

DER encoding rule. Only when using -ber option.

 +asn1config

This functionality works together with the flags - ber_bin and optimize. You enables the + ber. It enables the specialized decodes, see the Specialized Decode chapter.

@@ -413,7 +377,6 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

For a complete description of erlc see Erts Reference Manual.

-

For preferred option use see Preferred Option Use section.

The compiler and other compile-time functions can also be invoked from the Erlang shell. Below follows a brief description of the primary functions, for a @@ -429,9 +392,9 @@ asn1ct:compile("H323-MESSAGES.asn1").

which equals:

 asn1ct:compile("H323-MESSAGES.asn1",[ber]).
-

If one wants PER encoding with optimizations:

+

If one wants PER encoding:

-asn1ct:compile("H323-MESSAGES.asn1",[per_bin,optimize]).
+asn1ct:compile("H323-MESSAGES.asn1",[per]).

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

 asn1ct:encode('H323-MESSAGES','SomeChoiceType',{call,"octetstring"}).
@@ -442,269 +405,6 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes).
'H323-MESSAGES':decode('SomeChoiceType',Bytes).
-
- - Preferred Option Use -

- It may not be obvious which compile options best fit a - situation. This section describes the format of the result of - encode and decode. It also gives some performance statistics - when using certain options. Finally there is a recommendation - which option combinations should be used. -

-

- The default option is ber. It is the same backend as - ber_bin except that the result of encode is transformed - to a flat list. Below is a table that gives the different - formats of input and output of encode and decode using the - allowed combinations of coding and optimization - options: (EAVF stands for how ASN1 values are represented in - Erlang which is described in the ASN1 Types chapter) -

- - - Encoding Rule - Compile options, allowed combinations - encode input - encode output - decode input - decode output - - - BER - [ber] (default) - EAVF - flat list - flat list / binary - EAVF - - - BER - [ber_bin] - EAVF - iolist - binary - EAVF - - - BER - [ber_bin, optimize] - EAVF - iolist - binary - EAVF - - - BER - [ber_bin, optimize, nif] - EAVF - iolist - iolist / binary - EAVF - - - PER aligned variant - [per] - EAVF - flat list - flat list - EAVF - - - PER aligned variant - [per_bin] - EAVF - iolist / binary - binary - EAVF - - - PER aligned variant - [per_bin, optimize] - EAVF - binary - binary - EAVF - - - PER unaligned variant - [uper_bin] - EAVF - binary - binary - EAVF - - - - DER - [(ber), der] - EAVF - flat list - flat list / binary - EAVF - - - DER - [ber_bin, der] - EAVF - iolist - binary - EAVF - - - DER - [ber_bin, optimize, der] - EAVF - iolist - binary - EAVF - - - DER - [ber_bin, optimize, nif, der] - EAVF - iolist - binary - EAVF - - - - The output / input formats for different combinations of compile options. -
-

- Encode / decode speed comparison in one user case for the above - alternatives (except DER) is showed in the table below. The - DER alternatives are slower than their corresponding - BER alternative. -

- - - - compile options - encode time - decode time - - - [ber] - 120 - 162 - - - [ber_bin] - 124 - 154 - - - [ber_bin, optimize] - 50 - 78 - - - [ber_bin, optimize, driver] - 50 - 62 - - - [per] - 141 - 133 - - - [per_bin] - 125 - 123 - - - [per_bin, optimize] - 77 - 72 - - - [uper_bin] - 97 - 104 - - - One example of difference in speed for the compile option alternatives. - -
- -

- The compile options ber, per and - driver are kept for backwards compatibility and should not be - used in new code. The nif implementation which replaces the linked-in - driver has been shown to be about 5-15% faster. -

-

- You are strongly recommended to use the appropriate alternative - of the bold typed options. The optimize and - nif options does not affect the encode or decode - result, just the time spent in run-time. When ber_bin and - nif or per_bin and optimize is - combined the C-code nif is used in chosen parts of encode / - decode procedure. -

- - - Compile options, allowed combinations - use of nif - - - [ber] - no - - - [ber_bin] - no - - - [ber_bin, optimize] - no - - - [ber_bin, optimize, nif] - yes - - - [per] - no - - - [per_bin] - no - - - [per_bin, optimize] - yes - - - [uper_bin] - no - - - - [(ber), der] - no - - - [ber_bin, der] - no - - - [ber_bin, optimize, der] - no - - - [ber_bin, optimize, nif, der] - yes - - - - When the ASN1 nif is used. -
- -
Run-time Functions

A brief description of the major functions is given here. For a @@ -719,9 +419,9 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). 'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}). 'H323-MESSAGES':decode('SomeChoiceType',Bytes).

The asn1 nif is enabled in two occasions: encoding of - asn1 values when the asn1 spec is compiled with per_bin and - optimize or decode of encoded asn1 values when the asn1 spec is - compiled with ber_bin, optimize and nif. In + asn1 values when the asn1 spec is compiled with per and + or decode of encoded asn1 values when the asn1 spec is + compiled with ber. In those cases the nif will be loaded automatically at the first call to encode/decode. If one doesn't want the performance overhead of the nif being loaded at the first call it is possible @@ -868,26 +568,6 @@ Operational ::= BOOLEAN --ASN.1 definition 

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

For historical reasons it is also possible to assign ASN.1 values - in Erlang using a tuple notation - with type and value as this

- 
-Val = {'Operational',true}
- - -

The tuple notation, {Typename, Value} is only kept - because of backward compatibility and may be withdrawn in a - future release. If the notation is used the Typename - element must be spelled correctly, otherwise a run-time error - will occur. -

-

If the ASN.1 module is compiled with the flags - per_bin or ber_bin and optimize it is not - allowed to use the tuple notation. That possibility has been - removed due to performance reasons. Neither is it allowed to - use the {ComponentName,Value} notation in case of a - SEQUENCE or SET type.

-

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

@@ -1149,7 +829,7 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....] 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_bin +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}]).
@@ -1174,9 +854,9 @@ TextFileVal2 = [88,76,55,44,99,121 .......... a lot of characters here ....]
         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:

       
-1> asn1ct:compile('UTF',[ber_bin]).
+1> asn1ct:compile('UTF',[ber]).
 Erlang ASN.1 version "1.4.3.3" compiling "UTF.asn" 
-Compiler Options: [ber_bin]
+Compiler Options: [ber]
 --{generated,"UTF.asn1db"}--
 --{generated,"UTF.erl"}--
 ok
@@ -1731,12 +1411,9 @@ SS ::= SET {
 1> Val = 'Values':tt().
 {'TT',77,["kalle","kula"]}
 2> {ok,Bytes} = 'Values':encode('TT',Val).
-{ok,["0",
-     [18],
-     [[[128],[1],"M"],["\\241","\\r",[[[4],[5],"kalle"],[[4],[4],"kula"]]]]]}
-3> FlatBytes = lists:flatten(Bytes).
-[48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,107,117,108,97]
-4> 'Values':decode('TT',FlatBytes).
+{ok,<<48,18,128,1,77,161,13,4,5,107,97,108,108,101,4,4,
+      107,117,108,97>>}
+4> 'Values':decode('TT',Bytes).
 {ok,{'TT',77,["kalle","kula"]}}
 5>
     

-- 
cgit v1.2.3