1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
7
<year>2000</year><year>2009</year>
8
<holder>Ericsson AB. All Rights Reserved.</holder>
11
The contents of this file are subject to the Erlang Public License,
12
Version 1.1, (the "License"); you may not use this file except in
13
compliance with the License. You should have received a copy of the
14
Erlang Public License along with this software. If not, it can be
15
retrieved online at http://www.erlang.org/.
17
Software distributed under the License is distributed on an "AS IS"
18
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
the License for the specific language governing rights and limitations
24
<title>Internal form and its encodings</title>
25
<prepared>Håkan Mattsson</prepared>
26
<responsible>Håkan Mattsson</responsible>
28
<approved>Håkan Mattsson</approved>
30
<date>2007-06-15</date>
32
<file>megaco_encode.xml</file>
34
<p>This version of the stack is compliant with: </p>
35
<list type="bulleted">
37
<p>Megaco/H.248 version 1 (RFC3525)
38
updated according to Implementors Guide version 10-13.</p>
41
<p>Megaco/H.248 version 2 as defined by
42
draft-ietf-megaco-h248v2-04
43
updated according to Implementors Guide version 10-13.</p>
46
<p>Megaco/H.248 version 3 as defined by
47
ITU H.248.1 (09/2005).</p>
52
<title>Internal form of messages</title>
53
<p>We use the same internal form for both the binary and text
54
encoding. Our internal form of Megaco/H.248 messages is heavily
55
influenced by the internal format used by ASN.1
56
encoders/decoders:</p>
57
<list type="bulleted">
59
<p>"SEQUENCE OF" is represented as a list.</p>
62
<p>"CHOICE" is represented as a tagged tuple with size 2.</p>
65
<p>"SEQUENCE" is represented as a record, defined in
66
"megaco/include/megaco_message_v1.hrl".</p>
69
<p>"OPTIONAL" is represented as an ordinary field in a
70
record which defaults to 'asn1_NOVALUE', meaning that the
71
field has no value.</p>
74
<p>"OCTET STRING" is represented as a list of unsigned integers.</p>
77
<p>"ENUMERATED" is represented as a single atom.</p>
80
<p>"BIT STRING" is represented as a list of atoms.</p>
83
<p>"BOOLEAN" is represented as the atom 'true' or 'false'.</p>
86
<p>"INTEGER" is represented as an integer.</p>
89
<p>"IA5String" is represented as a list of integers,
90
where each integer is the ASCII value of the corresponding
94
<p>"NULL" is represented as the atom 'NULL'.</p>
97
<p>In order to fully understand the internal form you must get
98
hold on a ASN.1 specification for the Megaco/H.248 protocol,
99
and apply the rules above.
100
Please, see the documentation of the ASN.1 compiler in
101
Erlang/OTP for more details of the semantics in mapping between
102
ASN.1 and the corresponding internal form.</p>
103
<p>Observe that the 'TerminationId' record is not used in the
104
internal form. It has been replaced with a megaco_term_id record
105
(defined in "megaco/include/megaco.hrl").</p>
109
<title>The different encodings</title>
110
<p>The Megaco/H.248 standard defines both a plain text encoding
111
and a binary encoding (ASN.1 BER) and we have implemented
112
encoders and decoders for both. We do in fact supply five
113
different encoding/decoding modules.</p>
114
<p>In the text encoding, implementors have the choice of using a
115
mix of short and long keywords. It is also possible to add white
116
spaces to improve readability. We use the term compact for text
117
messages with the shortest possible keywords and no optional
118
white spaces, and the term pretty for a well indented text
119
format using long keywords and an indentation style like the
120
text examples in the Megaco/H.248 specification).</p>
121
<p>Here follows an example of a text message to give a feeling
122
of the difference between the pretty and compact versions of
123
text messages. First the pretty, well indented version with long
126
MEGACO/1 [124.124.124.222]
129
ServiceChange = ROOT {
132
ServiceChangeAddress = 55555,
134
Reason = "901 Cold Boot"
139
<p>Then the compact version without indentation and with short keywords:</p>
142
!/1 [124.124.124.222]
143
T=9998{C=-{SC=ROOT{SV{MT=RS,AD=55555,PF=ResGW/1,RE="901 Cold Boot"}}}} </pre>
144
<p>And the programmers view of the same message.
145
First a list of ActionRequest records are constructed and
146
then it is sent with one of the send functions in the API:</p>
148
Prof = #'ServiceChangeProfile'{profileName = "resgw", version = 1},
149
Parm = #'ServiceChangeParm'{serviceChangeMethod = restart,
150
serviceChangeAddress = {portNumber, 55555},
151
serviceChangeReason = "901 Cold Boot",
152
serviceChangeProfile = Prof},
153
Req = #'ServiceChangeRequest'{terminationID = [?megaco_root_termination_id],
154
serviceChangeParms = Parm},
155
Actions = [#'ActionRequest'{contextId = ?megaco_null_context_id,
156
commandRequests = {serviceChangeReq, Req}}],
157
megaco:call(ConnHandle, Actions, Config). </pre>
158
<p>And finally a print-out of the entire internal form:</p>
164
{ip4Address,{'IP4Address', [124,124,124,222], asn1_NOVALUE}},
168
{'TransactionRequest',
177
{'ServiceChangeRequest',
179
{megaco_term_id, false, ["root"]}],
180
{'ServiceChangeParm',
184
{'ServiceChangeProfile', "resgw", version = 1},
204
<p>The following encoding modules are provided:
206
<list type="bulleted">
208
<p>megaco_pretty_text_encoder - encodes messages into
209
pretty text format, decodes both pretty as well as compact
213
<p>megaco_compact_text_encoder - encodes messages into
214
compact text format, decodes both pretty as well as compact
218
<p>megaco_binary_encoder - encode/decode ASN.1 BER messages.
219
This encoder implements the fastest of the BER encoders/decoders.
220
Recommended binary codec.</p>
223
<p>megaco_ber_encoder - encode/decode ASN.1 BER
227
<p>megaco_ber_bin_encoder - encode/decode ASN.1 BER
228
messages. This encoder uses ASN.1 ber_bin which
229
has been optimized using the bit syntax.</p>
232
<p>megaco_per_encoder - encode/decode ASN.1 PER
233
messages. N.B. that this format is not included in the
237
<p>megaco_per_bin_encoder - encode/decode ASN.1 PER
238
messages. N.B. that this format is not included in the
239
Megaco standard. This encoder uses ASN.1 per_bin which
240
has been optimized using the bit syntax.</p>
243
<p>megaco_erl_dist_encoder - encodes messages into Erlangs
244
distribution format. It is rather verbose but encoding and
245
decoding is blinding fast. N.B. that this format is not
246
included in the Megaco standard.</p>
252
<marker id="erl_dist_config"></marker>
253
<title>Configuration of Erlang distribution encoding module</title>
254
<p>The encoding_config of the megaco_erl_dist_encoder module
255
may be one of these:</p>
256
<list type="bulleted">
258
<p><c><![CDATA[[]]]></c> - Encodes the messages to the standard distribution
259
format. It is rather verbose but encoding and decoding is
263
<p><c><![CDATA[[megaco_compressed]]]></c> - Encodes the messages to the
264
standard distribution format after an internal transformation.
265
It is less verbose, but the total time of the encoding and
266
decoding will on the other hand be somewhat slower (see the
267
<seealso marker="megaco_performance">performance</seealso>
268
chapter for more info).</p>
271
<p><c><![CDATA[[{megaco_compressed, Module}]]]></c> - Works in the same
272
way as the megaco_compressed config parameter, only here the
273
user provide their own compress module. This module must
275
<seealso marker="megaco_edist_compress">megaco_edist_compress</seealso>
279
<p><c><![CDATA[[compressed]]]></c> - Encodes the messages to a compressed
280
form of the standard distribution format. It is less
281
verbose, but the encoding and decoding will on the other
288
<marker id="text_config"></marker>
289
<title>Configuration of text encoding module(s)</title>
290
<p>When using text encoding(s), there is actually two different
291
configs controlling what software to use:</p>
292
<list type="bulleted">
294
<p><c><![CDATA[[]]]></c> - An empty list indicates that the erlang
295
scanner should be used.</p>
298
<p><c><![CDATA[[{flex, port()}]]]></c> - Use the flex scanner when
302
<p>The Flex scanner is a Megaco scanner written as a linked in driver
303
(in C). There are two ways to get this working:</p>
304
<list type="bulleted">
306
<p>Let the Megaco stack start the flex scanner
307
(load the driver).</p>
308
<p>To make this happen the megaco stack has to be configured: </p>
309
<list type="bulleted">
311
<p>Add the <c><![CDATA[{scanner, flex}]]></c> directive to an
312
Erlang system config file for the megaco app. This will
313
make the Megaco stack initiate the default
314
<c><![CDATA[megaco_receive_handle]]></c> with the encoding_config set
315
to the <c><![CDATA[[{flex, port()}]]]></c>. </p>
318
<p>When retrieving the <c><![CDATA[megaco_receive_handle]]></c>,
319
retain the encoding_config.</p>
322
<p>The benefit of this is that Megaco handles the starting, holding
323
and the supervision of the driver and port.</p>
326
<p>The Megaco client (user) starts the flex scanner (load the driver).</p>
327
<p>When starting the flex scanner a port to the linked in driver is
328
created. This port has to be owned by a process. This process must not
329
die. If it does the port will also terminate. Therefor:</p>
331
<list type="bulleted">
333
<p>Create a permanent process. Make sure this process is
334
supervised (so that if it does die, this will be noticed).</p>
337
<p>Let this process start the flex scanner by calling the
338
<c><![CDATA[megaco_flex_scanner:start()]]></c> function.</p>
341
<p>Retrieve the <c><![CDATA[port()]]></c> and when initiating
342
the <c><![CDATA[megaco_receive_handle]]></c>, set the encoding_config to
343
[{flex, port()}].</p>
346
<p>Pass the <c><![CDATA[receive_handle]]></c> to the transport module.</p>
354
<marker id="binary_config"></marker>
355
<title>Configuration of binary encoding module(s)</title>
356
<p>When using binary encoding, the structure of the termination id's
357
needs to be specified.</p>
358
<list type="bulleted">
360
<p><c><![CDATA[[driver|_]]]></c> - make use of the asn1 driver for decode
361
(ber_bin) and encode (per_bin). This option is only available for
362
encoding modules: <c><![CDATA[megaco_binary_encoder]]></c>,
363
<c><![CDATA[megaco_ber_bin_encoder]]></c> and <c><![CDATA[megaco_per_bin_encoder]]></c>.</p>
364
<p>If this option is present in the encoding config, it <em>must</em>
365
to be the <em>first</em>, unless the
366
<seealso marker="#handling_versions">version3</seealso> encoding
367
config is present, in which case it must come second, after
368
the version3 encoding config,
369
e.g. <c><![CDATA[[{version3,prev3b},driver]]]></c>.</p>
372
<p><c><![CDATA[[native]]]></c> - skips the transformation phase, i.e.
373
the decoded message(s) will not be transformed into our internal
377
<p><c><![CDATA[[integer()]]]></c> - A list containing the size (the number
378
of bits) of each level. Example: <c><![CDATA[[3,8,5,8]]]></c>.</p>
381
<p><c><![CDATA[integer()]]></c> - Number of one byte (8 bits) levels.
382
N.B. This is currently converted into the previous config.
383
Example: <c><![CDATA[3]]></c> (<c><![CDATA[[8,8,8]]]></c>).</p>
389
<marker id="handling_versions"></marker>
390
<title>Handling megaco versions</title>
391
<p>Since the version 3 implemented, in this version of the Megaco
392
application, is preliminary, it is necessary to have a way
393
to handle different version 3 implementations. For this reason
394
the encoding config option <c><![CDATA[{version3, version3()}]]></c> has been
395
introduced. This option, if present, has to be <em>first</em> in the
396
encoding config list. Version 1 and 2 codec's ignore this option, if
398
<code type="none"><![CDATA[
399
version3() -> prev3a | prev3b | prev3c | v3 ]]></code>
400
<list type="bulleted">
402
<p><em>prev3a</em></p>
403
<p>Preliminary version 3, based on TD-33</p>
406
<p><em>prev3b</em></p>
407
<p>Preliminary version 3, based on TD-33, but text encoding
408
updated with the final solution for priority in
409
<c><![CDATA[contextProperty]]></c> (which is backward compatible with v2).</p>
412
<p><em>prev3c</em></p>
413
<p>Preliminary version 3, based on the final version of the
414
v3-standard, but <em>excluding</em> segments!</p>
418
<p>Full version 3. Including segmentation. This is the default
419
version 3 variant (i.e. if a version 3 messages is to be
420
encoded/decoded and no version3 encoding config is found,
421
then v3 is assumed).</p>
424
<p>There are two ways to handle the different megaco encoding versions.
425
Either using <em>dynamic version detection</em> (only valid for
426
for incoming messages) or by <em>explicit version</em> setting in
427
the connection info.</p>
428
<p>For incomming messages:</p>
429
<list type="bulleted">
431
<p>Dynamic version detection</p>
432
<p>Set the protocol version in the megaco_receive_handle to
433
<c><![CDATA[dynamic]]></c> (this is the default).
434
<br></br>This works for those codecs that support partial decode of the
435
version, currently <em>text</em>, and ber_bin
436
(<c><![CDATA[megaco_binary_encoder]]></c> and <c><![CDATA[megaco_ber_bin_encoder]]></c>).
437
<br></br>This way the decoder will detect which version is used and
438
then use the proper decoder. </p>
441
<p>Explicit version</p>
442
<p>Explicitly set the actual protocol version in the
443
megaco_receive_handle.
444
<br></br>Start with version 1. When the initial service change has been
445
performed and version 2 has been negotiated, upgrade the
446
megaco_receive_handle of the transport process (control_pid) to
449
<seealso marker="megaco_tcp#upgrade_receive_handle">megaco_tcp</seealso>
451
<seealso marker="megaco_udp#upgrade_receive_handle">megaco_udp</seealso>.
452
<br></br>Note that if <c><![CDATA[udp]]></c> is used, the same transport process
453
could be used for several connections. This could make upgrading
455
<br></br>For codecs that does not support partial decode of the version,
456
currently <c><![CDATA[megaco_ber_encoder]]></c>, <c><![CDATA[megaco_per_encoder]]></c>
457
and <c><![CDATA[megaco_per_bin_encoder]]></c>, <c><![CDATA[dynamic]]></c> will revert to
461
<p>For outgoing messages:</p>
462
<list type="bulleted">
464
<p>Update the connection info protocol_version.</p>
467
<p>Override protocol version when sending a message by adding the
468
item <c><![CDATA[{protocol_version, integer()}]]></c> to the Options.
470
<seealso marker="megaco#call">call</seealso> or
471
<seealso marker="megaco#cast">cast</seealso>.
472
<br></br>Note that this does not effect the messages that are sent
473
autonomously by the stack. They use the protocol_version of the
480
<title>Encoder callback functions</title>
481
<p>The encoder callback interface is defined by the <c><![CDATA[megaco_encoder]]></c>
482
behaviour, see <seealso marker="megaco_encoder">megaco_encoder</seealso>.</p>
added
removed
lib/megaco/doc/src/megaco_encode.xml
