The R13B03 release.OTP_R13B03

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&aring;kan Mattsson</prepared>
+    <responsible>H&aring;kan Mattsson</responsible>
+    <docno></docno>
+    <approved>H&aring;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>
+