<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Internal form and its encodings</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/megaco-3.16.0.2.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>Megaco/H.248</strong><br><strong>User's Guide</strong><br><small>Version 3.16.0.2</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Introduction" expanded="false">Introduction<ul>
<li><a href="megaco_intro.html">
Top of chapter
</a></li>
<li title="Scope and Purpose"><a href="megaco_intro.html#id56570">Scope and Purpose</a></li>
<li title="Prerequisites"><a href="megaco_intro.html#id65628">Prerequisites</a></li>
<li title="About This Manual"><a href="megaco_intro.html#id61790">About This Manual</a></li>
<li title="Where to Find More Information"><a href="megaco_intro.html#id62066">Where to Find More Information</a></li>
</ul>
</li>
<li id="no" title="Architecture" expanded="false">Architecture<ul>
<li><a href="megaco_architecture.html">
Top of chapter
</a></li>
<li title="Network view"><a href="megaco_architecture.html#id58224">Network view</a></li>
<li title="General"><a href="megaco_architecture.html#id65139">General</a></li>
<li title="Single node config"><a href="megaco_architecture.html#id60119">Single node config</a></li>
<li title="Distributed config"><a href="megaco_architecture.html#id58176">Distributed config</a></li>
<li title="Message round-trip call flow"><a href="megaco_architecture.html#id61141">Message round-trip call flow</a></li>
</ul>
</li>
<li id="no" title="Running the stack" expanded="false">Running the stack<ul>
<li><a href="megaco_run.html">
Top of chapter
</a></li>
<li title="Starting"><a href="megaco_run.html#id64614">Starting</a></li>
<li title="MGC startup call flow"><a href="megaco_run.html#id65587">MGC startup call flow</a></li>
<li title="MG startup call flow"><a href="megaco_run.html#id64564">MG startup call flow</a></li>
<li title="Configuring the Megaco stack"><a href="megaco_run.html#id65484">Configuring the Megaco stack</a></li>
<li title="Initial configuration"><a href="megaco_run.html#id65269">Initial configuration</a></li>
<li title="Changing the configuration"><a href="megaco_run.html#id65365">Changing the configuration</a></li>
<li title="The transaction sender"><a href="megaco_run.html#id64741">The transaction sender</a></li>
<li title="Segmentation of transaction replies"><a href="megaco_run.html#id64873">Segmentation of transaction replies</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Internal form and its encodings" expanded="true">Internal form and its encodings<ul>
<li><a href="megaco_encode.html">
Top of chapter
</a></li>
<li title="Internal form of messages"><a href="megaco_encode.html#id64187">Internal form of messages</a></li>
<li title="The different encodings"><a href="megaco_encode.html#id64304">The different encodings</a></li>
<li title="Configuration of Erlang distribution encoding module"><a href="megaco_encode.html#id64461">Configuration of Erlang distribution encoding module</a></li>
<li title="Configuration of text encoding module(s)"><a href="megaco_encode.html#id65758">Configuration of text encoding module(s)</a></li>
<li title="Configuration of binary encoding module(s)"><a href="megaco_encode.html#id65967">Configuration of binary encoding module(s)</a></li>
<li title="Handling megaco versions"><a href="megaco_encode.html#id66078">Handling megaco versions</a></li>
<li title="Encoder callback functions"><a href="megaco_encode.html#id66326">Encoder callback functions</a></li>
</ul>
</li>
<li id="no" title="Transport mechanisms" expanded="false">Transport mechanisms<ul>
<li><a href="megaco_transport_mechanisms.html">
Top of chapter
</a></li>
<li title="Callback interface"><a href="megaco_transport_mechanisms.html#id66413">Callback interface</a></li>
<li title="Examples"><a href="megaco_transport_mechanisms.html#id66482">Examples</a></li>
</ul>
</li>
<li id="no" title="Implementation examples" expanded="false">Implementation examples<ul>
<li><a href="megaco_examples.html">
Top of chapter
</a></li>
<li title="A simple Media Gateway Controller"><a href="megaco_examples.html#id66572">A simple Media Gateway Controller</a></li>
<li title="A simple Media Gateway"><a href="megaco_examples.html#id66620">A simple Media Gateway</a></li>
</ul>
</li>
<li id="no" title="Megaco mib" expanded="false">Megaco mib<ul>
<li><a href="megaco_mib.html">
Top of chapter
</a></li>
<li title="Intro"><a href="megaco_mib.html#id66738">Intro</a></li>
<li title="Statistics counters"><a href="megaco_mib.html#id66763">Statistics counters</a></li>
<li title="Distribution"><a href="megaco_mib.html#id66799">Distribution</a></li>
</ul>
</li>
<li id="no" title="Performance comparison" expanded="false">Performance comparison<ul>
<li><a href="megaco_performance.html">
Top of chapter
</a></li>
<li title="Comparison of encoder/decoders"><a href="megaco_performance.html#id66878">Comparison of encoder/decoders</a></li>
<li title="System performance characteristics"><a href="megaco_performance.html#id67709">System performance characteristics</a></li>
<li title="Description of encoders/decoders"><a href="megaco_performance.html#id67746">Description of encoders/decoders</a></li>
<li title="Setup"><a href="megaco_performance.html#id67856">Setup</a></li>
<li title="Summary"><a href="megaco_performance.html#id67869">Summary</a></li>
</ul>
</li>
<li id="no" title="Testing and tools" expanded="false">Testing and tools<ul>
<li><a href="megaco_debug.html">
Top of chapter
</a></li>
<li title="Tracing"><a href="megaco_debug.html#id67998">Tracing</a></li>
<li title="Measurement and transformation"><a href="megaco_debug.html#id68043">Measurement and transformation</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>4 Internal form and its encodings</h1>
<p>This version of the stack is compliant with: </p>
<ul>
<li>
<p>Megaco/H.248 version 1 (RFC3525)
updated according to Implementors Guide version 10-13.</p>
</li>
<li>
<p>Megaco/H.248 version 2 as defined by
draft-ietf-megaco-h248v2-04
updated according to Implementors Guide version 10-13.</p>
</li>
<li>
<p>Megaco/H.248 version 3 as defined by
ITU H.248.1 (09/2005).</p>
</li>
</ul>
<h3><a name="id64187">4.1
Internal form of messages</a></h3>
<p>We use the same internal form for both the binary and text
encoding. Our internal form of Megaco/H.248 messages is heavily
influenced by the internal format used by ASN.1
encoders/decoders:</p>
<ul>
<li>
<p>"SEQUENCE OF" is represented as a list.</p>
</li>
<li>
<p>"CHOICE" is represented as a tagged tuple with size 2.</p>
</li>
<li>
<p>"SEQUENCE" is represented as a record, defined in
"megaco/include/megaco_message_v1.hrl".</p>
</li>
<li>
<p>"OPTIONAL" is represented as an ordinary field in a
record which defaults to 'asn1_NOVALUE', meaning that the
field has no value.</p>
</li>
<li>
<p>"OCTET STRING" is represented as a list of unsigned integers.</p>
</li>
<li>
<p>"ENUMERATED" is represented as a single atom.</p>
</li>
<li>
<p>"BIT STRING" is represented as a list of atoms.</p>
</li>
<li>
<p>"BOOLEAN" is represented as the atom 'true' or 'false'.</p>
</li>
<li>
<p>"INTEGER" is represented as an integer.</p>
</li>
<li>
<p>"IA5String" is represented as a list of integers,
where each integer is the ASCII value of the corresponding
character.</p>
</li>
<li>
<p>"NULL" is represented as the atom 'NULL'.</p>
</li>
</ul>
<p>In order to fully understand the internal form you must get
hold on a ASN.1 specification for the Megaco/H.248 protocol,
and apply the rules above.
Please, see the documentation of the ASN.1 compiler in
Erlang/OTP for more details of the semantics in mapping between
ASN.1 and the corresponding internal form.</p>
<p>Observe that the 'TerminationId' record is not used in the
internal form. It has been replaced with a megaco_term_id record
(defined in "megaco/include/megaco.hrl").</p>
<h3><a name="id64304">4.2
The different encodings</a></h3>
<p>The Megaco/H.248 standard defines both a plain text encoding
and a binary encoding (ASN.1 BER) and we have implemented
encoders and decoders for both. We do in fact supply five
different encoding/decoding modules.</p>
<p>In the text encoding, implementors have the choice of using a
mix of short and long keywords. It is also possible to add white
spaces to improve readability. We use the term compact for text
messages with the shortest possible keywords and no optional
white spaces, and the term pretty for a well indented text
format using long keywords and an indentation style like the
text examples in the Megaco/H.248 specification).</p>
<p>Here follows an example of a text message to give a feeling
of the difference between the pretty and compact versions of
text messages. First the pretty, well indented version with long
keywords:</p>
<div class="example"><pre>
MEGACO/1 [124.124.124.222]
Transaction = 9998 {
Context = - {
ServiceChange = ROOT {
Services {
Method = Restart,
ServiceChangeAddress = 55555,
Profile = ResGW/1,
Reason = "901 Cold Boot"
}
}
}
} </pre></div>
<p>Then the compact version without indentation and with short keywords:</p>
<div class="example"><pre>
!/1 [124.124.124.222]
T=9998{C=-{SC=ROOT{SV{MT=RS,AD=55555,PF=ResGW/1,RE="901 Cold Boot"}}}} </pre></div>
<p>And the programmers view of the same message.
First a list of ActionRequest records are constructed and
then it is sent with one of the send functions in the API:</p>
<div class="example"><pre>
Prof = #'ServiceChangeProfile'{profileName = "resgw", version = 1},
Parm = #'ServiceChangeParm'{serviceChangeMethod = restart,
serviceChangeAddress = {portNumber, 55555},
serviceChangeReason = "901 Cold Boot",
serviceChangeProfile = Prof},
Req = #'ServiceChangeRequest'{terminationID = [?megaco_root_termination_id],
serviceChangeParms = Parm},
Actions = [#'ActionRequest'{contextId = ?megaco_null_context_id,
commandRequests = {serviceChangeReq, Req}}],
megaco:call(ConnHandle, Actions, Config). </pre></div>
<p>And finally a print-out of the entire internal form:</p>
<div class="example"><pre>
{'MegacoMessage',
asn1_NOVALUE,
{'Message',
1,
{ip4Address,{'IP4Address', [124,124,124,222], asn1_NOVALUE}},
{transactions,
[
{transactionRequest,
{'TransactionRequest',
9998,
[{'ActionRequest',
0,
asn1_NOVALUE,
asn1_NOVALUE,
[
{'CommandRequest',
{serviceChangeReq,
{'ServiceChangeRequest',
[
{megaco_term_id, false, ["root"]}],
{'ServiceChangeParm',
restart,
{portNumber, 55555},
asn1_NOVALUE,
{'ServiceChangeProfile', "resgw", version = 1},
"901 MG Cold Boot",
asn1_NOVALUE,
asn1_NOVALUE,
asn1_NOVALUE
}
}
},
asn1_NOVALUE,
asn1_NOVALUE
}
]
}
]
}
}
]
}
}
} </pre></div>
<p>The following encoding modules are provided:
</p>
<ul>
<li>
<p>megaco_pretty_text_encoder - encodes messages into
pretty text format, decodes both pretty as well as compact
text.</p>
</li>
<li>
<p>megaco_compact_text_encoder - encodes messages into
compact text format, decodes both pretty as well as compact
text.</p>
</li>
<li>
<p>megaco_binary_encoder - encode/decode ASN.1 BER messages.
This encoder implements the fastest of the BER encoders/decoders.
Recommended binary codec.</p>
</li>
<li>
<p>megaco_ber_encoder - encode/decode ASN.1 BER
messages.</p>
</li>
<li>
<p>megaco_ber_bin_encoder - encode/decode ASN.1 BER
messages. This encoder uses ASN.1 ber_bin which
has been optimized using the bit syntax.</p>
</li>
<li>
<p>megaco_per_encoder - encode/decode ASN.1 PER
messages. N.B. that this format is not included in the
Megaco standard.</p>
</li>
<li>
<p>megaco_per_bin_encoder - encode/decode ASN.1 PER
messages. N.B. that this format is not included in the
Megaco standard. This encoder uses ASN.1 per_bin which
has been optimized using the bit syntax.</p>
</li>
<li>
<p>megaco_erl_dist_encoder - encodes messages into Erlangs
distribution format. It is rather verbose but encoding and
decoding is blinding fast. N.B. that this format is not
included in the Megaco standard.</p>
</li>
</ul>
<h3><a name="id64461">4.3
Configuration of Erlang distribution encoding module</a></h3>
<a name="erl_dist_config"></a>
<p>The encoding_config of the megaco_erl_dist_encoder module
may be one of these:</p>
<ul>
<li>
<p><span class="code">[]</span> - Encodes the messages to the standard distribution
format. It is rather verbose but encoding and decoding is
blinding fast.</p>
</li>
<li>
<p><span class="code">[megaco_compressed]</span> - Encodes the messages to the
standard distribution format after an internal transformation.
It is less verbose, but the total time of the encoding and
decoding will on the other hand be somewhat slower (see the
<span class="bold_code"><a href="megaco_performance.html">performance</a></span>
chapter for more info).</p>
</li>
<li>
<p><span class="code">[{megaco_compressed, Module}]</span> - Works in the same
way as the megaco_compressed config parameter, only here the
user provide their own compress module. This module must
implement the
<span class="bold_code"><a href="megaco_edist_compress.html">megaco_edist_compress</a></span>
behaviour.</p>
</li>
<li>
<p><span class="code">[compressed]</span> - Encodes the messages to a compressed
form of the standard distribution format. It is less
verbose, but the encoding and decoding will on the other
hand be slower.</p>
</li>
</ul>
<h3><a name="id65758">4.4
Configuration of text encoding module(s)</a></h3>
<a name="text_config"></a>
<p>When using text encoding(s), there is actually two different
configs controlling what software to use:</p>
<ul>
<li>
<p><span class="code">[]</span> - An empty list indicates that the erlang
scanner should be used.</p>
</li>
<li>
<p><span class="code">[{flex, port()}]</span> - Use the flex scanner when
decoding (not optimized for SMP). See
<span class="bold_code"><a href="megaco_run.html#initial_config">initial configuration</a></span>
for more info.</p>
</li>
<li>
<p><span class="code">[{flex, ports()}]</span> - Use the flex scanner when
decoding (optimized for SMP). See
<span class="bold_code"><a href="megaco_run.html#initial_config">initial configuration</a></span>
for more info.</p>
</li>
</ul>
<p>The Flex scanner is a Megaco scanner written as a linked in driver
(in C). There are two ways to get this working:</p>
<ul>
<li>
<p>Let the Megaco stack start the flex scanner
(load the driver).</p>
<p>To make this happen the megaco stack has to be configured: </p>
<ul>
<li>
<p>Add the <span class="code">{scanner, flex}</span> (or similar) directive to an
Erlang system config file for the megaco app (see
<span class="bold_code"><a href="megaco_run.html#initial_config">initial configuration</a></span>
chapter for details). </p>
</li>
<li>
<p>Retrieve the encoding-config using the
<span class="bold_code"><a href="megaco.html#system_info">system_info</a></span>
function (with <span class="code">Item = text_config</span>). </p>
</li>
<li>
<p>Update the receive handle with the encoding-config
(the <span class="code">encoding_config</span> field). </p>
</li>
</ul>
<p>The benefit of this is that Megaco handles the starting, holding
and the supervision of the driver and port.</p>
</li>
<li>
<p>The Megaco client (user) starts the flex scanner (load the driver).</p>
<p>When starting the flex scanner a port to the linked in driver is
created. This port has to be owned by a process. This process must not
die. If it does the port will also terminate. Therefor:</p>
<p></p>
<ul>
<li>
<p>Create a permanent process. Make sure this process is
supervised (so that if it does die, this will be noticed).</p>
</li>
<li>
<p>Let this process start the flex scanner by calling the
<span class="code">megaco_flex_scanner:start/0,1</span> function.</p>
</li>
<li>
<p>Retrieve the encoding-config and when initiating
the <span class="code">megaco_receive_handle</span>, set the
field <span class="code">encoding_config</span> accordingly.</p>
</li>
<li>
<p>Pass the <span class="code">megaco_receive_handle</span> to the
transport module.</p>
</li>
</ul>
</li>
</ul>
<h3><a name="id65967">4.5
Configuration of binary encoding module(s)</a></h3>
<a name="binary_config"></a>
<p>When using binary encoding, the structure of the termination id's
needs to be specified.</p>
<ul>
<li>
<p><span class="code">[driver|_]</span> - make use of the asn1 driver for decode
(ber_bin) and encode (per_bin). This option is only available for
encoding modules: <span class="code">megaco_binary_encoder</span>,
<span class="code">megaco_ber_bin_encoder</span> and <span class="code">megaco_per_bin_encoder</span>.</p>
<p>If this option is present in the encoding config, it <strong>must</strong>
to be the <strong>first</strong>, unless the
<span class="bold_code"><a href="#handling_versions">version3</a></span> encoding
config is present, in which case it must come second, after
the version3 encoding config,
e.g. <span class="code">[{version3,prev3b},driver]</span>.</p>
</li>
<li>
<p><span class="code">[native]</span> - skips the transformation phase, i.e.
the decoded message(s) will not be transformed into our internal
form.</p>
</li>
<li>
<p><span class="code">[integer()]</span> - A list containing the size (the number
of bits) of each level. Example: <span class="code">[3,8,5,8]</span>.</p>
</li>
<li>
<p><span class="code">integer()</span> - Number of one byte (8 bits) levels.
N.B. This is currently converted into the previous config.
Example: <span class="code">3</span> (<span class="code">[8,8,8]</span>).</p>
</li>
</ul>
<h3><a name="id66078">4.6
Handling megaco versions</a></h3>
<a name="handling_versions"></a>
<p>Since the version 3 implemented, in this version of the Megaco
application, is preliminary, it is necessary to have a way
to handle different version 3 implementations. For this reason
the encoding config option <span class="code">{version3, version3()}</span> has been
introduced. This option, if present, has to be <strong>first</strong> in the
encoding config list. Version 1 and 2 codec's ignore this option, if
found. </p>
<div class="example"><pre>
version3() -> prev3a | prev3b | prev3c | v3 </pre></div>
<ul>
<li>
<p><strong>prev3a</strong></p>
<p>Preliminary version 3, based on TD-33</p>
</li>
<li>
<p><strong>prev3b</strong></p>
<p>Preliminary version 3, based on TD-33, but text encoding
updated with the final solution for priority in
<span class="code">contextProperty</span> (which is backward compatible with v2).</p>
</li>
<li>
<p><strong>prev3c</strong></p>
<p>Preliminary version 3, based on the final version of the
v3-standard, but <strong>excluding</strong> segments!</p>
</li>
<li>
<p><strong>v3</strong></p>
<p>Full version 3. Including segmentation. This is the default
version 3 variant (i.e. if a version 3 messages is to be
encoded/decoded and no version3 encoding config is found,
then v3 is assumed).</p>
</li>
</ul>
<p>There are two ways to handle the different megaco encoding versions.
Either using <strong>dynamic version detection</strong> (only valid for
for incoming messages) or by <strong>explicit version</strong> setting in
the connection info.</p>
<p>For incoming messages:</p>
<ul>
<li>
<p>Dynamic version detection</p>
<p>Set the protocol version in the megaco_receive_handle to
<span class="code">dynamic</span> (this is the default).
<br>This works for those codecs that support partial decode of the
version, currently <strong>text</strong>, and ber_bin
(<span class="code">megaco_binary_encoder</span> and <span class="code">megaco_ber_bin_encoder</span>).
<br>This way the decoder will detect which version is used and
then use the proper decoder. </p>
</li>
<li>
<p>Explicit version</p>
<p>Explicitly set the actual protocol version in the
megaco_receive_handle.
<br>Start with version 1. When the initial service change has been
performed and version 2 has been negotiated, upgrade the
megaco_receive_handle of the transport process (control_pid) to
version 2.
See
<span class="bold_code"><a href="megaco_tcp.html#upgrade_receive_handle">megaco_tcp</a></span>
and
<span class="bold_code"><a href="megaco_udp.html#upgrade_receive_handle">megaco_udp</a></span>.
<br>Note that if <span class="code">udp</span> is used, the same transport process
could be used for several connections. This could make upgrading
impossible.
<br>For codecs that does not support partial decode of the version,
currently <span class="code">megaco_ber_encoder</span>, <span class="code">megaco_per_encoder</span>
and <span class="code">megaco_per_bin_encoder</span>, <span class="code">dynamic</span> will revert to
version 1.</p>
</li>
</ul>
<p>For outgoing messages:</p>
<ul>
<li>
<p>Update the connection info protocol_version.</p>
</li>
<li>
<p>Override protocol version when sending a message by adding the
item <span class="code">{protocol_version, integer()}</span> to the Options.
See
<span class="bold_code"><a href="megaco.html#call">call</a></span> or
<span class="bold_code"><a href="megaco.html#cast">cast</a></span>.
<br>Note that this does not effect the messages that are sent
autonomously by the stack. They use the protocol_version of the
connection info.</p>
</li>
</ul>
<h3><a name="id66326">4.7
Encoder callback functions</a></h3>
<p>The encoder callback interface is defined by the <span class="code">megaco_encoder</span>
behaviour, see <span class="bold_code"><a href="megaco_encoder.html">megaco_encoder</a></span>.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 2000-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
961
