File: megaco_encode.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (690 lines) | stat: -rw-r--r-- 16,752 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>Internal form and its encodings</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="4"><!-- Empty --></A>
<H2>4 Internal form and its encodings</H2>

<P>This version of the stack is compliant with: 
<P>
<UL>

<LI>
Megaco/H.248 version 1 (RFC3525)
        updated according to Implementors Guide version 10-13.<BR>

</LI>


<LI>
Megaco/H.248 version 2 as defined by 
        draft-ietf-megaco-h248v2-04
        updated according to Implementors Guide version 10-13.<BR>

</LI>


<LI>
Megaco/H.248 version 3 as defined by 
        ITU H.248.1 (09/2005).<BR>

</LI>


</UL>
<A NAME="4.1"><!-- Empty --></A>
<H3>4.1 Internal form of messages</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>
&#34;SEQUENCE OF&#34; is represented as a list.<BR>

</LI>


<LI>
&#34;CHOICE&#34; is represented as a tagged tuple with size 2.<BR>

</LI>


<LI>
 &#34;SEQUENCE&#34; is represented as a record, defined in
         &#34;megaco/include/megaco_message_v1.hrl&#34;.<BR>

</LI>


<LI>
 &#34;OPTIONAL&#34; is represented as an ordinary field in a
         record which defaults to 'asn1_NOVALUE', meaning that the
         field has no value.<BR>

</LI>


<LI>
 &#34;OCTET STRING&#34; is represented as a list of unsigned integers.<BR>

</LI>


<LI>
 &#34;ENUMERATED&#34; is represented as a single atom.<BR>

</LI>


<LI>
 &#34;BIT STRING&#34; is represented as a list of atoms.<BR>

</LI>


<LI>
 &#34;BOOLEAN&#34; is represented as the atom 'true' or 'false'.<BR>

</LI>


<LI>
 &#34;INTEGER&#34; is represented as an integer.<BR>

</LI>


<LI>
 &#34;IA5String&#34; is represented as a list of integers,
         where each integer is the ASCII value of the corresponding
         character.<BR>

</LI>


<LI>
 &#34;NULL&#34; is represented as the atom 'NULL'.<BR>

</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>Observe that the 'TerminationId' record is not used in the
internal form. It has been replaced with a megaco_term_id record
(defined in &#34;megaco/include/megaco.hrl&#34;).<A NAME="4.2"><!-- Empty --></A>
<H3>4.2 The different encodings</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>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>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:
<PRE>
   MEGACO/1 [124.124.124.222]
   Transaction = 9998 {
           Context = - {
                   ServiceChange = ROOT {
                           Services {
                                   Method = Restart,
                                   ServiceChangeAddress = 55555,
                                   Profile = ResGW/1,
                                   Reason = &#34;901 Cold Boot&#34;
                           }
                   }
           }
   }
</PRE>

<P>Then the compact version without indentation and with short keywords:

<PRE>
 
   !/1 [124.124.124.222]
   T=9998{C=-{SC=ROOT{SV{MT=RS,AD=55555,PF=ResGW/1,RE=&#34;901 Cold Boot&#34;}}}}
</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:
<PRE>
  Prof = #'ServiceChangeProfile'{profileName = &#34;resgw&#34;, version = 1},
  Parm = #'ServiceChangeParm'{serviceChangeMethod  = restart,
                              serviceChangeAddress = {portNumber, 55555},
                              serviceChangeReason  = &#34;901 Cold Boot&#34;,
                              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:
<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, [&#34;root&#34;]}],
                {'ServiceChangeParm',
                 restart,
                 {portNumber, 55555},
                 asn1_NOVALUE,
                 {'ServiceChangeProfile', &#34;resgw&#34;, version = 1},
                 &#34;901 MG Cold Boot&#34;,
                 asn1_NOVALUE,
                 asn1_NOVALUE,
                 asn1_NOVALUE
                }
              }
             },
             asn1_NOVALUE,
             asn1_NOVALUE
            }
           ]
          }
         ]
       }
      }
     ]
    }
   }
  } 
</PRE>

<P>The following encoding modules are provided:


<P>
<UL>

