1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
27
<prepared>Kenneth Lundin</prepared>
28
<responsible>Kenneth Lundin</responsible>
30
<approved>Kenneth Lundin</approved>
34
<file>asn1.sgml</file>
36
<module>asn1ct</module>
37
<modulesummary>ASN.1 compiler and compile-time support functions</modulesummary>
39
<p>The ASN.1 compiler takes an ASN.1 module as input and genarates a
40
corresponding Erlang module which can encode and decode the datatypes
41
specified. Alternatively the compiler takes a specification module
42
(se below) specifying all input modules and generates one module with
43
encode/decode functions. There are also some generic functions which
44
can be used in during development of applications which handles ASN.1
45
data (encoded as BER or PER).</p>
49
<name>compile(Asn1module) -> ok | {error,Reason}</name>
50
<name>compile(Asn1module , Options) -> ok | {error,Reason}</name>
51
<fsummary>Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER.</fsummary>
53
<v>Asn1module = atom() | string()</v>
54
<v>Options = [Option]</v>
55
<v>Option = ber | per | ber_bin | per_bin | uper_bin | der | compact_bit_string | noobj | {outdir,Dir} | {i,IncludeDir} | optimize | asn1config | undec_rest | {inline,OutputName} | inline</v>
56
<v>Reason = term()</v>
59
<p>Compiles the ASN.1 module <c>Asn1module</c> and generates an
60
Erlang module <c>Asn1module.erl</c> with encode and decode
61
functions for the types defined in <c>Asn1module</c>. For each
62
ASN.1 value defined in the module an Erlang function which
63
returns the value in Erlang representation is generated.</p>
64
<p>If <c>Asn1module</c> is a filename without extension first
65
<c>".asn1"</c> is assumed, then <c>".asn"</c> and finally
66
<c>".py"</c> (to be compatible with the old ASN.1 compiler).
67
Of course <c>Asn1module</c> can be a full pathname (relative or
68
absolute) including filename with (or without) extension.
69
<marker id="asn1set"></marker>
71
<p>If one wishes to compile a set of Asn1 modules into one
72
Erlang file with encode/decode functions one has to list all
73
involved files in a configuration file. This configuration
74
file must have a double extension ".set.asn", (".asn" can
75
alternatively be ".asn1" or ".py"). The input files' names
76
must be listed, within qoutation marks (""), one at each row
77
in the file. If the input files are <c>File1.asn</c>,
78
<c>File2.asn</c> and <c>File3.asn</c> the configuration file
84
<p>The output files will in this case get their names from the
85
configuration file. If the configuration file has the name
86
<c>SetOfFiles.set.asn</c> the name of the output files will be
87
<c>SetOfFiles.hrl, SetOfFiles.hrl and SetOfFiles.asn1db</c>.</p>
88
<p>Sometimes in a system of ASN.1 modules there are different
89
default tag modes, e.g. AUTOMATIC, IMPLICIT or EXPLICIT. The
90
multi file compilation resolves the default tagging as if
91
the modules were compiled separetely.</p>
92
<p>Another unwanted effect that may occure in multi file compilation
93
is name collisions. The compiler solves this problem in two
94
ways: If the definitions are identical then the output module
95
keeps only one definition with the original name. But if
96
definitions only have same name and differs in the definition,
97
then they will be renamed. The new names will be the definition
98
name and the original module name concatenated.</p>
99
<p>If any name collision have occured the compiler reports a
100
"NOTICE: ..." message that tells if a definition was renamed,
101
and the new name that must be used to encode/decode data.</p>
102
<p><c>Options</c> is a list with options specific for the asn1
103
compiler and options that are applied to the Erlang compiler.
104
The latter are those that not is recognized as asn1 specific.
105
Available options are:</p>
107
<tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag>
109
<p>The encoding rule to be used. EncodingRule is BER or
110
PER with the variants <c>aligned</c> or
111
<c>unaligned</c>. If this option is omitted <c>ber</c> is
112
the default. The <c>per</c> option means the aligned
113
variant. To use the unaligned variant the <c>uper_bin</c>
114
option has to be used.</p>
115
<p>The generated Erlang module always gets the same name
116
as the ASN.1 module and as a consequence of this only one
117
encoding rule per ASN.1 module can be used at runtime.</p>
118
<p>The <c>ber_bin</c> and <c>per_bin</c> options are
119
equivalent with the <c>ber</c> and <c>per</c> options with
120
the difference that the generated encoding/decoding
121
functions take advantage of the bit syntax, which in most
122
cases increases the performance considerably. The result
123
from encoding is a binary or a list (mayby nested) with
124
Erlang terms, including binaries.</p>
126
<tag><c>der</c></tag>
128
<p>By this option the Distinguished Encoding Rule (DER) is chosed.
129
DER is regarded as a specialized variant of the BER encoding
130
rule, therefore the <c>der</c> option only makes sense when
131
the <c>ber</c> or <c>ber_bin</c> option is used. This option
132
sometimes adds sorting and value checks when encoding, which
133
implies a slower encoding. The decoding rutines are the same
134
as for <c>ber</c>.</p>
136
<tag><c>compact_bit_string</c></tag>
138
<p>Makes it possible to use a compact notation for values
139
of the BIT STRING type in Erlang. The notation: </p>
141
BitString = {Unused,Binary},
143
Binary = binary() </pre>
144
<p><c>Unused</c> must be a number in the range 0 to 7. It
145
tells how many bits in the least significant byte in
146
<c>Binary</c> that is unused. For details see <seealso marker="asn1_ug#BIT STRING">BIT STRING type section in users guide</seealso>.</p>
148
<tag><c>{i,IncludeDir}</c></tag>
150
<p>Adds <c>IncludeDir</c> to the search-path for
151
<c>.asn1db</c> and asn1 source files. The compiler tries
152
to open a <c>.asn1db</c> file when a module imports
153
definitions from another ASN.1 module. If no
154
<c>.asn1db</c> file is found the asn1 source file is
155
parsed. Several <c>{i,IncludeDir}</c> can be given.
158
<tag><c>noobj</c></tag>
160
<p>Do not compile (i.e do not produce object code) the generated
161
<c>.erl</c> file. If this option is omitted the generated Erlang module
162
will be compiled.</p>
164
<tag><c>{outdir,Dir}</c></tag>
166
<p>Specifies the directory <c>Dir</c> where all generated files
167
shall be placed. If omitted the files are placed in the
168
current directory.</p>
170
<tag><c>optimize</c></tag>
172
<p>This option is only valid together with one of the
174
or <c>ber_bin</c> option. It gives time optimized code
175
generated and it uses another runtime module and
176
in the <c>per_bin</c> case a linked-in driver. The result
177
in the <c>per_bin</c> case from an encode when compiled
178
with this option will be a binary.</p>
180
<tag><c>driver</c></tag>
182
<p>Option valid together with <c>ber_bin</c> and <c>optimize</c>
183
options. It enables the use of a linked-in driver that gives
184
considerable faster decode. In <c>ber_bin</c> the driver is
185
enabled only by explicit use of the option <c>driver</c>.</p>
187
<tag><c>asn1config</c></tag>
189
<p>When one of the specialized decodes, exclusive or
190
selective decode, is wanted one has to give instructions in
191
a configuration file. The option <c>asn1config</c> enables
192
specialized decodes and takes the configuration file, which
193
has the same name as the ASN.1 spec but with extension
194
<c>.asn1config</c>, in concern.
196
<p>The instructions for exclusive decode must follow the
197
<seealso marker="asn1_spec#Exclusive Instruction">instruction and grammar in the User's Guide</seealso>.
199
<p>You can also find the instructions for selective decode
201
<seealso marker="asn1_spec#Selective Instruction">User's Guide</seealso>.
204
<tag><c>undec_rest</c></tag>
206
<p>A buffer that holds a message, beeing decoded may
207
also have some following bytes. Now it is possible to get
208
those following bytes returned together with the decoded
209
value. If an asn1 spec is compiled with this option a tuple
210
<c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a
211
list or a binary. Earlier versions of the compiler ignored
212
those following bytes.</p>
214
<tag><c>{inline,OutputName}</c></tag>
216
<p>Compiling with this option gives one output module
217
containing all asn1 run-time functionality. The asn1 specs
218
are provided in a target module Module.set.asn as described
219
<seealso marker="#asn1set">above</seealso>. The name of the
220
resulting module containing generated encode/decode functions
221
and inlined run-time functions will be
222
<c>OutputName.erl</c>. The merging/inlining of code is done
223
by the <c>igor</c> module of <c>syntax_tools</c>. By default
224
the functions generated from the first asn1 spec in the
225
<c>.set.asn</c> are exported, unless a
226
<c>{export,[atom()]}</c> or <c>{export_all,true}</c> option
227
are provided. The list of atoms are names of choosen asn1
228
specs from the <c>.set.asn</c> file.</p>
230
<tag><c>inline</c></tag>
232
<p>It is also possible to use the sole argument <c>inline</c>.
233
It is as <c>{inline,OutputName}</c>, but the output file gets the
234
default name of the source <c>.set.asn</c> file.</p>
237
<p>Any additional option that is applied will be passed to
238
the final step when the generated .erl file is compiled.
240
<p>The compiler generates the following files:</p>
241
<list type="bulleted">
243
<p><c>Asn1module.hrl</c> (if any SET or SEQUENCE is defined)</p>
246
<p><c>Asn1module.erl</c> the Erlang module with encode, decode and value functions.</p>
249
<p><c>Asn1module.asn1db</c> intermediate format used by the compiler when modules IMPORTS
250
definitions from each other.</p>
256
<name>encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}</name>
257
<fsummary>Encode an ASN.1 value.</fsummary>
259
<v>Module = Type = atom()</v>
260
<v>Value = term()</v>
261
<v>Bytes = [Int] when integer(Int), Int >= 0, Int =< 255</v>
262
<v>Reason = term()</v>
265
<p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module
266
<c>Module</c>. Returns a list of bytes if successful. To get as fast execution as
268
encode function only performs rudimentary tests that the input
270
is a correct instance of <c>Type</c>. The length of strings is for example
271
not always checked. Returns <c>{ok,Bytes}</c> if successful or
272
<c>{error,Reason}</c> if an error occured.
277
<name>decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}</name>
278
<fsummary>Decode from Bytes into an ASN.1 value.</fsummary>
280
<v>Module = Type = atom()</v>
281
<v>Value = Reason = term()</v>
282
<v>Bytes = [Int] when integer(Int), Int >= 0, Int =< 255</v>
285
<p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes
286
<c>Bytes</c>. Returns <c>{ok,Value}</c> if successful.</p>
290
<name>validate(Module,Type,Value) -> ok | {error,Reason}</name>
291
<fsummary>Validate an ASN.1 value.</fsummary>
293
<v>Module = Type = atom()</v>
294
<v>Value = term()</v>
297
<p>Validates that <c>Value</c> conforms to <c>Type</c>
298
from <c>Module</c>. <em>Not implemented in this version of the ASN.1 application.</em></p>
302
<name>value(Module ,Type) -> {ok,Value} | {error,Reason}</name>
303
<fsummary>Create an ASN.1 value for test purposes.</fsummary>
305
<v>Module = Type = atom()</v>
306
<v>Value = term()</v>
307
<v>Reason = term()</v>
310
<p>Returns an Erlang term which is an example of a valid Erlang
311
representation of a value of the ASN.1 type <c>Type</c>. The value
312
is a random value and subsequent calls to this function will for most
313
types return different values.</p>
317
<name>test(Module) -> ok | {error,Reason}</name>
318
<name>test(Module,Type) -> ok | {error,Reason}</name>
319
<name>test(Module,Type,Value) -> ok | {error,Reason}</name>
320
<fsummary>Perform a test of encode and decode for types in an ASN.1 module.</fsummary>
322
<p>Performs a test of encode and decode of all types in <c>Module</c>.
323
The generated functions are called by this function.
324
This function is useful during test to secure that the generated
325
encode and decode functions and the general runtime support work
326
as expected. <br></br>
327
<c>test/1</c> iterates over all types in <c>Module</c>. <br></br>
328
<c>test/2</c> tests type <c>Type</c> with a random value. <br></br>
329
<c><![CDATA[test/3 tests type <c>Type]]></c> with <c>Value</c>. <br></br>
331
Schematically the following happens for each type in the module.</p>
334
{ok,Value} = asn1ct:value(Module,Type),
335
{ok,Bytes} = asn1ct:encode(Module,Type,Value),
336
{ok,Value} = asn1:decode(Module,Type,Bytes). </code>
added
removed
lib/asn1/doc/src/asn1ct.xml
