1asn1ct(3) Erlang Module Definition asn1ct(3)
2
6 asn1ct - ASN.1 compiler and compile-time support functions
7
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 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 To revert to the old representation of the types, use option
26 legacy_erlang_types.
27 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 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
42 compile(Asn1module) -> ok | {error, Reason}
43 compile(Asn1module, Options) -> ok | {error, Reason}
44 Types:
46 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 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 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 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 File1.asn
80 File2.asn
81 File3.asn
82 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 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 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 * If the definitions are identical, the output module keeps
98 only one definition with the original name.
99 * 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 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 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 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 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 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 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 For details, see Section Map representation for SEQUENCE
137 and SET in the User's Guide.
138 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 For details, see Section BIT STRING in the User's Guide.
145 This option implies option legacy_erlang_types.
147 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 For details, see Section BIT STRING in the User's Guide
155 This option implies option legacy_erlang_types.
157 legacy_erlang_types:
159 Use the same Erlang types to represent BIT STRING and OCTET
160 STRING as in OTP R16.
161 For details, see Section BIT STRING and Section OCTET STRING
163 in the User's Guide.
164 This option is not recommended for new code. This option
166 cannot be combined with the option maps.
167 {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 If EnumTypeName does not exist in the ASN.1 specification,
176 the compilation stops with an error code.
177 The generated conversion functions are named name2num_Enum‐
179 TypeName/1 and num2name_EnumTypeName/1.
180 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 {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 {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 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 For instructions for exclusive decode, see Section Exclusive
207 Decode in the User's Guide.
208 For instructions for selective decode, see Section Selective
210 Decode in the User's Guide.
211 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 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 {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 {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 verbose:
237 Causes more verbose information from the compiler describing
238 what it is doing.
239 warnings_as_errors:
241 Causes warnings to be treated as errors.
242 Any more option that is applied is passed to the final step when
244 the generated .erl file is compiled.
245 The compiler generates the following files:
247 * Asn1module.hrl (if any SET or SEQUENCE is defined)
249 * Asn1module.erl - Erlang module with encode, decode, and
251 value functions
252 * Asn1module.asn1db - Intermediate format used by the compiler
254 when modules IMPORT definitions from each other.
255 value(Module, Type) -> {ok, Value} | {error, Reason}
257 Types:
259 Module = Type = atom()
261 Value = term()
262 Reason = term()
263 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 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 test(Module) -> ok | {error, Reason}
279 test(Module, Type | Options) -> ok | {error, Reason}
280 test(Module, Type, Value | Options) -> ok | {error, Reason}
281 Types:
283 Module = Type = atom()
285 Value = term()
286 Options = [{i, IncludeDir}]
287 Reason = term()
288 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 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 * test/1 iterates over all types in Module.
306 * test/2 tests type Type with a random value.
308 * test/3 tests type Type with Value.
310 Schematically, the following occurs for each type in the module:
312 {ok, Value} = asn1ct:value(Module, Type),
314 {ok, Bytes} = Module:encode(Type, Value),
315 {ok, Value} = Module:decode(Type, Bytes).
316 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.
322Ericsson AB asn1 5.0.5.2 asn1ct(3)