From e95095457c4d83c02850b811fb28711c0b3d1c23 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update asn1 documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson. --- lib/asn1/doc/src/asn1ct.xml | 316 +++++++++++++++++++++++--------------------- 1 file changed, 163 insertions(+), 153 deletions(-) (limited to 'lib/asn1/doc/src/asn1ct.xml') diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index 32ff2d52cf..4e0bf055fc 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -35,43 +35,45 @@ ASN.1 compiler and compile-time support functions

The ASN.1 compiler takes an ASN.1 module as input and generates a - corresponding Erlang module which can encode and decode the data-types - specified. Alternatively the compiler takes a specification module - (se below) specifying all input modules and generates one module with - 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).

+ corresponding Erlang module, which can encode and decode the specified + data types. Alternatively, the compiler takes a specification module + specifying all input modules, and generates a module with + encode/decode functions. In addition, some generic functions + can be used during development of applications that 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. Also, an undecoded open type will now be wrapped in - a asn1_OPENTYPE tuple. For details see BIT STRING, OCTET STRING, and - ASN.1 Information Objects in User's Guide.

-

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

+

By default in OTP 17, the representation of the BIT STRING + and OCTET STRING types as Erlang terms were changed. BIT + STRING values are now Erlang bit strings and OCTET STRING + values are binaries. Also, an undecoded open type is now wrapped in + an asn1_OPENTYPE tuple. For details, see BIT STRING, OCTET STRING, and + ASN.1 Information Objects in the User's Guide.

+

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

 + -

In R16, the options have been simplified. The back-end is chosen +

In OTP R16, the options were 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. + Options optimize, nif, and driver options + are no longer necessary (and the ASN.1 compiler generates a + warning if they are used). Options ber_bin, per_bin, + and uper_bin options still work, but generates a warning.

-

Another change in R16 is that the generated encode/2 - function always returns a binary. - The encode/2 function for the BER back-end used to return - an iolist.

+

Another change in OTP R16 is that the generated function + encode/2 always returns a binary. Function encode/2 + for the BER back end used to return an iolist.

 + compile(Asn1module) -> ok | {error, Reason} compile(Asn1module, Options) -> ok | {error, Reason} - Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER. + Compiles an ASN.1 module and generates encode/decode functions according to encoding rules BER or PER. Asn1module = atom() | string() Options = [Option| OldOption] @@ -85,79 +87,82 @@ Prefix = string() -

Compiles the ASN.1 module Asn1module and generates an - Erlang module Asn1module.erl with encode and decode +

Compiles the ASN.1 module Asn1module and generates + an Erlang module Asn1module.erl with encode and decode functions for the types defined in Asn1module. For each - ASN.1 value defined in the module an Erlang function which + ASN.1 value defined in the module, an Erlang function that returns the value in Erlang representation is generated.

-

If Asn1module is a filename without extension first - ".asn1" is assumed, then ".asn" and finally +

