diff options
Diffstat (limited to 'lib/megaco/doc/src/megaco_encode.xml')
| -rw-r--r-- | lib/megaco/doc/src/megaco_encode.xml | 498 |
1 files changed, 498 insertions, 0 deletions
diff --git a/lib/megaco/doc/src/megaco_encode.xml b/lib/megaco/doc/src/megaco_encode.xml new file mode 100644 index 0000000000..410e4f3b31 --- /dev/null +++ b/lib/megaco/doc/src/megaco_encode.xml @@ -0,0 +1,498 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2000</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Internal form and its encodings</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date>2007-06-15</date> + <rev>%VSN%</rev> + <file>megaco_encode.xml</file> + </header> + <p>This version of the stack is compliant with: </p> + <list type="bulleted"> + <item> + <p>Megaco/H.248 version 1 (RFC3525) + updated according to Implementors Guide version 10-13.</p> + </item> + <item> + <p>Megaco/H.248 version 2 as defined by + draft-ietf-megaco-h248v2-04 + updated according to Implementors Guide version 10-13.</p> + </item> + <item> + <p>Megaco/H.248 version 3 as defined by + ITU H.248.1 (09/2005).</p> + </item> + </list> + + <section> + <title>Internal form of messages</title> + <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> + <list type="bulleted"> + <item> + <p>"SEQUENCE OF" is represented as a list.</p> + </item> + <item> + <p>"CHOICE" is represented as a tagged tuple with size 2.</p> + </item> + <item> + <p>"SEQUENCE" is represented as a record, defined in + "megaco/include/megaco_message_v1.hrl".</p> + </item> + <item> + <p>"OPTIONAL" is represented as an ordinary field in a + record which defaults to 'asn1_NOVALUE', meaning that the + field has no value.</p> + </item> + <item> + <p>"OCTET STRING" is represented as a list of unsigned integers.</p> + </item> + <item> + <p>"ENUMERATED" is represented as a single atom.</p> + </item> + <item> + <p>"BIT STRING" is represented as a list of atoms.</p> + </item> + <item> + <p>"BOOLEAN" is represented as the atom 'true' or 'false'.</p> + </item> + <item> + <p>"INTEGER" is represented as an integer.</p> + </item> + <item> + <p>"IA5String" is represented as a list of integers, + where each integer is the ASCII value of the corresponding + character.</p> + </item> + <item> + <p>"NULL" is represented as the atom 'NULL'.</p> + </item> + </list> + <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> + </section> + + <section> + <title>The different encodings</title> + <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> + <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> + <p>Then the compact version without indentation and with short keywords:</p> + <pre> + + !/1 [124.124.124.222] + T=9998{C=-{SC=ROOT{SV{MT=RS,AD=55555,PF=ResGW/1,RE="901 Cold Boot"}}}} </pre> + <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> + <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> + <p>And finally a print-out of the entire internal form:</p> + <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> + <p>The following encoding modules are provided: + </p> + <list type="bulleted"> + <item> + <p>megaco_pretty_text_encoder - encodes messages into + pretty text format, decodes both pretty as well as compact + text.</p> + </item> + <item> + <p>megaco_compact_text_encoder - encodes messages into + compact text format, decodes both pretty as well as compact + text.</p> + </item> + <item> + <p>megaco_binary_encoder - encode/decode ASN.1 BER messages. + This encoder implements the fastest of the BER encoders/decoders. + Recommended binary codec.</p> + </item> + <item> + <p>megaco_ber_encoder - encode/decode ASN.1 BER + messages.</p> + </item> + <item> + <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> + </item> + <item> + <p>megaco_per_encoder - encode/decode ASN.1 PER + messages. N.B. that this format is not included in the + Megaco standard.</p> + </item> + <item> + <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> + </item> + <item> + <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> + </item> + </list> + </section> + + <section> + <marker id="erl_dist_config"></marker> + <title>Configuration of Erlang distribution encoding module</title> + <p>The encoding_config of the megaco_erl_dist_encoder module + may be one of these:</p> + <list type="bulleted"> + <item> + <p><c><![CDATA[[]]]></c> - Encodes the messages to the standard distribution + format. It is rather verbose but encoding and decoding is + blinding fast.</p> + </item> + <item> + <p><c><![CDATA[[megaco_compressed]]]></c> - 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 + <seealso marker="megaco_performance">performance</seealso> + chapter for more info).</p> + </item> + <item> + <p><c><![CDATA[[{megaco_compressed, Module}]]]></c> - 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 + <seealso marker="megaco_edist_compress">megaco_edist_compress</seealso> + behaviour.</p> + </item> + <item> + <p><c><![CDATA[[compressed]]]></c> - 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> + </item> + </list> + </section> + + <section> + <marker id="text_config"></marker> + <title>Configuration of text encoding module(s)</title> + <p>When using text encoding(s), there is actually two different + configs controlling what software to use:</p> + <list type="bulleted"> + <item> + <p><c><![CDATA[[]]]></c> - An empty list indicates that the erlang + scanner should be used.</p> + </item> + <item> + <p><c><![CDATA[[{flex, port()}]]]></c> - Use the flex scanner when + decoding (not optimized for SMP). See + <seealso marker="megaco_run#initial_config">initial configuration</seealso> + for more info.</p> + </item> + <item> + <p><c><![CDATA[[{flex, ports()}]]]></c> - Use the flex scanner when + decoding (optimized for SMP). See + <seealso marker="megaco_run#initial_config">initial configuration</seealso> + for more info.</p> + </item> + </list> + <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> + <list type="bulleted"> + <item> + <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> + <list type="bulleted"> + <item> + <p>Add the <c><![CDATA[{scanner, flex}]]></c> (or similar) directive to an + Erlang system config file for the megaco app (see + <seealso marker="megaco_run#initial_config">initial configuration</seealso> + chapter for details). </p> + </item> + <item> + <p>Retrieve the encoding-config using the + <seealso marker="megaco#system_info">system_info</seealso> + function (with <c>Item = text_config</c>). </p> + </item> + <item> + <p>Update the receive handle with the encoding-config + (the <c>encoding_config</c> field). </p> + </item> + </list> + <p>The benefit of this is that Megaco handles the starting, holding + and the supervision of the driver and port.</p> + </item> + <item> + <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> + <list type="bulleted"> + <item> + <p>Create a permanent process. Make sure this process is + supervised (so that if it does die, this will be noticed).</p> + </item> + <item> + <p>Let this process start the flex scanner by calling the + <c><![CDATA[megaco_flex_scanner:start/0,1]]></c> function.</p> + </item> + <item> + <p>Retrieve the encoding-config and when initiating + the <c><![CDATA[megaco_receive_handle]]></c>, set the + field <c>encoding_config</c> accordingly.</p> + </item> + <item> + <p>Pass the <c><![CDATA[megaco_receive_handle]]></c> to the + transport module.</p> + </item> + </list> + </item> + </list> + </section> + + <section> + <marker id="binary_config"></marker> + <title>Configuration of binary encoding module(s)</title> + <p>When using binary encoding, the structure of the termination id's + needs to be specified.</p> + <list type="bulleted"> + <item> + <p><c><![CDATA[[driver|_]]]></c> - make use of the asn1 driver for decode + (ber_bin) and encode (per_bin). This option is only available for + encoding modules: <c><![CDATA[megaco_binary_encoder]]></c>, + <c><![CDATA[megaco_ber_bin_encoder]]></c> and <c><![CDATA[megaco_per_bin_encoder]]></c>.</p> + <p>If this option is present in the encoding config, it <em>must</em> + to be the <em>first</em>, unless the + <seealso marker="#handling_versions">version3</seealso> encoding + config is present, in which case it must come second, after + the version3 encoding config, + e.g. <c><![CDATA[[{version3,prev3b},driver]]]></c>.</p> + </item> + <item> + <p><c><![CDATA[[native]]]></c> - skips the transformation phase, i.e. + the decoded message(s) will not be transformed into our internal + form.</p> + </item> + <item> + <p><c><![CDATA[[integer()]]]></c> - A list containing the size (the number + of bits) of each level. Example: <c><![CDATA[[3,8,5,8]]]></c>.</p> + </item> + <item> + <p><c><![CDATA[integer()]]></c> - Number of one byte (8 bits) levels. + N.B. This is currently converted into the previous config. + Example: <c><![CDATA[3]]></c> (<c><![CDATA[[8,8,8]]]></c>).</p> + </item> + </list> + </section> + + <section> + <marker id="handling_versions"></marker> + <title>Handling megaco versions</title> + <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 <c><![CDATA[{version3, version3()}]]></c> has been + introduced. This option, if present, has to be <em>first</em> in the + encoding config list. Version 1 and 2 codec's ignore this option, if + found. </p> + <code type="none"><![CDATA[ +version3() -> prev3a | prev3b | prev3c | v3 ]]></code> + <list type="bulleted"> + <item> + <p><em>prev3a</em></p> + <p>Preliminary version 3, based on TD-33</p> + </item> + <item> + <p><em>prev3b</em></p> + <p>Preliminary version 3, based on TD-33, but text encoding + updated with the final solution for priority in + <c><![CDATA[contextProperty]]></c> (which is backward compatible with v2).</p> + </item> + <item> + <p><em>prev3c</em></p> + <p>Preliminary version 3, based on the final version of the + v3-standard, but <em>excluding</em> segments!</p> + </item> + <item> + <p><em>v3</em></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> + </item> + </list> + <p>There are two ways to handle the different megaco encoding versions. + Either using <em>dynamic version detection</em> (only valid for + for incoming messages) or by <em>explicit version</em> setting in + the connection info.</p> + <p>For incoming messages:</p> + <list type="bulleted"> + <item> + <p>Dynamic version detection</p> + <p>Set the protocol version in the megaco_receive_handle to + <c><![CDATA[dynamic]]></c> (this is the default). + <br></br>This works for those codecs that support partial decode of the + version, currently <em>text</em>, and ber_bin + (<c><![CDATA[megaco_binary_encoder]]></c> and <c><![CDATA[megaco_ber_bin_encoder]]></c>). + <br></br>This way the decoder will detect which version is used and + then use the proper decoder. </p> + </item> + <item> + <p>Explicit version</p> + <p>Explicitly set the actual protocol version in the + megaco_receive_handle. + <br></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 + <seealso marker="megaco_tcp#upgrade_receive_handle">megaco_tcp</seealso> + and + <seealso marker="megaco_udp#upgrade_receive_handle">megaco_udp</seealso>. + <br></br>Note that if <c><![CDATA[udp]]></c> is used, the same transport process + could be used for several connections. This could make upgrading + impossible. + <br></br>For codecs that does not support partial decode of the version, + currently <c><![CDATA[megaco_ber_encoder]]></c>, <c><![CDATA[megaco_per_encoder]]></c> + and <c><![CDATA[megaco_per_bin_encoder]]></c>, <c><![CDATA[dynamic]]></c> will revert to + version 1.</p> + </item> + </list> + <p>For outgoing messages:</p> + <list type="bulleted"> + <item> + <p>Update the connection info protocol_version.</p> + </item> + <item> + <p>Override protocol version when sending a message by adding the + item <c><![CDATA[{protocol_version, integer()}]]></c> to the Options. + See + <seealso marker="megaco#call">call</seealso> or + <seealso marker="megaco#cast">cast</seealso>. + <br></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> + </item> + </list> + </section> + + <section> + <title>Encoder callback functions</title> + <p>The encoder callback interface is defined by the <c><![CDATA[megaco_encoder]]></c> + behaviour, see <seealso marker="megaco_encoder">megaco_encoder</seealso>.</p> + </section> +</chapter> + |