This version of the stack is compliant with:
Megaco/H.248 version 1 (RFC3525) updated according to Implementors Guide version 10-13.
Megaco/H.248 version 2 as defined by draft-ietf-megaco-h248v2-04 updated according to Implementors Guide version 10-13.
Megaco/H.248 version 3 as defined by ITU H.248.1 (09/2005).
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:
"SEQUENCE OF" is represented as a list.
"CHOICE" is represented as a tagged tuple with size 2.
"SEQUENCE" is represented as a record, defined in "megaco/include/megaco_message_v1.hrl".
"OPTIONAL" is represented as an ordinary field in a record which defaults to 'asn1_NOVALUE', meaning that the field has no value.
"OCTET STRING" is represented as a list of unsigned integers.
"ENUMERATED" is represented as a single atom.
"BIT STRING" is represented as a list of atoms.
"BOOLEAN" is represented as the atom 'true' or 'false'.
"INTEGER" is represented as an integer.
"IA5String" is represented as a list of integers, where each integer is the ASCII value of the corresponding character.
"NULL" is represented as the atom 'NULL'.
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.
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").
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.
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).
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:
MEGACO/1 [124.124.124.222]
Transaction = 9998 {
Context = - {
ServiceChange = ROOT {
Services {
Method = Restart,
ServiceChangeAddress = 55555,
Profile = ResGW/1,
Reason = "901 Cold Boot"
}
}
}
}
Then the compact version without indentation and with short keywords:
!/1 [124.124.124.222]
T=9998{C=-{SC=ROOT{SV{MT=RS,AD=55555,PF=ResGW/1,RE="901 Cold Boot"}}}}
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:
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).
And finally a print-out of the entire internal form:
{'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
}
]
}
]
}
}
]
}
}
}
The following encoding modules are provided:
megaco_pretty_text_encoder - encodes messages into pretty text format, decodes both pretty as well as compact text.
megaco_compact_text_encoder - encodes messages into compact text format, decodes both pretty as well as compact text.
megaco_binary_encoder - encode/decode ASN.1 BER messages. This encoder implements the fastest of the BER encoders/decoders. Recommended binary codec.
megaco_ber_encoder - encode/decode ASN.1 BER messages.
megaco_per_encoder - encode/decode ASN.1 PER messages. N.B. that this format is not included in the Megaco standard.
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.
The encoding_config of the megaco_erl_dist_encoder module may be one of these:
When using text encoding(s), there is actually two different configs controlling what software to use:
The Flex scanner is a Megaco scanner written as a linked in driver (in C). There are two ways to get this working:
Let the Megaco stack start the flex scanner (load the driver).
To make this happen the megaco stack has to be configured:
Add the
Retrieve the encoding-config using the
Update the receive handle with the encoding-config
(the
The benefit of this is that Megaco handles the starting, holding and the supervision of the driver and port.
The Megaco client (user) starts the flex scanner (load the driver).
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:
Create a permanent process. Make sure this process is supervised (so that if it does die, this will be noticed).
Let this process start the flex scanner by calling the
Retrieve the encoding-config and when initiating
the
Pass the
When using binary encoding, the structure of the termination id's needs to be specified.
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
prev3a | prev3b | prev3c | v3 ]]>
prev3a
Preliminary version 3, based on TD-33
prev3b
Preliminary version 3, based on TD-33, but text encoding
updated with the final solution for priority in
prev3c
Preliminary version 3, based on the final version of the v3-standard, but excluding segments!
v3
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).
There are two ways to handle the different megaco encoding versions. Either using dynamic version detection (only valid for for incoming messages) or by explicit version setting in the connection info.
For incoming messages:
Dynamic version detection
Set the protocol version in the megaco_receive_handle to
This works for those codecs that support partial decode of the
version, currently text, and ber_bin
(
This way the decoder will detect which version is used and
then use the proper decoder.
Explicit version
Explicitly set the actual protocol version in the
megaco_receive_handle.
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
Note that if
For codecs that does not support partial decode of the version,
currently
For outgoing messages:
Update the connection info protocol_version.
Override protocol version when sending a message by adding the
item
Note that this does not effect the messages that are sent
autonomously by the stack. They use the protocol_version of the
connection info.
The encoder callback interface is defined by the