If Asn1module is a filename without extension, first + ".asn1" is assumed, then ".asn", and finally ".py" (to be compatible with the old ASN.1 compiler). - Of course Asn1module can be a full pathname (relative or + Asn1module can be a full pathname (relative or absolute) including filename with (or without) extension.

-

If one wishes to compile a set of Asn1 modules into one - Erlang file with encode/decode functions one has to list all +

If it is needed to compile a set of ASN.1 modules into an + Erlang file with encode/decode functions, ensure to list all involved files in a configuration file. This configuration - file must have a double extension ".set.asn", (".asn" can - alternatively be ".asn1" or ".py"). The input files' names - must be listed, within quotation marks (""), one at each row + file must have a double extension ".set.asn" + (".asn" can alternatively be ".asn1" or ".py"). + List the input file names + within quotation marks (""), one at each row in the file. If the input files are File1.asn, - File2.asn and File3.asn the configuration file - shall look like:

+ File2.asn, and File3.asn, the configuration file + must look as follows:

 File1.asn
 File2.asn
-File3.asn
-

The output files will in this case get their names from the - configuration file. If the configuration file has the name - SetOfFiles.set.asn the name of the output files will be - SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db.

-

Sometimes in a system of ASN.1 modules there are different - default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The - multi file compilation resolves the default tagging as if +File3.asn +

The output files in this case get their names from the + configuration file. If the configuration file is named + SetOfFiles.set.asn, the names of the output files are + SetOfFiles.hrl, SetOfFiles.erl, and SetOfFiles.asn1db.

+

Sometimes in a system of ASN.1 modules, different + default tag modes, for example, AUTOMATIC, IMPLICIT, + or EXPLICIT. The + multi-file compilation resolves the default tagging as if the modules were compiled separately.

-

Another unwanted effect that may occur in multi file compilation - is name collisions. The compiler solves this problem in two - ways: If the definitions are identical then the output module - keeps only one definition with the original name. But if - definitions only have same name and differs in the definition, - then they will be renamed. The new names will be the definition - name and the original module name concatenated.

-

If any name collision have occurred the compiler reports a - "NOTICE: ..." message that tells if a definition was renamed, +

Name collisions is another unwanted effect that can occur in + multi file-compilation. The compiler solves this problem in one + of two ways:

+ + If the definitions are identical, the output module + keeps only one definition with the original name. + If the definitions have the same name and differs in the + definition, they are renamed. The new names are the definition + name and the original module name concatenated. + +

If a name collision occurs, the compiler reports a + "NOTICE: ..." message that tells if a definition was renamed, and the new name that must be used to encode/decode data.

- -

- Options is a list with options specific for the asn1 +

Options is a list with options specific for the ASN.1 compiler and options that are applied to the Erlang compiler. - The latter are those that not is recognized as asn1 specific. - Available options are: + The latter are not recognized as ASN.1 specific. The + available options are as follows:

ber | per | uper

The encoding rule to be used. The supported encoding rules - are BER (Basic Encoding Rules), - PER aligned (Packed Encoding Rules) and PER unaligned. - If the encoding rule option is omitted ber + are Basic Encoding Rules (BER), + Packed Encoding Rules (PER) aligned, and PER unaligned. + If the encoding rule option is omitted, ber is the default.

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. + as the ASN.1 module. Therefore, only one + encoding rule per ASN.1 module can be used at runtime.

der

- By this option the Distinguished Encoding Rules (DER) is chosen. + With 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 option. + rule. Therefore, this option only makes sense together + with option ber. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding. The decoding routines are the same @@ -167,118 +172,123 @@ File3.asn compact_bit_string

- The BIT STRING type will be decoded to the "compact notation". + The BIT STRING type is decoded to "compact notation". This option is not recommended for new code.

-

For details see - - BIT STRING type section in the Users Guide - . +

For details, see Section + + BIT STRING in the User's Guide.

-

This option implies the legacy_erlang_types option.

+

This option implies option legacy_erlang_types.

 legacy_bit_string

- The BIT STRING type will be decoded to the legacy - format, i.e. a list of zeroes and ones. + The BIT STRING type is decoded to the legacy + format, that is, a list of zeroes and ones. This option is not recommended for new code.

-

For details see - - BIT STRING type section in the Users Guide - . -

This option implies the legacy_erlang_types option.

-

+

For details, see Section + BIT STRING + in the User's Guide

+

This option implies option legacy_erlang_types.

 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.

+

Use the same Erlang types to represent BIT STRING and + OCTET STRING as in OTP R16.

+

For details, see Section BIT STRING and Section + OCTET + STRING in the User's Guide.

+

This option is not recommended for new code.

 {n2n, EnumTypeName}

- Tells the compiler to generate functions for conversion between - names (as atoms) and numbers and vice versa for the EnumTypeName specified. There can be multiple occurrences of this option in order to specify several type names. The type names must be declared as ENUMERATIONS in the ASN.1 spec. - If the EnumTypeName does not exist in the ASN.1 spec the - compilation will stop with an error code. - The generated conversion functions are named + Tells the compiler to generate functions for conversion + between names (as atoms) and numbers and conversely for + the specified EnumTypeName. There can be multiple + occurrences of this option to specify several type names. + The type names must be declared as ENUMERATIONS in + the ASN.1 specification.

+

+ If EnumTypeName does not exist in the ASN.1 specification, + the compilation stops with an error code.

+

+ The generated conversion functions are named name2num_EnumTypeName/1 and num2name_EnumTypeName/1.

noobj -

Do not compile (i.e do not produce object code) the generated - .erl file. If this option is omitted the generated Erlang module - will be compiled.

+

Do not compile (that is, do not produce object code) the + generated .erl file. If this option is omitted, the + generated Erlang module is compiled.

 {i, IncludeDir}

Adds IncludeDir to the search-path for - .asn1db and asn1 source files. The compiler tries - to open a .asn1db file when a module imports - definitions from another ASN.1 module. If no - .asn1db file is found the asn1 source file is - parsed. Several {i, IncludeDir} can be given. + .asn1db and ASN.1 source files. The compiler + tries to open an .asn1db file when a module imports + definitions from another ASN.1 module. If no + .asn1db file is found, the ASN.1 source file is + parsed. Several {i, IncludeDir} can be given.

{outdir, Dir} -

Specifies the directory Dir where all generated files - shall be placed. If omitted the files are placed in the - current directory.

+

Specifies directory Dir where all generated files + are to be placed. If this option is omitted, the files are + placed in the current directory.

 asn1config -

When one of the specialized decodes, exclusive or - selective decode, is wanted one has to give instructions in - a configuration file. The option asn1config enables - specialized decodes and takes the configuration file, which - has the same name as the ASN.1 spec but with extension - .asn1config, in concern. +

When using one of the specialized decodes, exclusive or + selective decode, instructions must be given in + a configuration file. Option asn1config enables + specialized decodes and takes the configuration file in + concern. The configuration file has + the same name as the ASN.1 specification, but with extension + .asn1config.

-

The instructions for exclusive decode must follow the - instruction and grammar in the User's Guide. +

For instructions for exclusive decode, see Section + Exclusive + Decode in the User's Guide.

-

You can also find the instructions for selective decode - in the - User's Guide. +

For instructions for selective decode, see Section + Selective + Decode in the User's Guide.

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 +

A buffer that holds a message, being decoded it can also + have some following bytes. Those following bytes can now + be returned together with the decoded value. If an + ASN.1 specification is compiled with this option, a tuple + {ok, Value, Rest} is returned. Rest can be a list or a binary. Earlier versions of the compiler ignored those following bytes.

 no_ok_wrapper -

If this option is given, the generated encode/2 - and decode/2 functions will not wrap a successful +

With this option, the generated encode/2 + and decode/2 functions do not wrap a successful return value in an {ok,...} tuple. If any error - occurs, there will be an exception.

+ occurs, an exception will be raised.

 {macro_name_prefix, Prefix}

All macro names generated by the compiler are prefixed with - Prefix. This is useful when multiple protocols that contains + Prefix. This is useful when multiple protocols that contain macros with identical names are included in a single module.

 {record_name_prefix, Prefix}

All record names generated by the compiler are prefixed with - Prefix. This is useful when multiple protocols that contains + Prefix. This is useful when multiple protocols that contain records with identical names are included in a single module.

 verbose @@ -291,27 +301,27 @@ File3.asn

Causes warnings to be treated as errors.

 -

Any additional option that is applied will be passed to - the final step when the generated .erl file is compiled. +

Any more option that is applied is passed to + the final step when the generated .erl file is compiled.

The compiler generates the following files:

- -

Asn1module.hrl (if any SET or SEQUENCE is defined)

+ Asn1module.hrl (if any SET or SEQUENCE + is defined) - -

Asn1module.erl the Erlang module with encode, decode and value functions.

+ Asn1module.erl - Erlang module with encode, decode, + and value functions - -

Asn1module.asn1db intermediate format used by the compiler when modules IMPORTS - definitions from each other.

+ Asn1module.asn1db - Intermediate format used by the + compiler when modules IMPORT definitions from each other. + encode(Module, Type, Value)-> {ok, Bytes} | {error, Reason} - Encode an ASN.1 value. + Encodes an ASN.1 value. Module = Type = atom() Value = term() @@ -319,11 +329,11 @@ File3.asn Reason = term() -

Encodes Value of Type defined in the ASN.1 module - 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 +

Encodes Value of Type defined in the ASN.1 module + Module. To get as fast execution as possible, the + encode function performs only the rudimentary tests that input + Value is a correct instance of Type. So, for example, + the length of strings is not always checked. Returns {ok, Bytes} if successful or {error, Reason} if an error occurred.

@@ -331,6 +341,7 @@ File3.asn Use Module:encode(Type, Value) instead.

 + decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason} Decode from Bytes into an ASN.1 value. @@ -346,26 +357,28 @@ File3.asn Use Module:decode(Type, Bytes) instead.

 + value(Module, Type) -> {ok, Value} | {error, Reason} - Create an ASN.1 value for test purposes. + Creates an ASN.1 value for test purposes. Module = Type = atom() Value = term() Reason = term() -

