1asn1ct(3)                  Erlang Module Definition                  asn1ct(3)
2
3
4

NAME

6       asn1ct - ASN.1 compiler and compile-time support functions
7

DESCRIPTION

9       The  ASN.1 compiler takes an ASN.1 module as input and generates a cor‐
10       responding Erlang module, which can encode  and  decode  the  specified
11       data  types.  Alternatively,  the compiler takes a specification module
12       specifying all input modules, and generates a module with encode/decode
13       functions.  In  addition,  some  generic  functions  can be used during
14       development of applications that handles ASN.1 data (encoded as BER  or
15       PER).
16
17   Note:
18       By  default  in  OTP 17, the representation of the BIT STRING and OCTET
19       STRING types as Erlang terms were changed. BIT STRING  values  are  now
20       Erlang bit strings and OCTET STRING values are binaries. Also, an unde‐
21       coded open type is now wrapped in an asn1_OPENTYPE tuple. For  details,
22       see  BIT  STRING,  OCTET  STRING,  and ASN.1 Information Objects in the
23       User's Guide.
24
25       To  revert  to  the  old  representation  of  the  types,  use   option
26       legacy_erlang_types.
27
28
29   Note:
30       In  OTP  R16, the options were simplified. The back end is chosen using
31       one of the options ber, per, or uper. Options optimize, nif, and driver
32       options  are  no  longer  necessary (and the ASN.1 compiler generates a
33       warning if they are  used).  Options  ber_bin,  per_bin,  and  uper_bin
34       options still work, but generates a warning.
35
36       Another  change  in  OTP  R16  is  that the generated function encode/2
37       always returns a binary. Function encode/2 for the BER back end used to
38       return an iolist.
39
40

EXPORTS