<LI>
megaco_pretty_text_encoder - encodes messages into
         pretty text format, decodes both pretty as well as compact
         text.<BR>

</LI>


<LI>
megaco_compact_text_encoder - encodes messages into
         compact text format, decodes both pretty as well as compact
         text.<BR>

</LI>


<LI>
megaco_binary_encoder - encode/decode ASN.1 BER messages.
         This encoder implements the fastest of the BER encoders/decoders.
         Recommended binary codec.<BR>

</LI>


<LI>
megaco_ber_encoder - encode/decode ASN.1 BER 
         messages.<BR>

</LI>


<LI>
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.<BR>

</LI>


<LI>
megaco_per_encoder - encode/decode ASN.1 PER
         messages. N.B. that this format is not included in the
         Megaco standard.<BR>

</LI>


<LI>
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.<BR>

</LI>


<LI>
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.<BR>

</LI>


</UL>
<A NAME="erl_dist_config"><!-- Empty --></A><A NAME="4.3"><!-- Empty --></A>
<H3>4.3 Configuration of Erlang distribution encoding module</H3>

<P>The encoding_config of the megaco_erl_dist_encoder module
may be one of these:
<P>
<UL>

<LI>
<CODE>[]</CODE> - Encodes the messages to the standard distribution
         format. It is rather verbose but encoding and decoding is
         blinding fast.<BR>


</LI>


<LI>
<CODE>[megaco_compressed]</CODE> - 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 
         <A HREF="megaco_performance.html">performance</A> 
         chapter for more info).<BR>


</LI>


<LI>
<CODE>[{megaco_compressed,Module}]</CODE> - Works in the same
         way as the megaco_compressed config parameter, only here the 
         user provide their own compress module. The module must export 
         two functions: <CODE>encode/1</CODE> and <CODE>decode/1</CODE>.<BR>


</LI>


<LI>
<CODE>[compressed]</CODE> - 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.<BR>


</LI>


</UL>
<A NAME="text_config"><!-- Empty --></A><A NAME="4.4"><!-- Empty --></A>
<H3>4.4 Configuration of text encoding module(s)</H3>

<P>When using text encoding(s), there is actually two different
configs controlling what software to use:
<P>
<UL>

<LI>
<CODE>[]</CODE> - An empty list indicates that the erlang
         scanner should be used.<BR>


</LI>


<LI>
<CODE>[{flex, port()}]</CODE> - Use the flex scanner when 
         decoding.<BR>


</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>
Let the Megaco stack start the flex scanner 
         (load the driver).<BR>

        To make this happen the megaco stack has to be configured: 
        <BR>

<UL>

<LI>
Add the <CODE>{scanner, flex}</CODE> directive to an 
         Erlang system config file for the megaco app. This will 
         make the Megaco stack initiate the default 
         <CODE>megaco_receive_handle</CODE> with the encoding_config set 
         to the <CODE>[{flex, port()}]</CODE>. <BR>

         
</LI>


<LI>
When retrieving the <CODE>megaco_receive_handle</CODE>, 
         retain the encoding_config.<BR>

         
</LI>


</UL>


        The benefit of this is that Megaco handles the starting, holding
         and the supervision of the driver and port.<BR>



</LI>


<LI>
The Megaco client (user) starts the flex scanner (load the driver).<BR>

        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:<BR>


        <BR>


        
<UL>

<LI>
Create a permanent process. Make sure this process is
         supervised (so that if it does die, this will be noticed).<BR>

         
</LI>


<LI>
Let this process start the flex scanner by calling the 
         <CODE>megaco_flex_scanner:start()</CODE> function.<BR>

         
</LI>


<LI>
Retrieve the <CODE>port()</CODE> and when initiating
         the <CODE>megaco_receive_handle</CODE>, set the encoding_config to 
         [{flex, port()}].<BR>

         
</LI>


<LI>
Pass the <CODE>receive_handle</CODE> to the transport module.<BR>

         
</LI>


</UL>


</LI>


</UL>
<A NAME="binary_config"><!-- Empty --></A><A NAME="4.5"><!-- Empty --></A>
<H3>4.5 Configuration of binary encoding module(s)</H3>

<P>When using binary encoding, the structure of the termination id's 
needs to be specified.
<P>
<UL>