Returns an Erlang term which is an example of a valid Erlang - representation of a value of the ASN.1 type Type. The value +

Returns an Erlang term that is an example of a valid Erlang + representation of a value of the ASN.1 type Type. The value is a random value and subsequent calls to this function will for most types return different values.

 + test(Module) -> ok | {error, Reason} test(Module, Type | Options) -> ok | {error, Reason} test(Module, Type, Value | Options) -> ok | {error, Reason} - Perform a test of encode and decode for types in an ASN.1 module. + Performs a test of encode and decode for types in an ASN.1 module. Module = Type = atom() Value = term() @@ -376,9 +389,8 @@ File3.asn

Performs a test of encode and decode of types in Module. The generated functions are called by this function. This function is useful during test to secure that the generated - encode and decode functions and the general runtime support work - as expected.

- + encode and decode functions as well as the general runtime support + work as expected.

test/1 iterates over all types in Module.

@@ -390,14 +402,12 @@ File3.asn

test/3 tests type Type with Value.

 - -

Schematically the following happens for each type in the module:

+

Schematically, the following occurs for each type in the module:

{ok, Value} = asn1ct:value(Module, Type), {ok, Bytes} = asn1ct:encode(Module, Type, Value), {ok, Value} = asn1ct:decode(Module, Type, Bytes). - -

The test functions utilizes the *.asn1db files +

The test functions use the *.asn1db files for all included modules. If they are located in a different directory than the current working directory, use the include option to add paths. This is only needed when automatically -- cgit v1.2.3