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
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:
- -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.
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.
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").
'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)
-
- 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.
-
- 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:
diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml
index 3be58cbc8e..9a9bb7ec1b 100644
--- a/lib/asn1/doc/src/asn1ct.xml
+++ b/lib/asn1/doc/src/asn1ct.xml
@@ -41,6 +41,19 @@
encode/decode functions. There are also some generic functions which
can be used in during development of applications which handles ASN.1
data (encoded as BER or PER).
+
+
In R16, the options have been simplified. The back-end is chosen
+ using one of the options ber, per, or uper.
+ The options optimize, nif, and driver options
+ are no longer necessary (and the ASN.1 compiler will print a
+ warning if they are used). The options ber_bin, per_bin,
+ and uper_bin options will still work, but will print a warning.
+
+
Another change in R16 is that the generated encode/2
+ function (and asn1rt:encode/3) always returns a binary.
+ The encode/2 function for the BER back-end used to return
+ an iolist.
section in users guide. Available options are:
- ber | ber_bin | per | per_bin | uper_bin
+ ber | per | uper
The encoding rule to be used. The supported encoding rules
@@ -120,23 +133,12 @@ File3.asn
PER aligned (Packed Encoding Rules) and PER unaligned.
If the encoding rule option is omitted ber
is the default.
- The per_bin option means the aligned
- variant. To use the unaligned variant the uper_bin
- option has to be used.
The generated Erlang module always gets the same name
as the ASN.1 module and as a consequence of this only one
encoding rule per ASN.1 module can be used at runtime.
-
- The ber_bin and per_bin options are
- equivalent with the OldOptionsber and per
- with the difference that the generated encoding/decoding
- functions take advantage of the bit syntax, which in most
- cases increases the performance considerably. The result
- from encoding is a binary or an iolist.
-
der
@@ -144,7 +146,7 @@ File3.asn
By this option the Distinguished Encoding Rules (DER) is chosen.
DER is regarded as a specialized variant of the BER encoding
rule, therefore the der option only makes sense together
- with the ber or ber_bin option.
+ with the ber option.
This option
sometimes adds sorting and value checks when encoding, which
implies a slower encoding. The decoding routines are the same
@@ -206,28 +208,6 @@ Binary = binary()
shall be placed. If omitted the files are placed in the
current directory.
- optimize
-
-
This option is only valid together with one of the
- per_bin
- or ber_bin option. It gives time optimized code
- generated and it uses another runtime module and
- in the per_bin case a nif. The result
- in the per_bin case from an encode when compiled
- with this option will be a binary.
-
- driver
-
-
As of R15B this means the same as the nif option. Kept for
- backwards compatability reasons.
-
- nif
-
-
Option valid together with ber_bin and optimize
- options. It enables the use of several nifs that gives faster
- encode and decode. Nifs are only enabled by the explicit use of
- the option nif
- asn1config
When one of the specialized decodes, exclusive or
@@ -270,10 +250,6 @@ Binary = binary()
{export, [atom()]} or {export_all, true} option
are provided. The list of atoms are names of chosen asn1
specs from the .set.asn file.
-
When used together with nif for ber_bin, the
- asn1 nifs will be used if the asn1rt_nif module is
- available. If it is not available, a slower erlang fallback
- will be used.
inline
@@ -327,13 +303,12 @@ Binary = binary()
Module = Type = atom()Value = term()
- Bytes = [Int] when integer(Int), Int >= 0, Int =< 255
+ Bytes = binary()Reason = term()
Encodes Value of Type defined in the ASN.1 module
- Module. Returns a list of bytes if successful. To get as fast execution as
- possible the
+ Module. To get as fast execution as possible the
encode function only performs rudimentary tests that the input
Value
is a correct instance of Type. The length of strings is for example
@@ -348,10 +323,10 @@ Binary = binary()
Module = Type = atom()Value = Reason = term()
- Bytes = [Int] when integer(Int), Int >= 0, Int =< 255
+ Bytes = binary()
-
Decodes Type from Module from the list of bytes
+
Decodes Type from Module from the binary
Bytes. Returns {ok, Value} if successful.
diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml
index 0c3c257189..f2cac0c9e7 100644
--- a/lib/asn1/doc/src/asn1rt.xml
+++ b/lib/asn1/doc/src/asn1rt.xml
@@ -47,35 +47,34 @@
Module = Type = atom()Value = Reason = term()
- Bytes = binary | [Int] when integer(Int), Int >= 0, Int =< 255 | binary
+ Bytes = binary
-
Decodes Type from Module from the list of bytes or
- binary Bytes. If the module is compiled with ber_bin
- or per_bin option Bytes must be a binary.
+
Decodes Type from Module from the binary Bytes.
Returns {ok,Value} if successful.
- encode(Module,Type,Value)-> {ok,BinOrList} | {error,Reason}
+ encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}Encode an ASN.1 value.Module = Type = atom()Value = term()
- BinOrList = Bytes | binary()
- Bytes = [Int|binary|Bytes] when integer(Int), Int >= 0, Int =< 255
+ Bytes = binaryReason = term()
Encodes Value of Type defined in the ASN.1 module
Module. Returns a possibly nested list of bytes and or binaries
- if successful. If Module was compiled with the options per_bin and optimize the result is a binary. To get as
- fast execution as possible the
+ if successful. To get as fast execution as possible the
encode function only performs rudimentary tests that the input
Value
is a correct instance of Type. The length of strings is for example
not always checked.
This function is obsolete and will be removed in R16A
-
-
-
utf8_binary_to_list(UTF8Binary) -> {ok,UnicodeList} | {error,Reason}Transforms an utf8 encoded binary to a unicode list.
diff --git a/lib/asn1/doc/src/notes.xml b/lib/asn1/doc/src/notes.xml
index 5ca86130a1..72b496caf7 100644
--- a/lib/asn1/doc/src/notes.xml
+++ b/lib/asn1/doc/src/notes.xml
@@ -483,7 +483,7 @@
ENUMERATION type, the compilation will be terminated with an
error code.
Below follows an example on how to use the option from the command line with erlc:
- erlc -bper_bin +optimize +driver +"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn
+ erlc -bper+"{n2n,'CauseMisc'}" +"{n2n,'CausePcl'}" MyModyle.asn