<LI>
        <CODE>[driver|_]</CODE> - make use of the asn1 driver for decode
         (ber_bin) and encode (per_bin). This option is only available for 
         encoding modules: <CODE>megaco_binary_encoder</CODE>, 
         <CODE>megaco_ber_bin_encoder</CODE> and <CODE>megaco_per_bin_encoder</CODE>.<BR>

        If this option is present in the encoding config, it <STRONG>must</STRONG> 
         to be the <STRONG>first</STRONG>, unless the 
         <A HREF="#handling_versions">version3</A> encoding 
         config is present, in which case it must come second, after 
         the version3 encoding config, 
         e.g. <CODE>[{version3,prev3b},driver]</CODE>.<BR>


</LI>


<LI>
<CODE>[native]</CODE> - skips the transformation phase, i.e. 
        the decoded message(s) will not be transformed into our internal
        form.<BR>


</LI>


<LI>
<CODE>[integer()]</CODE> - A list containing the size (the number 
         of bits) of each level. Example: <CODE>[3,8,5,8]</CODE>.<BR>


</LI>


<LI>
<CODE>integer()</CODE> - Number of one byte (8 bits) levels.
        N.B. This is currently converted into the previous config. 
        Example: <CODE>3</CODE> (<CODE>[8,8,8]</CODE>).<BR>


</LI>


</UL>
<A NAME="handling_versions"><!-- Empty --></A><A NAME="4.6"><!-- Empty --></A>
<H3>4.6 Handling megaco versions</H3>

<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 <CODE>{version3, version3()}</CODE> 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. 

<PRE>
version3() -&#62; prev3a | prev3b | prev3c
</PRE>

<P>
<UL>

<LI>
<STRONG>prev3a</STRONG><BR>

                 Preliminary version 3, based on TD-33
        <BR>


</LI>


<LI>
<STRONG>prev3b</STRONG><BR>

                 Preliminary version 3, based on TD-33, but text encoding 
updated with the final solution for priority in 
<CODE>contextProperty</CODE> (which is backward compatible with v2).
        <BR>


</LI>


<LI>
<STRONG>prev3c</STRONG><BR>

                 Preliminary version 3, based on the final version of the 
v3-standard, but excluding segments!
        <BR>


</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>For incomming messages:
<P>
<UL>

<LI>
Dynamic version detection<BR>

                 Set the protocol version in the megaco_receive_handle to 
<CODE>dynamic</CODE> (this is the default).
         <BR>
This works for those codecs that support partial decode of the 
version, currently <STRONG>text</STRONG>, and ber_bin 
(<CODE>megaco_binary_encoder</CODE> and <CODE>megaco_ber_bin_encoder</CODE>). 
         <BR>
This way the decoder will detect which version is used and 
         then use the proper decoder. 
        <BR>


</LI>


<LI>
Explicit version<BR>

                 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 
         <A HREF="megaco_tcp.html#upgrade_receive_handle">megaco_tcp</A>
         and 
         <A HREF="megaco_udp.html#upgrade_receive_handle">megaco_udp</A>.
         <BR>
Note that if <CODE>udp</CODE> 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 <CODE>megaco_ber_encoder</CODE>, <CODE>megaco_per_encoder</CODE>
and <CODE>megaco_per_bin_encoder</CODE>, <CODE>dynamic</CODE> will revert to 
version 1.
        <BR>


</LI>


</UL>

<P>For outgoing messages:
<P>
<UL>

<LI>
                 Update the connection info protocol_version.
        <BR>


</LI>


<LI>
                 Override protocol version when sending a message by adding the
         item <CODE>{protocol_version, integer()}</CODE> to the Options.
         See 
         <A HREF="megaco.html#call">call</A> or
         <A HREF="megaco.html#cast">cast</A>.
         <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.
        <BR>


</LI>


</UL>
<A NAME="4.7"><!-- Empty --></A>
<H3>4.7 Encoder callback functions</H3>

<P>The encoder callback interface is defined by the <CODE>megaco_encoder</CODE> 
behaviour, see <A HREF="megaco_encoder.html">megaco_encoder</A>.<CENTER>
<HR>
<SMALL>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>