42       compile(Asn1module) -> ok | {error, Reason}
43       compile(Asn1module, Options) -> ok | {error, Reason}
44
45              Types:
46
47                 Asn1module = atom() | string()
48                 Options = [Option| OldOption]
49                 Option  =  ber  |  per  |  uper  | der | compact_bit_string |
50                 legacy_bit_string | legacy_erlang_types | noobj | {n2n, Enum‐
51                 TypeName}  |{outdir,  Dir}  |  {i, IncludeDir} | asn1config |
52                 undec_rest | no_ok_wrapper |  {macro_name_prefix,  Prefix}  |
53                 {record_name_prefix, Prefix} | verbose | warnings_as_errors
54                 OldOption = ber | per
55                 Reason = term()
56                 Prefix = string()
57
58              Compiles  the  ASN.1  module  Asn1module and generates an Erlang
59              module Asn1module.erl with encode and decode functions  for  the
60              types defined in Asn1module. For each ASN.1 value defined in the
61              module, an Erlang function that returns the value in Erlang rep‐
62              resentation is generated.
63
64              If  Asn1module is a filename without extension, first ".asn1" is
65              assumed, then ".asn", and finally ".py" (to be  compatible  with
66              the old ASN.1 compiler). Asn1module can be a full pathname (rel‐
67              ative or absolute) including filename with (or  without)  exten‐
68              sion.
69
70              If it is needed to compile a set of ASN.1 modules into an Erlang
71              file with encode/decode functions, ensure to list  all  involved
72              files in a configuration file. This configuration file must have
73              a double  extension  ".set.asn"  (".asn"  can  alternatively  be
74              ".asn1"  or  ".py").  List the input file names within quotation
75              marks (""), one at each row in the file. If the input files  are
76              File1.asn, File2.asn, and File3.asn, the configuration file must
77              look as follows:
78
79              File1.asn
80              File2.asn
81              File3.asn
82
83              The output files in this case get their names from the  configu‐
84              ration   file.   If  the  configuration  file  is  named  SetOf‐
85              Files.set.asn, the names of the output files are SetOfFiles.hrl,
86              SetOfFiles.erl, and SetOfFiles.asn1db.
87
88              Sometimes  in  a  system of ASN.1 modules, different default tag
89              modes, for example, AUTOMATIC, IMPLICIT, or EXPLICIT. The multi-
90              file  compilation resolves the default tagging as if the modules
91              were compiled separately.
92
93              Name collisions is another unwanted effect  that  can  occur  in
94              multi  file-compilation. The compiler solves this problem in one
95              of two ways:
96
97                * If the definitions are identical, the  output  module  keeps
98                  only one definition with the original name.
99
100                * If  the  definitions  have  the same name and differs in the
101                  definition, they are renamed. The new names are the  defini‐
102                  tion name and the original module name concatenated.
103
104              If a name collision occurs, the compiler reports a "NOTICE: ..."
105              message that tells if a definition was renamed, and the new name
106              that must be used to encode/decode data.
107
108              Options  is  a list with options specific for the ASN.1 compiler
109              and options that are applied to the Erlang compiler. The  latter
110              are  not recognized as ASN.1 specific. The available options are
111              as follows:
112
113                ber | per | uper:
114                  The encoding rule to be used. The supported  encoding  rules
115                  are  Basic Encoding Rules (BER), Packed Encoding Rules (PER)
116                  aligned, and PER unaligned. If the encoding rule  option  is
117                  omitted, ber is the default.
118
119                  The generated Erlang module always gets the same name as the
120                  ASN.1 module. Therefore, only one encoding  rule  per  ASN.1
121                  module can be used at runtime.
122
123                der:
124                  With  this  option the Distinguished Encoding Rules (DER) is
125                  chosen. DER is regarded as a specialized variant of the  BER
126                  encoding  rule.  Therefore,  this  option  only  makes sense
127                  together with option ber. This option sometimes adds sorting
128                  and  value  checks  when  encoding,  which  implies a slower
129                  encoding. The decoding routines are the same as for ber.
130
131                maps:
132                  This option changes the representation of the types SEQUENCE
133                  and  SET  to use maps (instead of records). This option also
134                  suppresses the generation of .hrl files.
135
136                  For details, see Section  Map  representation  for  SEQUENCE
137                  and SET in the User's Guide.
138
139                compact_bit_string:
140                  The  BIT  STRING type is decoded to "compact notation". This
141                  option is not recommended for new code. This  option  cannot
142                  be combined with the option maps.
143
144                  For details, see Section  BIT STRING in the User's Guide.
145
146                  This option implies option legacy_erlang_types.
147
148                legacy_bit_string:
149                  The  BIT  STRING  type is decoded to the legacy format, that
150                  is, a list of zeroes and ones. This  option  is  not  recom‐
151                  mended for new code. This option cannot be combined with the
152                  option maps.
153
154                  For details, see Section BIT STRING in the User's Guide
155
156                  This option implies option legacy_erlang_types.
157
158                legacy_erlang_types:
159                  Use the same Erlang types to represent BIT STRING and  OCTET
160                  STRING as in OTP R16.
161
162                  For details, see Section BIT STRING and Section OCTET STRING
163                  in the User's Guide.
164
165                  This option is not recommended for  new  code.  This  option
166                  cannot be combined with the option maps.
167
168                {n2n, EnumTypeName}:
169                  Tells  the  compiler  to  generate  functions for conversion
170                  between names (as atoms) and numbers and conversely for  the
171                  specified EnumTypeName. There can be multiple occurrences of
172                  this option to specify several type names.  The  type  names
173                  must be declared as ENUMERATIONS in the ASN.1 specification.
174
175                  If  EnumTypeName  does not exist in the ASN.1 specification,
176                  the compilation stops with an error code.
177
178                  The generated conversion functions are named  name2num_Enum‐
179                  TypeName/1 and num2name_EnumTypeName/1.
180
181                noobj:
182                  Do  not  compile  (that  is, do not produce object code) the
183                  generated .erl file. If this option is omitted,  the  gener‐
184                  ated Erlang module is compiled.
185
186                {i, IncludeDir}:
187                  Adds  IncludeDir  to  the  search-path for .asn1db and ASN.1
188                  source files. The compiler tries to  open  an  .asn1db  file
189                  when a module imports definitions from another ASN.1 module.
190                  If no .asn1db file  is  found,  the  ASN.1  source  file  is
191                  parsed. Several {i, IncludeDir} can be given.
192
193                {outdir, Dir}:
194                  Specifies  directory Dir where all generated files are to be
195                  placed. If this option is omitted, the files are  placed  in
196                  the current directory.
197
198                asn1config:
199                  When  using  one  of  the  specialized decodes, exclusive or
200                  selective decode, instructions must be given in a configura‐
201                  tion file. Option asn1config enables specialized decodes and
202                  takes the configuration file in concern.  The  configuration
203                  file  has the same name as the ASN.1 specification, but with
204                  extension .asn1config.
205
206                  For instructions for exclusive decode, see Section Exclusive
207                  Decode in the User's Guide.
208
209                  For instructions for selective decode, see Section Selective
210                  Decode in the User's Guide.
211
212                undec_rest:
213                  A buffer that holds a message, being  decoded  it  can  also
214                  have  some following bytes. Those following bytes can now be
215                  returned together with the decoded value. If an ASN.1 speci‐
216                  fication  is  compiled with this option, a tuple {ok, Value,
217                  Rest} is returned. Rest can be a list or a  binary.  Earlier
218                  versions of the compiler ignored those following bytes.
219
220                no_ok_wrapper:
221                  With  this option, the generated encode/2 and decode/2 func‐
222                  tions do not wrap a successful return value in  an  {ok,...}
223                  tuple. If any error occurs, an exception will be raised.
224
225                {macro_name_prefix, Prefix}:
226                  All  macro names generated by the compiler are prefixed with
227                  Prefix. This is useful when multiple protocols that  contain
228                  macros with identical names are included in a single module.
229
230                {record_name_prefix, Prefix}:
231                  All record names generated by the compiler are prefixed with
232                  Prefix. This is useful when multiple protocols that  contain
233                  records  with  identical names are included in a single mod‐
234                  ule.
235
236                verbose:
237                  Causes more verbose information from the compiler describing
238                  what it is doing.
239
240                warnings_as_errors:
241                  Causes warnings to be treated as errors.
242
243              Any more option that is applied is passed to the final step when
244              the generated .erl file is compiled.
245
246              The compiler generates the following files:
247
248                * Asn1module.hrl (if any SET or SEQUENCE is defined)
249
250                * Asn1module.erl - Erlang  module  with  encode,  decode,  and
251                  value functions
252
253                * Asn1module.asn1db - Intermediate format used by the compiler
254                  when modules IMPORT definitions from each other.
255
256       value(Module, Type) -> {ok, Value} | {error, Reason}
257
258              Types:
259
260                 Module = Type = atom()
261                 Value = term()
262                 Reason = term()
263
264              Returns an Erlang term that is an example of a valid Erlang rep‐
265              resentation  of  a  value of the ASN.1 type Type. The value is a
266              random value and subsequent calls to this function will for most
267              types return different values.
268
269          Note:
270              Currently, the value function has many limitations. Essentially,
271              it will mostly work for old specifications  based  on  the  1997
272              standard  for ASN.1, but not for most modern-style applications.
273              Another limitation is that the value function may  not  work  if
274              options  that  change  code  generations  strategies such as the
275              options macro_name_prefix and record_name_prefix have been used.
276
277
278       test(Module) -> ok | {error, Reason}
279       test(Module, Type | Options) -> ok | {error, Reason}
280       test(Module, Type, Value | Options) -> ok | {error, Reason}
281
282              Types:
283
284                 Module = Type = atom()
285                 Value = term()
286                 Options = [{i, IncludeDir}]
287                 Reason = term()
288
289              Performs a test of encode and decode of  types  in  Module.  The
290              generated  functions  are called by this function. This function
291              is useful during test to secure that the  generated  encode  and
292              decode  functions as well as the general runtime support work as
293              expected.
294
295          Note:
296              Currently, the test  functions  have  many  limitations.  Essen‐
297              tially,  they  will  mostly work for old specifications based on
298              the 1997 standard for  ASN.1,  but  not  for  most  modern-style
299              applications.  Another limitation is that the test functions may
300              not work if options that change code generations strategies such
301              as  the  options  macro_name_prefix  and record_name_prefix have
302              been used.
303
304
305                * test/1 iterates over all types in Module.
306
307                * test/2 tests type Type with a random value.
308
309                * test/3 tests type Type with Value.
310
311              Schematically, the following occurs for each type in the module:
312
313              {ok, Value} = asn1ct:value(Module, Type),
314              {ok, Bytes} = Module:encode(Type, Value),
315              {ok, Value} = Module:decode(Type, Bytes).
316
317              The test functions use the *.asn1db files for all included  mod‐
318              ules. If they are located in a different directory than the cur‐
319              rent working directory, use the include  option  to  add  paths.
320              This  is  only  needed when automatically generating values. For
321              static values using Value no options are needed.
322
323
324
325Ericsson AB                      asn1 5.0.5.2                        asn1ct(3)
Impressum