Erlang/OTP Megaco Stack

8/13/2019 Erlang/OTP Megaco Stack

1/84

Megaco/H.248

version 3.3


2/84

Typeset in LATEX from SG ML source using the D O C BUILD ER 3.3.2 D ocument System.


3/84

Contents

1 Megaco UsersGuide 1

1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Scope and P urpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.2 P rereq uisit es . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.3 About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.4 Wh ere t o Find M ore Inf orm at ion . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.1 Net work view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.2 G eneral . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.3 Single node con g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.4 D istributed con g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.2.5 M essage round -t rip call ow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.3 Running t he stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.1 Starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.3.2 MG C start up call ow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.3.3 MG st art up call ow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1.3.4 C o n guring t he M ega co st ack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1.3.5 Init ial con gura tion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.3.6 C h anging t he con gurat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.3.7 Th e t ransa ct ion send er . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.4 Int erna l form and it s encod ings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.4.1 Int erna l form of m essa ges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.4.2 Th e d iff erent encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

1.4.3 Congurat ion of Erlang distr ibut ion encoding module . . . . . . . . . . . . . . . 161.4.4 Congura t ion of t ex t encoding module(s) . . . . . . . . . . . . . . . . . . . . . 17

1.4.5 Congura t ion of b inary encoding module(s) . . . . . . . . . . . . . . . . . . . . 17

1.4.6 H and ling m ega co versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1. 4. 7 Enco der ca llb ack f unct ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.5 Transport m echanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.5.1 C allback int erface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

iiiMegaco /H .248


4/84

1.5.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1.6 Implem ent at ion examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

1. 6. 1 A sim ple M ed ia G a tew a y C o nt ro ller . . . . . . . . . . . . . . . . . . . . . . . . 19

1.6.2 A simple Media G at ew ay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.7 Megaco mib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.7.1 Intro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.7.2 St at ist ics count ers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

1.7.3 D istribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.8 Performace comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1. 8. 1 C o mp ariso n o f enco der/d eco ders . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.8.2 Descrip tion of encoders/decoders . . . . . . . . . . . . . . . . . . . . . . . . . . 25

1.8.3 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1. 8. 4 C o mplet e m ea su rem ent resu lt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

1.8.5 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1.9 Testing and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271.9.1 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

1. 9. 2 M ea su rem ent a nd t ra nsf orm at io n . . . . . . . . . . . . . . . . . . . . . . . . . . 28

2 Megaco ReferenceManual 31

2.1 megaco . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

2.2 megaco codec meas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

2.3 megaco codec t ransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

2.4 megaco encoder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

2.5 megaco ex scanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

2.6 megaco tcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

2.7 megaco transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

2.8 megaco udp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

2.9 megaco user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Listof Figures 73

Listof Tables 75

iv Megaco/H .248


5/84

Chapter 1

Megaco Users Guide

The Megaco a pplication is a framew ork for building applications on top of t he Megaco/H .248 protocol.

1.1 Introduction

Megaco/H .248 is a prot ocol for control of elements in a ph ysically decom posed multimedia gat ewa y,enabling separation of call control from media conversion. A Media G atew ay C ontroller (MG C)controls one or more M edia G ateway s (MG ).

This version of the stack supports both version 1 and version 2 as dened by:

version 1 - RFC 3525 &H .248-IG (v10-v13)

version 2 - draft -ietf-megaco-h248v2-04 & H .248.1 v2 C orrigendum 1 (03/2004)

version 3 - TD -33 (except segments)

The semantics of the prot ocol has jointly been de ned by tw o standardization bodies: IETF - which calls the protocol Megaco

ITU - which calls the protocol H .248

1.1.1 Scope and Purpose

This manual d escribes the Megaco a ppliacation, a s a com ponent of the Erlang/O pen Telecom Plat formdevelopment environment. It is assumed t hat the reader is familiar w ith t he Erlang D evelopmentEnvironment, which is described in a separate User's G uide.

1.1.2 PrerequisitesThe following prerequisites is required for understanding the material in the Megaco User's G uide:

the b asics of t he Megaco/H .248 protocol

the basics of the Abstract Sy ntax N otation O ne (ASN.1)

familiarity w ith t he Erlang system and Erlang programming

The applicat ion req uires Erlang/O TP release R7B or lat er.

1Megaco /H .248


6/84

Chapter 1: Megaco Users Guide

1.1.3 About This Manual

In add ition to this introductory chapter, the Megaco U ser's G uide contains the follow ing chapters:

C hapter 2: Architecture describes the a rchitecture and typical usage of t he application.

C hapt er 3: Internal form and its encodings describes the internal form of Megaco/H .248

messages and its various encodings. C hapt er 4: Transport mechanisms describes how different mecha nisms can be used to transport

th e Megaco /H .248 messages.

C hapt er 5: D ebugging describes tracing and debugging.

1.1.4 Where to Find More Information

Refer to the following documentation for more information about Megaco/H.248 and about theErlang/O TP developm ent system:

version 1, RFC 3525 1

old version 1, RFC 30152

Version 2 C orrigendum 1 3

version 2, draft-ietf-megaco-h248v2-04 4

D raft H .248.1 version 3 5

the ASN.1 U ser's G uide

the Reference Manual

C oncurrent Programm ing in Erlang, 2nd Edit ion (1996), Prentice-H all, ISBN 0-13-508301-X .

1.2 Architecture

1.2.1 Network view

Megaco is a (master/slave) protocol for control of gat eway functions at t he edge of t he packet netw ork.Examples of this is IP-PSTN trunking gateways and analog line gateways. The main function of Megacois to allow gateway decomposition into a call agent (call control) part (known as Media G atew ayController, MG C) - master, and an gateway interface part (known as Media G ateway, MG ) - slave. TheMG has no call control know ledge and only hand le making the connections and simple congurat ions.

SIP and H.323 are peer-to-peer protocols for call control (valid only for some of the protocols withinH.323), or more generally multi-media session protocols. They both operate at a different level (callcontrol) from M egaco in a decomposed netw ork, and are therefor not aw are of w ether or not Megaco isbeing used underneath.

1 URL: http://www.erlang.org/project/megaco/standard/rfc3525.txt2 URL: http://www.ietf.org/rfc/rfc3015.txt3 URL: http://www.erlang.org/project/megaco/standard/H.248.1-Corr1-200403.doc4 URL: http://www.erlang.org/project/megaco/standard/draft-ietf-megaco-h248v2-04.txt5 URL: http://www.erlang.org/project/megaco/standard/td-33 h.248.1v3.doc

2 Megaco/H .248


7/84

1.2: Architecture

Figure 1.1: Network architecture

Megaco and peer protocols are complementary in nature and entirely compatible w ithin the samesystem. At a system level, Megaco allows for

overall network cost and performance optimization

protection of investment by isolation of changes at the call control layer

freedom to geographically distribute b oth call function and gatew ay function

adaption of legacy equipment

3Megaco /H .248


8/84


1.2.2 General

This Erlang/OTP applicat ion supplies a framew ork for building applications tha t needs t o ut ilize t heMegaco/H .248 prot ocol.

We have introduced t he term user as a generic term f or either an MG or an M G C, since most of thefunctionality w e support, is common for b oth MG 's and MG C's. A (local) user may be congured in

various way s and it may establish any number of connections to its counterpart, th e remote user. O ncea connection has been established, the connection is supervised and it may be used for the purpose ofsending messages. N.B. according to t he standard an MG is connected to a t most one MG C, w hile anMG C may be connected to any number of MG 's.

For the purpose of m anaging virtual MG 's, one Erlang node m ay host any number of M G 's. In fact itmay host a mix of MG 's and MG C 's. You may say that an Erlang node may h ost any number of users.

The prot ocol engine uses callback mo dules to handle various things:

encoding callback modules - handles the encoding and decoding of messages. Several modules forhandling different encodings are included, such as ASN.1 BER, pretty well indented text,compact text and some others. Others may be written by you.

transport callback m odules - handles sending and receiving of messages. Transport m odules forTC P/IP and UD P/IP are included and others may be w ritten by y ou.

user callback modules - the actual implementation of an MG or MG C. Most of the functions areintended for handling of a decoded transaction (request, reply, acknowledgement), but there areothers that handles connect, disconnect and errors cases.

Each connection may have its own conguration of callback modules, re-send timers, transaction idranges etc. and they may be re-congured on-the-y.

In the API of Megaco, a user may explicitely send action requests, but generation of transactionidentiers, the encoding and actual transport of the message to the remote user is handled automaticallyby the protocol engine according to t he actual connection conguration. Megaco messages are notexposed in the API.

On the receiving side the transport module receives the message and forwards it to the protocol engine,which decodes it and invokes user callback functions for each transaction. When a user has handled itsaction requests, it simply returns a list of action replies (or a message error) and the protocol engine usesthe encoding module and transport module to compose and forward the message to the originating user.

The protocol stack does also handle things like automatic sending of acknowledgements, pendingtransactions, re-send of messages, supervision of connections etc.

In order to provide a solution for scalable implementations of MG 's and MG C's, a user may bedistributed over several Erlang nodes. One of the Erlang nodes is connected to the physical networkinterface, but messages may be sent from ot her nodes and th e replies are automa tically forwarded backto the originating node.

4 Megaco/H .248


9/84

1.2: Architecture

1.2.3 Single node cong

H ere a system conguration with an MG and M G C residing in one Erlang node each is outlined:

Figure 1.2: Single node cong

1.2.4 Distributed cong

In a larger system with a user (in this case an MG C) distributed over several Erlang nodes, it looks alittle b it different. Here th e encoding is performed on the originating Erlang node (1) and the binary is

forwarded t o t he node (2) w ith t he physical netw ork interface. When the potential message reply isreceived on t he interface on node (2), it is decoded there and then different actions will be t aken f oreach transaction in the message. The t ransaction reply w ill be forw arded in its decoded form to theoriginating node (1) w hile the other t ypes of transactions w ill be h andled locally on node (2).

Timers and re-send of m essages w ill be handled on locally on one nod e, that is node(1), in ord er toavoid unneccessary transfer of data between the Erlang nodes.

5Megaco /H .248


10/84


Figure 1.3: D istribut es node con g

1.2.5 Message round-trip call ow

The ty pical round-trip of a message can b e view ed as follows. Firstly w e view the call ow on th eoriginating side:

6 Megaco/H .248


11/84

1.2: Architecture

main encoder transportuser

megaco:cast/3

EncMod:decode_message/4

(ack requested)

EncMod:encode_message

megaco:recieve_message/4

SendMod:send_message/2

UserMod:handle_trans_reply/4


EncMod:encode_message/2

recieve bytes(2)

send bytes(1)

send bytes(3)

Figure 1.4: Message C all Flow (originating side)

Then w e continue with the call ow on the destination side:

7Megaco /H .248


12/84


transport user

megaco:receive_message/2


UserMod:handle_trans_requeat/3



megaco:receive_message/4


send bytes(2)

receive bytes(3)

receive bytes(1)

UserMod:handle_trans_ack/4

encodermain

Figure 1.5: Message Call Flow (destination side)

1.3 Running the stack

1.3.1 Starting

A user may have a number of virtual connections to other users. An MG is connected t o at most oneMG C, w hile an MG C may be connected to a ny number of MG 's. For each connection the user selects atransport service, an encoding scheme and a user callback module.

An MG C must initiate its transport service in order to listen t o MG 's trying to connect. H ow the act ualtransport is initiated is outside the scope of this application. However a send handle (typically a socketid or host and port) must be provided from t he transport service in order to enable us to send t hemessage to the correct destination. We do how ever not a ssume anyth ing about t his, from our point ofview, opaq ue handle. H opefully it is rather small since it w ill passed around t he system betw eenprocesses rather frequ ently.

8 Megaco/H .248


13/84

1.3: Running the stack

A user may either be statically congured in a .cong le according to t he application concept ofErlang/O TP or dynam ically started w ith t he con guration settings as arguments to megaco:start user/2.These con guration sett ings may be updat ed later on w ith megaco:upd ate conn info/2.

The funct ion megaco:connect/4 is used to tell the Megaco application a bout w hich control process itshould supervise, which MID the remote user has, which callback module it should use to sendmessages etc. When t his virtual connection is estab lished t he user may use megaco:call/3 andmegaco:cast/3 in order to send messages to th e other side. Then it is up to t he MG to send its rstService Change Request message after applying some clever algorithm in order to ght the problemw ith startup avalanche (as discussed in t he RFC).

The originating user will wait for a reply or a timeout (dened by the request timer). When it receivesthe reply this will optionally be a cknow ledged (regulated by auto ack), and forwa rded to t he user. If aninterim pending reply is received, the long request timer will be used instead of the usual request timer,in order to enable avoidance of spurious re-sends of the request.

On the destination side the transport service waits for messages. Each message is forwarded to theMegaco a pplication via t he megaco:receive m essage/4 callback function. The t ransport service may ormay not provide means for blocking and unblocking the reception of the incoming messages.

If a message is received before the virtual connection has been established, the connection will be

setup a utomat ically. An MG C may be real open minded and dy namically decide w hich encoding andtransport service to use depending on how the transport layer contact is performed. For IP transportstw o ports are standardized, one for textual encoding and one for binary encoding. If for example anUD P packet w as received on the t ext port it w ould be possible to decide encoding and t ransport on t he y.

After decoding a message various user callback functions are invoked in order to allow the user to actproperly. See the megaco user module for more info about the callback arguments.

When the user has processed a transaction request in its callback function, the Megaco applicationassembles a transaction reply, encodes it using the selected encoding module and sends the messageback by invoking the callback function:

SendMod:send message(SendHandle, ErlangBinary)

Re-send of messages, handling pending transactions, acknowledgements etc. is handled automatically bythe M egaco application but the user is free to override the default behaviour by the variouscon guration possibilities. S ee megaco:updat e u ser info/2 and megaco:up dat e co nn info/2 about thepossibilities.

When connections gets broken (that is explicitly by m egaco:disconnect/2 or w hen its controllingprocess dies) a user callback function is invoked in order t o allow the user to re-establish t heconnection. The internal state of kept messages, re-send timers etc. is not affected by this. A few re-sends will of course fail while the connection is down, but the automatic re-send algorithm does notbother about this and eventually w hen the connection is up and running the messages will be deliveredif the timeouts are set to be long enough. The user has the option of explicitly invokingmegaco:cancel/2 t o ca ncel all messages for a connection.

1.3.2 MGC startup call ow

In order to prepare the MG C for th e reception of the initial message, hopefully a Service C hangeRequest, the following needs to be done:

Start the Megaco application.

Sta rt t he MG C user. This may eith er be done explicitly w ith m egaco:start user/2 or implicitly byproviding the -megaco users conguration parameter.

9Megaco /H .248


14/84


Initiate the t ransport service and provide it w ith a receive handle obta ined frommegaco:user inf o/2.

When the initial message arrives the transport service forwards it to the protocol engine whichaut omat ically sets up th e connection and invokes UserMod:hand le connect/2 before it invokesU serMod: handle trans req uest/3 w ith th e Service C hange Request like this:

transport user

receive bytes(1)megaco:receive_message/4


UserMod:handle_connect/3


send bytes(2)

encodermain


Figure 1.6: MG C Startup C all Flow

1.3.3 MG startup call ow

In order to prepare the MG for th e sending of th e initial message, hopefully a Service C hange Request,the follow ing needs to be done:

Start the Megaco application.

Sta rt t he MG user. This may either be done explicitly w ith m egaco:start user/2 or implicitly byproviding the -megaco users conguration parameter.

Initiate the t ransport service and provide it w ith a receive handle obta ined frommegaco:user inf o/2.

Setup a connection to the MG C w ith m egaco:connect/4 and provide it w ith a receive handleobt ained from megaco:user info/2.

If the MG has been provisioned with the MID of the MG C it can be given as the RemoteMidparamet er to megaco:connect /4 and t he call ow w ill look like this:

10 Megaco/H .248


15/84


main encoderuser

UserMod:handle_connect/2

(return of mecaco:return/4)

megaco:call/3


(return of megaco:call/3)

EndMod:encode_message/2


megaco_receive_message/4

megaco:connect/4

transport

receive bytes(2)

send bytes(1)

Figure 1.7: M G Startup C all Flow

If the MG cannot be provisioned with the MID of the MG C, the MG can use the atom'preliminary mid' a s the Remot eMid parameter to megaco:connect/4 a nd t he call ow w ill look likethis:

11Megaco /H .248


16/84


main encoder transportuser

(return of mecaco:return/4)

megaco:call/3

SendMod:send_message/2send bytes(1)

EndMod:encode_message/2

UserMod:handle_connect/2 (RemoteMid = preliminary.mid)

megaco:connect/4 (RemoteMid = preliminary.mid)

receive bytes(2)

megaco_receive_message/4


(return of megaco:call/3)

UserMod:handle_connect/2 (RemoteMid = actual MID of MGC)

Figure 1.8: MG Startup C all Flow (no MID )

1.3.4 Conguring the Megaco stack

There are three kinds of conguration:

U ser info - Informa tion related to megaco users. Read/Write.A User is an entity identied by a MID, e.g. a MG C or a MG.This information can be retrieved using megaco:user info [page 38].

C onnection info - Information regarding connections. Read/Write.This information can be retrieved using megaco:conn info [page 40].

System info - System w ide information. Read only.This information can be retrieved using megaco:system info [page 43].

12 Megaco/H .248


17/84


1.3.5 Initial conguration

The initial conguration of the Megaco should be dened in the Erlang system conguration le. Thefollow ing congured parameters are dened for the Megaco application:

users = [ f Mid, [user config()] g ].Each user is represented by a tuple w ith t he Mid of t he user and a list of con g parameters (eachparameter is in t urn a tuple: f Item, Value g ).

scanner = flex | f Module, Function, Arguments, Modules g flex will result in the start of the ex scanner.The other alternative makes it possible for Megaco to start and supervise a scanner written by theuser (see supervisor:start child for an explanation of the pa rameters).

1.3.6 Changing the conguration

The conguration can be changed during runtime. This is done with the functionsmegaco:update user info [page 40] and m egaco:update conn info [page 43]

1.3.7 The transaction sender

The transaction sender is a process (one per connection), which handle all transaction sending, if socongured (see megaco:user info [page 38] and megaco:conn info [page 40]).

The purpose of the transaction sender is to accumulate transactions for a more efcient messagesending. The transactions that are accumulated are transaction request and transaction ack. Fortransaction ack's the benet is quite large, since the transactions are small and it is possible to haveranges (which means that transaction acks for transactions 1, 2, 3 and 4 can be sent as a range 1-4 in onetransaction ack, instead of four separate transactions).

There are a number of conguration parameter's that control the operation of the transaction sender. Inprinciple, a message w ith everyt hing stored (ack's and request's) is sent from the process when:

When trans timer expires.

When trans ack maxcount number of ack's has been received.

When trans req maxcount number of requests's has been received.

When the size of all received requests exceeds trans req maxsize .

When a reply transaction is sent.

When a pending transaction is sent.

When something is to be sent, everything is packed into one message. Unless the trigger was a replytransaction and the ad ded size of the reply and all the requests is greater th en trans req maxsize , inw hich case the stored transcations is sent rts in a separate mesage, and the t he reply in another

message.When the transaction sender receives a request which is already in storage (indicated by thetransaction id) it is assumed to be a resend and everything stored is sent. This could happen if the valuesof the trans timer and the request timer is not properly choosen.

13Megaco /H .248


18/84


1.4 Internal form and its encodings

This version of the stack is compliant with:

Megaco/H .248 version 1 (RFC3525) upd ated according t o Im plementors G uide version 10-13.

Megaco/H .248 version 2 a s dened by draft -ietf-megaco-h248v2-04 upda ted according t oImplementors G uide version 10-13.

1.4.1 Internal form of messages

We use the same internal form for both the binary and text encoding. O ur internal form ofMegaco/H .248 messages is heavily inuenced by the internal form at used by ASN.1 encoders/decoders:

SEQ UEN C E O F is represented as a list.

CHOICE is represented as a tagged tuple with size 2.

SEQ U ENC E is represented as a record, d ened in megaco/include/megaco message v1.hrl.

O PTIO NAL is represented as an ordinary eld in a record w hich defaults to 'asn1 NOVALUE',

meaning that t he eld ha s no value. O C TET STRING is represented as a list of unsigned integers.

ENU MERATED is represented as a single atom.

BIT STRING is represented as a list of at oms.

BO O LEAN is represented as the atom 'true' or 'false'.

INTEG ER is represented as an integer.

IA5String is represented as a list of integers, where each integer is the ASCII value of thecorresponding charact er.

NU LL is represented as t he at om 'NU LL'.

In order to fully understand the internal form you m ust get hold on a ASN.1 specicat ion for theMegaco/H .248 protocol, and apply t he rules above. P lease, see the d ocumenta tion of t he ASN.1compiler in Erlang/O TP f or more det ails of t he semantics in mapping betw een ASN.1 and thecorresponding internal form.

O bserve that the 'TerminationId' record is not used in the internal form. It ha s been replaced w ith amegaco term id record (d ened in megaco/include/megaco.hrl).

1.4.2 The different encodings

The Megaco/H .248 standard denes bot h a plain text encoding and a binary encoding (ASN.1 BER)and w e have implemented encoders and d ecoders for both. We do in fact supply ve differentencoding/decod ing modules.

In the text encoding, implementors have the choice of using a mix of short and long keywords. It is alsopossible to add white spaces to improve readability. We use the term compact for text messages withthe shortest possible keyw ords and no opt ional white spaces, and the t erm pretty for a w ell indentedtext forma t using long keyw ords and an indenta tion style like the t ext exam ples in the Megaco/H .248specication).

H ere follows an example of a t ext message to give a f eeling of the d ifference betw een the pretty andcompact versions of text messages. First the pretty, well indented version with long keywords:

14 Megaco/H .248


19/84

1.4: Internal form and its encodings

MEGACO/1 [124.124.124.222]Transaction = 9998 f

Context = - f ServiceChange = ROOT f

Services f Method = Restart,

ServiceChangeAddress = 55555,Profile = ResGW/1,Reason = "901 Cold Boot"

g

g

g

g

Then the compact version without indentation and w ith short keyw ords:

!/1 [124.124.124.222]T=9998 f C=- f SC=ROOTf SVf MT=RS,AD=55555,PF=ResGW/1,RE="901 Cold Boot" g g g g

And the programmers view of the same message. First a list of ActionRequest records are constructedand t hen it is sent w ith one of t he send functions in th e API:

Prof = #ServiceChangeProfile f profileName = "resgw", version = 1 g ,Parm = #ServiceChangeParm f serviceChangeMethod = restart,

serviceChangeAddress = f portNumber, 55555 g ,serviceChangeReason = "901 Cold Boot",serviceChangeProfile = Prof g ,

Req = #ServiceChangeRequest f terminationID = [?megaco root termination id],serviceChangeParms = Parm g ,

Actions = [#ActionRequest f contextId = ?megaco null context id,

commandRequests =f

serviceChangeReq, Req g g

], megaco:call(ConnHandle, Actions, Config).

And nally a print-out of t he entire internal form:

f MegacoMessage,asn1 NOVALUE,f Message,

1,f ip4Address, f IP4Address, [124,124,124,222], asn1 NOVALUE g g ,f transactions,

[f transactionRequest,

f TransactionRequest,9998,[ f ActionRequest,

0,asn1 NOVALUE,asn1 NOVALUE,[

f CommandRequest,f serviceChangeReq,

15Megaco /H .248


20/84


f ServiceChangeRequest,[

f megaco term id, false, ["root"] g ],f ServiceChangeParm,

restart,f portNumber, 55555 g ,

asn1 NOVALUE,f ServiceChangeProfile, "resgw", version = 1 g ,"901 MG Cold Boot",asn1 NOVALUE,asn1 NOVALUE,asn1 NOVALUE

g

g

g ,asn1 NOVALUE,asn1 NOVALUE

g

]g

]g

g

]g

g

g

The following encoding modules are provided:

megaco pretty text encoder - encodes messages into pretty text forma t, d ecodes both pretty aswell as compact text.

megaco compact text encoder - encodes messages into compact text forma t, d ecodes both prettyas well as compact text.

megaco binary encoder - encode/decode ASN.1 B ER m essages. This encoder implements th efastest of the B ER encoders/decoders. Recommended binary cod ec.

megaco ber encoder - encode/decode ASN.1 B ER messages.

megaco ber bin encoder - encode/decode ASN.1 BE R m essages. This encoder uses ASN.1 ber binw hich has been optimized using the bit syntax.

megaco per encoder - encode/decode ASN.1 PER m essages. N.B. that this forma t is not includedin the Megaco standard.

megaco per b in encoder - encode/decode ASN.1 PER m essages. N.B. that this format is not

included in the Megaco standard. This encoder uses ASN.1 per bin which has been optimizedusing the bit syntax.

megaco erl dist encoder - encodes messages into Erlangs distribution format. It is rather verbosebut encoding and d ecoding is blinding fast. N.B. t hat this format is not included in the Megacostandard.

1.4.3 Conguration of Erlang distribution encoding module

The encoding cong of t he megaco erl dist encoder module may be one of th ese:

16 Megaco/H .248


21/84

1.4: Internal form and its encodings

[] - Encodes the messages to the standard distribution format. It is rather verbose but encodingand decoding is blinding fast.

[megaco compressed] - Encodes the messages to the standard distribution format after aninternal transformation. It is less verbose, but the t otal time of the encoding and d ecoding w ill onthe ot her hand b e somewhat slow er (see the performance [page 21] chapter for m ore info).

[ f megaco compressed,Module g ] - Works in the same way as the megaco compressed congparameter, only here the user provide their own compress module. The module must export twofunctions: encode/1 and decode/1 .

[compressed] - 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.

1.4.4 Conguration of text encoding module(s)

When using text encoding(s), t here is actually tw o different congs controlling wha t software t o use:

[] - An empty list indicates that the erlang scanner should be used.

[ f flex, port() g ] - Use the ex scanner w hen decoding.

The Flex scanner is a Megaco scanner written as a linked in driver (in C). There are two ways to get thisworking:

Let t he Megaco stack start the ex scanner (load the driver).To m ake this happen the m egaco stack has to be congured:

Add the f scanner, flex g directive to an Erlang system con g le for the megaco app. Thisw ill make the Megaco stack initiate t he default megaco receive handle with theencoding cong set to the [ f flex, port() g ] .

When retrieving the megaco receive handle , retain the encoding cong.

The benet of this is that Megaco handles the starting, holding and the supervision of the driverand port.

The Megaco client (user) starts the ex scanner (load the driver).When starting the ex scanner a port to the linked in driver is created. This port has to be ow nedby 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, thisw ill be noticed).

Let this process start the ex scanner by calling the megaco flex scanner:start() function. Retrieve the port() and when initiating the megaco receive handle , set the

encoding cong to [ f ex, port() g ]. Pass the receive handle to the t ransport module.

1.4.5 Conguration of binary encoding module(s)When using binary encoding, the structure of the termination id's needs to be specied.

[driver| ] - make use of the asn1 driver for decode (ber bin) and encode (per bin). This optionis only available for encoding modules: megaco binary encoder , megaco ber bin encoder and megaco per bin encoder .If this option is present in the encoding cong, it must to be the rst , unless the version3 [page18] encoding cong is present, in which case it must come second, after the version3 encodingcong, e.g. [ f version3,prev3b g ,driver] .

17Megaco /H .248


22/84


23/84

1.5: Transport mechanisms

1.4.7 Encoder callback functions

The encoder callback interface is dened by the megaco encoder behaviour, see megaco encoder [page57].

1.5 Transport mechanisms1.5.1 Callback interface

The callback interface of the transport module contains several functions. Some of which aremandatory w hile others are only opt ional:

send message - Send a message. M andatory block - Block the transport. O ptional

This function is usefull for ow control.

unblock - Unblock the transport. Optional

For more detail, see the megaco transport [page 63] behaviour denition.

1.5.2 Examples

The Megaco/H .248 application conta ins implementat ions for the tw o protoco ls speci ed by t heMegaco/H .248 standard; U D P, see megaco udp [pa ge 64], and TC P/TPK T, see megaco tcp [page 60].

1.6 Implementation examples

1.6.1 A simple Media Gateway Controller

In megaco/examples/simple/megaco simple mgc.erl there is an exa mple of a simple MG C tha t listenson both text a nd binary standard ports and is prepared to h andle a Service C hange Request m essage toarrive either via TC P/IP or U D P/IP. Messages received on th e text port a re decoded using a t extdecoder and messages received on the binary port are decoded using a binary decoder.

The Service C hange Reply is encoded in the same w ay as the request and sent b ack to the MG w ith thesame transport mechanism U D P/IP or TC P/IP.

After this initial service change message the connect ion betw een the MG and M G C is fully estab lishedand supervised.

The MG C, w ith its four listeners, may be started w ith:

cd megaco/examples/simpleerl -pa ../../../megaco/ebin -s megaco filter -s megaco megaco simple mgc:start().

or simply 'gmake mgc'.

The -s megaco lter option to erl implies, the event tracing mechanism to be enabled and an interactivesequence chart tool to be started. This may be quite useful in order to visualize how your MG Cinteracts w ith th e Megaco/H .248 protocol stack.

The event traces may alternatively be directed t o a le for later analyze. By d efault the event t racing isdisabled, but it may dynamically be enabled w ithout any need for re-compilation of t he code.

19Megaco /H .248


24/84


1.6.2 A simple Media Gateway

In megaco/examples/simple/megaco simple mg.erl there is an exam ple of a simple MG tha t connectsto an MG C, sends a Service C hange Request and w aits synchronously for a reply.

After this initial service change message the connection between the MG and MG C is fully establishedand supervised.

Assuming th at the M G C is started on th e local host, four d ifferent MG 's, using text over TC P/IP, binaryover TC P/IP, text over UD P/IP and binary over UD P/IP m ay be started on the same Erlang node w ith:

cd megaco/examples/simpleerl -pa ../../../megaco/ebin -s megaco filter -s megaco megaco simple mg:start().

or simply 'gmake mg'.

If you only want to start a single MG which tries to connect an MG on a host named baidarka, youmay use one of th ese functions (instead of t he megaco simple mg:start/0 above):

megaco simple mg:start tcp text("baidarka", []). megaco simple mg:start tcp binary("baidarka", []). megaco simple mg:start udp text("baidarka", []). megaco simple mg:start udp binary("baidarka", []).

The -s megaco lter option to erl implies, the event tracing mechanism to be enabled and an interactivesequence chart t ool to be started. This may be q uite useful in order to visualize how your MG interactsw ith th e Megaco/H .248 protocol stack.

The event traces may a lternatively b e directed t o a le for later analyze. By default the event t racing isdisabled, but it ma y dy namically b e enabled w ithout any need for re-compilation of t he code.

1.7 Megaco mib

1.7.1 Intro

The Megaco mib is as of yet not standardized and our implementation is based ondraft-ietf-megaco-mib-04.txt . Almost all of the mib cannot easily b e implemented by the megacoapplication. Instead these things should be implemented by a user (of the megaco application).

So w hat part of the mib is implemented? Ba sically the relevant statistic counters of th eM edG wyG atewayStatsEntry .

1.7.2 Statistics counters

The implementation of the statistic counters is lightweight. I.e. the statistic counters are handledseparatelly by different entities of the application. For instance our two transport module(s) (seemegaco tcp [page 61] and megaco udp [page 65]) maintain their own counters and the applicationengine (see megaco [page 52]) maintain it's own counters.

This also means that if a user implement t heir own transport service then it has to maintain it's ow nstatistics.

20 Megaco/H .248


25/84

1.8: Performace comparison

1.7.3 Distribution

Each m egaco application m aintains it's ow n set of count ers. So in a large (distributed) MG /MG C itcould be neccessary to collect the statistics from several nodes (each) running the megaco application(only one of them with the transport).

1.8 Performace comparison

1.8.1 Comparison of encoder/decoders

The Megaco/H .248 stand ard de nes bot h a plain text encoding and a binary encoding (ASN.1 BER)and w e have implemented encoders and decoders for both. We do supply a b unch of differentencoding/decoding modu les and t he user may in fact implement t heir ow n (like our erl dist mo dule).Using a non-standard encoding format has its obvious drawbacks, but may be useful in somecongurations.

We have ma de four d ifferent measurements of ou r Erlang/OTP implementa tion o f t he Megaco/H .248protocol sta ck, in order t o com pare our different encoders/decoders. The result of each one is

summarized in a line chart:

21Megaco /H .248


26/84


Encoded message size in bytes

Figure 1.9: Encoded message size in bytes

22 Megaco/H .248


27/84


Encode time in micro seconds

Figure 1.10: Encode time in micro seconds

23Megaco /H .248


28/84


Decode time in micro seconds

Figure 1.11: D ecode time in micro seconds

24 Megaco/H .248


29/84


Sum of encode and decode time in micro seconds

Figure 1.12: Sum of encode and decode time in micro seconds

1.8.2 Description of encoders/decoders

In Appendix A of the Megaco/H .248 specicat ion (RFC 3525), there are about 30 messages that show sa representative call ow. We have also added a few extra version 1 messages and also some version 2messages. We have used th ese example messages as basis for our measurements. The num bers w ithinparentheses are the plain average values. Our gures have not been weighted in regard to how frequentthe d ifferent kinds of messages that are sent betw een the media gateway and its controller.

The t est com pares th e follow ing encoder/decoders:

pretty - pretty printed t ext. In the text encoding, t he protocol stack implementors have the choiceof using a mix of short and long keywords. It is also possible to add white spaces to improvereadability. The pretty text encoding utilizes long keywords and an indentation style like the textexamples in the Megaco/H .248 speci cation.

25Megaco /H .248


30/84


compact - the compact text encoding uses the shortest possible keyw ords and no optional w hitespaces.

ber - ASN.1 BER.

per - ASN.1 PER. Not standard ized as a valid Megaco/H .248 encoding, but included for th ematter of completeness as its encoding is extremely compact.

erl dist - Erlang's native distribution form at. Not standard ized as a valid Megaco/H .248 encoding,but included as a reference due to its well known performance characteristics. Erlang is adynamically t yped language and a ny Erlang data structure may be serialized to t he erl dist formatby using predened built-in functions.

The actual encoded messages have been collected in one directory per encoding type, containing one le per encoded message.

H ere follows an example of a t ext message to give a f eeling of the d ifference betw een the pretty andcompact versions of text messages. First the pretty printed, well indented version with long keywords:

MEGACO/1 [124.124.124.222]Transaction = 9998 f

Context = -f

ServiceChange = ROOT f Services f

Method = Restart,ServiceChangeAddress = 55555,Profile = ResGW/1,Reason = "901 MG Cold Boot"

g

g

g

g

Then the compact text version without indentation and w ith short keyw ords:

!/1 [124.124.124.222] T=9998 f C=- f SC=ROOTf SVf MT=RS,AD=55555,PF=ResGW/1,RE="901 MG Cold Boot" g g g g

1.8.3 Setup

The measurements has been performed on a NoName PC, with an Intel P4 1800 MHz CPU, 1536 MBD D R m emory running RedHat Linux 8, kernel 2.4.22. Soft w are versions was the open source OTPR9C updated with megaco-2.1 and asn1-1.4.4.1.

1.8.4 Complete measurement result

This chapter details the effects of the possible encoding congurations for every codec. The result aboveare the fastest of these congurations for each codec. The gures presented are the average of all usedmessages.

26 Megaco/H .248


31/84


32/84


Event traces can be viewed in a generic message sequence chart tool, tha t w e have w ritten. It can eitherbe used in b atch by loading event traces from le or interactively, as w e are doing at demos and w henw e debug our ow n code. The event trace stuff can for the moment be found under megaco/utils but,w ill later be documented and released as an ow n application.

1.9.2 Measurement and transformation

We have included a simple tool for codec measurement and message transformation.

The tool is located in the example directory..

Requirement

Erlang/OTP, version R9C or lat er.

Version 2.0 or lat er of this application.

Version 1.4.3 or later of the asn1 application.

The ex libraries. Without it, the ex powered codecs cannot be used.

Results

The results from the measurement run is four excel-compatible textles:

decode time.xls - D ecoding result

encode time.xls - Encoding result

tota l time.xls - Tota l (D ecoding+ encoding) result

message size.xls - Message size

Instruction

The tool contain three things:

The transformation module

The measurement module

The b asic message le archive

Transformation module The transforma tion mod ule is used to t ransform a set of messages encodedw ith one codec into a nother other codec's.

Example : Start an erlang node, and make sure it has the path to both the latest megaco ebin-dir as wellas the dir containing th e transformation module:

% erl -pa -pa Erlang (BEAM) emulator version 5.3 [source]

Eshell V5.3 (abort with ^G)1> megaco_codec_transform:t(pretty, [compact, per, ber, erlang])....2> halt().

or to make it even easier if you as above use pretty text as base:

28 Megaco/H .248


33/84

1.9: Testing and tools

% erl -noshell -pa -pa \n

or using ber binary as base:

% erl -noshell -pa -pa \n

Now the messages in t he 'pretty' directory h as been trasnformed and stored into the ot her codec dir's.

It is possible to transform from any codec to any other.

Measurement module The measurement module is used to measure the decode and encode t hemessages in t he cod ec dirs.

Example : Start an erlang node, and make sure it has the path to both the latest megaco ebin-dir as w ellas the dir containing the measurement module:

% erl -pa -pa Erlang (BEAM) emulator version 5.3 [source]

Eshell V5.3 (abort with ^G)1> megaco_codec_meas:t([pretty, compact, per, ber, erlang])....2> halt().

or to make it even easier, assuming a measure shall be done on all the codecs (as above):

% erl -noshell -pa -pa \n -s

When run as above (this will take some time), the measurement process is done as followes:

For each codec:For each message:

Read the message from the fileDetect message versionMeasure decodeMeasure encode

Write results, encode, decode and total, to file

The measure is done by iterating over t he decod e/encode funct ion for a pprox 5 seconds per messageand counting t he num ber of decodes/encodes.

29Megaco /H .248


34/84


Message le archive This is basically a gzipped tar le of a directory t ree with th e follow ingstructure:

time_test/pretty/compact/per/

ber/erlang/

The only directories containing any les are the pretty-dir and the ber-dir. It's the same messagesencoded with different codec's. This means it is possible to choose the message basis for the(transformation and) measurement.

These les include b oth version 1 and version 2 messages.

It is of course possible to add and remove messages at will. The messages included are the ones used inour own measurements.

Notes

Binary codecs There are tw o basic way s to use the binary encodings: With pa ckage related name andtermination id transformation (the 'nat ive' encoding cong) or w ithout. This transformation convertspackage related names and termination id's to a more convenient internal form (equivalent w ith t hedecoded text message).

The transformation is done after the actual decode has been done.

Furthermore, it is possible to m ake use of a linked in d river that performs some of t he decode/encode,decode for ber and encode for per (the 'driver' encoding cong).

Therefor in the tests, binary codecs are tested with four different encoding congs to determine exaclyhow the different options effect the performance: w ith transformation and w ithout driver ([]), w ithouttransformation and w ithout driver ([native]), w ith transformation and w ith driver ([driver]) and nallyw ithout transformation a nd w ith d river ([driver,native]).

Included test messages These messages are ripped from th e call ow examples in an old version ofthe RFC.

Measurement tool directory name Be sure not no name t he directory containing the measurementbinaries start ing w ith 'm egaco-', e.g. m egaco-meas. This w ill confuse the erlang applicat ion loader(erlang applications are named, e.g. megaco-1.0.2).

30 Megaco/H .248


35/84

Megaco Reference Manual

Short Summaries

Erlang Module megaco [page 37] Ma in API of the Megaco application Erlang Module megaco codec meas [page 54] This modu le implements a simple

megaco codec measurement tool.

Erlang Module megaco codec transform [page 55] Megaco messagetransformation utility.

Erlang Module megaco encoder [page 57] Megaco encoder begaviour. Erlang Module megaco ex scanner [page 59] Interface module to the ex

scanner linked in driver.

Erlang Module megaco tcp [page 60] Interface module to TPKT transportprotoco l for M egaco/H .248.

Erlang Module megaco transport [page 63] Megaco transport begaviour. Erlang Module megaco udp [page 64] Interface module to U D P transport

protoco l for M egaco/H .248.

Erlang Module megaco user [page 67] C allback module for users of t he Megaco

application

megaco

The following functions are exported:

start() - ok | f error, Reason g [page 37] Starts t he Megaco application

stop() - ok | f error, Reason g [page 37] Stops the Megaco application

stop[page 37] Stops the Megaco application

start user(UserMid, Config) - ok | f error, Reason g [page 37] Initial conguration of a user

stop user(UserMid) - ok | f error, Reason g [page 37] D elete the con guration of a user

user info(UserMid, Item) - Value | exit(Reason)[page 38] Lookup user information

update user info(UserMid, Item, Value) - ok | f error, Reason g [page 40] Update information about a user

31Megaco /H .248


36/84


conn info(ConnHandle, Item) - Value | exit(Reason)[page 41] Lookup information ab out an act ive connection

update conn info(ConnHandle, Item, Value) - ok | f error, Reason g [page 43] U pdate information about an active connection

system info(Item) - Value | exit(Reason)[page 43] Lookup system information

connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) - f ok,ConnHandle g | f error, Reason g [page 44] Establish a virtual connection

disconnect(ConnHandle, DiscoReason) - ok | f error, ErrReason g [page 45] Tear dow n a virtu al connection

call(ConnHandle, Actions, Options) - f ProtocolVersion, UserReply g [page 45] Sends one or more transaction request(s) and w aits for th e reply

cast(ConnHandle, Actions, Options) - ok | f error, Reason g [page 46] Sends one or more transaction request(s) but does NOT w ait for a reply

encode actions(ConnHandle, Actions, Options) - f ok, BinOrBins g |f

error, Reasong

[page 46] Encode action requests for one or more transaction request(s)

token tag2string(Tag) - Result[page 47] C onvert a token tag to a string

token tag2string(Tag, EncoderMod) - Result[page 47] C onvert a token tag to a string

token tag2string(Tag, EncoderMod, Version) - Result[page 47] C onvert a token tag to a string

cancel(ConnHandle, CancelReason) - ok | f error, ErrReason g [page 47] Cancel all outstanding messages for this connection

process received message(ReceiveHandle, ControlPid, SendHandle,

BinMsg) - ok[page 47] Process a received message

receive message(ReceiveHandle, ControlPid, SendHandle, BinMsg) - ok[page 48] Process a received message

parse digit map(DigitMapBody) - f ok, ParsedDigitMap g | f error,Reason g [page 49] Parses a digit map body

eval digit map(DigitMap) - f ok, MatchResult g | f error, Reason g [page 49] C ollect digit map letters according to the digit ma p

eval digit map(DigitMap, Timers) - f ok, MatchResult g | f error,Reason g

[page 49] C ollect digit map letters according to the digit ma p report digit event(DigitMapEvalPid, Events) - ok | f error, Reason g

[page 50] Send one or more events to the event collector process

test digit event(DigitMap, Events) - f ok, Kind, Letters g | f error,Reason g [page 50] Feed digit map collector with events and return the result

test request(ConnHandle, Version, EncodingMod, EncodingConfig,Actions) - f MegaMsg, EncodeRes g [page 51] Tests if th e Actions argument is correct

32 Megaco/H .248


37/84


38/84


t([FromCodec, ToCodecs]) - ok | f error, Reason g [page 55]

t(FromCodec, ToCodecs) - ok | f error, Reason g [page 55]

tmf(FromFile, FromCodec, ToCodec) - ok | f error, Reason g [page 55]

tm(FromMsg, FromCodec, ToCodec) - binary()[page 56]

megaco encoder


Module:encode message(EncodingConfig, Version, Message) - f ok, Bin g | Error[page 57] Encode a megaco message.

Module:decode message(EncodingConfig, Version, Bin) - f ok, Message g

| Error[page 57] D ecode a m egaco message.

Module:decode mini message(EncodingConfig, Version, Bin) - f ok,Message g | Error[page 57] Perform a minimal decode of a megaco message.

megaco ex scanner


start() - f ok, Port g | f error, Reason g [page 59]

megaco tcp


start transport() - f ok, TransportRef g [page 60]

listen(TransportRef, ListenPortSpecList) - ok[page 60]

connect(TransportRef, OptionList) - f ok, Handle, ControlPid g |f error, Reason g [page 60]

close(Handle) - ok[page 60]

socket(Handle) - Socket[page 61]

send message(Handle, Message) - ok[page 61]

block(Handle) - ok[page 61]

34 Megaco/H .248


39/84


40/84


get stats(SendHandle) - f ok, SendHandleStats g | f error, Reason g [page 65]

get stats(SendHandle, Counter) - f ok, CounterStats g | f error,Reason g [page 65]

reset stats() - void()[page 66]

reset stats(SendHandle) - void()[page 66]

megaco user


handle connect(ConnHandle, ProtocolVersion) - ok | error |f error,ErrorDescr g [page 68] Invoked when a new connection is established

handle disconnect(ConnHandle, ProtocolVersion, Reason) - ok[page 68] Invoked w hen a connection is teared d ow n

handle syntax error(ReceiveHandle, ProtocolVersion, DefaultED) - reply | f reply,ED g | no reply | f no reply,ED g [page 68] Invoked when a received message had syntax errors

handle message error(ConnHandle, ProtocolVersion, ErrorDescr) - ok[page 69] Invoked when a received message just contains an error

handle trans request(ConnHandle, ProtocolVersion, ActionRequests) - pending() | reply() | ignore trans request[page 69] Invoked for each transaction request

handle trans long request(ConnHandle, ProtocolVersion, ReqData) -

reply()[page 70] Optionally invoked for a time consuming transaction request

handle trans reply(ConnHandle, ProtocolVersion, UserReply,ReplyData) - ok[page 70] Optionally invoked for a transaction reply

handle trans ack(ConnHandle, ProtocolVersion, AckStatus, AckData) - ok[page 71] Optionally invoked for a transaction acknowledgement

handle unexpected trans(ReceiveHandle, ProtocolVersion, Trans) - ok[page 72] Invoked when an unexpected message is received

handle trans request abort(ReceiveHandle, ProtocolVersion, TransNo,

Pid) -

ok[page 72] Invoked w hen an transaction request has been abort ed

36 Megaco/H .248


41/84

Megaco Reference Manual megaco

megacoErlang Module

Interface module for t he Megaco a pplication

Exports

start() - ok | f error, Reason g

Types:

Reason = term()

Starts th e Megaco application

U sers may either explicitly be registered w ith m egaco:start user/2 and/or be staticallycongured by setting the application environment variable 'users' to a list of f UserMid,Congg tuples. S ee the function m egaco:start user/2 for details.

stop() - ok | f error, Reason g stop

Types:

Reason = term()

Stops the Megaco application

start user(UserMid, Config) - ok | f error, Reason g

Types:

UserMid = megaco mid() Cong = [f user info item(), user info value() g ] Reason = term()

Initial conguration of a user

Requires the megaco application t o be started. A user is either a Media G ateway (MG )or a Media G atewa y C ontroller (MG C ). O ne Erlang node may host many users.

A user is identied by its UserMid, w hich must be a legal Megaco MID.C ong is a list of f Item, Value g tuples. See megaco:user info/2 about w hich items andvalues that are valid.

stop user(UserMid) - ok | f error, Reason g

Types:

UserMid = megaco mid() Reason = term()

37Megaco /H .248


42/84

megaco Megaco Reference Manual

D elete the conguration of a user

Requires that the user does not have any active connection.

user info(UserMid, Item) - Value | exit(Reason)

Types:

Handle = user info handle() UserMid = megaco mid() Item = user info item() Value = user info value() Reason = term()

Lookup user information

The following Item's are valid:

connections Lists all active connections for this user. Returns a list ofmegaco conn handle records.

receive handle C onstruct a megaco receive handle record from user cong

trans id C urrent t ransaction id. A positive integer or the a tom undefined serial (incase no messages has been sent).

min trans id First trans id. A positive integer, defaults to 1.

max trans id Last trans id. A positive integer or innity, defaults to innity.

request timer Wait for reply. A Timer (see explanation below, defaults to#megaco incr timer f g ).

long request timer Wait for reply after pending. A Timer (see explanation below,defaults to innity).

auto ack Automatic send transaction ack when the transaction reply has been received(see trans ack below).

This is used for three-way-handshake .A boolean, defaults to false.

trans ack Shall ack's be accumulated or not.This property is only valid if auto ack is true.If auto ack is true, then if trans ack is false, ack's will be sent imm ediatelly. Iftrans ack is true, then ack's will instead be sent to the transaction sender processfor accumulation and later sending (see trans ack maxcount ,trans req maxcount , trans req maxsize , trans ack maxcount andtrans timer ).See also transaction sender [page 13] for more info.An boolean, defaults to false.

trans ack maxcount Maximum number of accumulated ack's. At most t his many ack'sw ill be accumulated by the transaction sender (if started and con gured t oaccumulate ack's).See also transaction sender [page 13] for more info.An integer, defaults to 10.

38 Megaco/H .248


43/84


trans req Shall requests be accumulated or not.If trans req is false, then request(s) will be sent immediatelly (in it's ownmessage).If trans req is true, then request(s) will instead be sent to the transaction senderprocess for accumulation and later sending (see trans ack maxcount ,trans req maxcount , trans req maxsize , trans ack maxcount and

trans timer ).See also transaction sender [page 13] for more info.An boolean, defaults to false.

trans req maxcount M aximum number of accumulated requests. At most this manyrequests w ill be accumulated by the t ransaction sender (if started and conguredto accumulate requests).See also transaction sender [page 13] for more info.An integer, defaults to 10.

trans req maxsize Maximum size of the accumulated req uests. At most t his muchrequests w ill be accumulated by the t ransaction sender (if started and conguredto accumulate requests).See also transaction sender [page 13] for more info.

An integer, defaults to 2048.trans timer Transaction sender timeout time. H as tw o funct ions. First, if the value is

0, then transactions will not be accumulated (e.g. the transaction sender processw ill not be started). Second, if the value is greater then 0 and auto ack andtrans ack is true or if trans req is true, then transaction sender will be startedand transactions (wh ich is depending on t he values of auto ack , trans ack andtrans req ) will be accumulated, for later sending.See also transaction sender [page 13] for more info.An integer, defaults to 0.

pending timer Automatic send pending if the timer expires before a transaction replyhas b een sent. This timer is also called provisional response timer. A Timer (seeexplanation below, defaults to 30000).

sent pending limit Sent pending limit (see the MG OriginatedPendingLimit and theMG COriginatedPendingLimit of the megaco root package). This parameterspecies how many pending messages that can be sent (for a given receivedtransaction request). When the limit is exceeded, the transaction is aborted (seehandle t rans request abort [page 72]) and a n error message is sent t o th e otherside.Note that this has no effect on the actual sending of pending transactions. This iseither implicit (e.g. when receiving a re-sent transaction request for a requestwhich is beeing processed) or controlled by the pending timer, see above.A positive integer or infinity .D efaults to infinity .

recv pending limit Receive pending limit (see the MG OriginatedPendingLimit andthe M G CO riginatedPendingLimit of the megaco root package). This parameterspecies how many pending messages that can be received (for a sent transactionrequest). When the limit is exceeded, the transaction is considered lost, and anerror returned to the user (through the call-back function handle t rans r eply ).A positive integer or infinity .D efaults to infinity .

reply timer Wait for an ack. When a request is received, some info related to thereply is store internally (e.g. the binary of the reply). This info will live until eitheran ack is received or this timer expires. For instance, if the same request is received

39Megaco /H .248


44/84


again (e.g. a request with the same transaction id), the (stored) reply will be (re-)sent automatically by megaco.A Timer (see explanation below, defaults to 30000).

send mod Send callback m odule w hich export s send message/2. The funct ionSendMod:send message(SendHandle, Binary) is invoked when the bytes needs tobe transmitted to t he remote user. An atom, defaults to megaco tcp.

encoding mod Encoding callback mod ule w hich export s encode m essage/2 anddecode message/2. The function EncodingMod :encode message(EncodingCo ng,MegacoMessage) is invoked whenever a 'MegacoMessage' record needs to betranslated into an Erlang binary. The functionEncodingMod:decode message(EncodingCong, Binary) is invoked whenever anErlang binary needs to be translated into a 'MegacoMessage' record. An atom,defaults to megaco pretty text encoder.

encoding config Encoding module cong. A list, d efaults to [] .

protocol version Actual protocol version. D efault is 1.

strict version Strict version control, i.e. when a message is received, verify that theversion is that w hich w as negotiated. D efault is true.

reply data D efault reply data. Any term, defaults to the atom undened.

user mod Name of th e user callback module. See the th e reference manual formegaco user for more info.

user args List of extra arguments to the user callback functions. See the the referencemanual for megaco user for m ore info.

threaded If a received message contains several transaction requests, this optionindicates whether the requests should be handled sequencially in the same process(false ), or if each req uest should be handled by it's own process ( true i.e. aseparate process is spawned for each request).D efaults to false .

A Timer may be:

infinity Means that t he timer never will time out

Integer Waits the given number of milli seconds before it times out.

IncrTimer A megaco incr timer record. Waits a given number of milli seconds,recalculates a new t imer by multiplying a static fact or and a dding a staticincrement and starts all over again after retransmitting the message again. Amaximum number of repetition can be stated.

update user info(UserMid, Item, Value) - ok | f error, Reason g

Types:

UserMid = megaco mid() Item = user info item() Value = user info value() Reason = term()

Update information about a user

Requ ires tha t t he user is started. See megaco:user info/2 about w hich items and valuesthat are valid.

40 Megaco/H .248


45/84


conn info(ConnHandle, Item) - Value | exit(Reason)

Types:

C onnHandle = #megaco conn handle f g Item = conn info item() Value = conn info value() Reason = term()Lookup information about an act ive connection

Requires that the connection is active.

control pid The process identier of the controlling process for a conenction.

send handle O paque send handle w hose contents is internal for the send module. Maybe any term.

local mid The local mid (of the connection, i.e. the ow n mid). megaco mid() .

remote mid The remote mid (of the connection). megaco mid() .

receive handle C onstruct a megaco receive ha ndle record.

trans id Next t ransaction id. A positive integer or the atom undefined serial (onlyin case of error).Note that transaction id's are (currently) maintained on a per user basis so there isno w ay t o be sure that the value returned w ill actually be used for a transactionsent on this connection (in case a user has several connections, which is not at allunlikely).

max trans id Last trans id. A positive integer or innity, defaults to innity.

request timer Wait for reply. A Timer (see explanation below, defaults to#megaco incr timer f g .

long request timer Wait for reply after pending. A Timer (see explanation below,defaults to innity.

auto ack Automatic send transaction ack when the transaction reply has been received(see trans ack below).This is used for three-way-handshake .A boolean, defaults to false.

trans ack Shall ack's be accumulated or not.This property is only valid if auto ack is true.If auto ack is true, then if trans ack is false, ack's will be sent immediatelly. Iftrans ack is true, then ack's will instead be sent to the transaction sender processfor accumulation and later sending (see trans ack maxcount ,trans req maxcount , trans req maxsize , trans ack maxcount andtrans timer ).See also transaction sender [page 13] for more info.

An boolean, defaults to false.trans ack maxcount Maximum numb er of accumulated ack's. At most t his many ack's

w ill be accumulated by the t ransaction sender (if started and congured toaccumulate ack's).See also transaction sender [page 13] for more info.An integer, defaults to 10.

41Megaco /H .248


46/84


trans req Shall requests be accumulated or not.If trans req is false, then request(s) will be sent immediatelly (in it's ownmessage).If trans req is true, then request(s) will instead be sent to the transaction senderprocess for accumulation and later sending (see trans ack maxcount ,trans req maxcount , trans req maxsize , trans ack maxcount and

trans timer ).See also transaction sender [page 13] for more info.An boolean, defaults to false.

trans req maxcount M aximum number of accumulated requests. At most this manyrequests w ill be a ccumulated by the t ransaction sender (if started and conguredto accumulate requests).See also transaction sender [page 13] for more info.An integer, defaults to 10.

trans req maxsize Maximum size of the accumulated requests. At most t his muchrequests w ill be a ccumulated by the t ransaction sender (if started and conguredto accumulate requests).See also transaction sender [page 13] for more info.

An integer, defaults to 2048.trans timer Transaction sender timeout time. H as tw o functions. First, if t he value is

0, then transactions will not be accumulated (e.g. the transaction sender processw ill not be started). Second, if the value is greater th en 0 and auto ack andtrans ack is true or if trans req is true, then transaction sender will be startedand transactions (which is depending on the values of auto ack , trans ack andtrans req ) w ill be accumulated, f or later sending.See also transaction sender [page 13] for more info.An integer, defaults to 0.

pending timer Automatic send transaction pending if the timer expires before atransaction reply has b een sent. This timer is also ca lled provisional response timer.A Timer (see explanation below, defaults to 30000.

sent pending limit Sent pending limit (see the MG OriginatedPendingLimit and theMG COriginatedPendingLimit of the megaco root package). This parameterspecies how many pending messages that can be sent (for a given receivedtransaction request). When the limit is exceeded, the transaction is aborted (seehandle t rans request abort [page 72]) and an error message is sent to the oth erside.Note t hat this has no effect on t he actual sending of pending transactions. This iseither implicit (e.g. when receiving a re-sent transaction request for a requestwhich is beeing processed) or controlled by the pending timer, see above.A positive integer or infinity .D efaults to infinity .

recv pending limit Receive pending limit (see the MG OriginatedPendingLimit andthe MG CO riginatedPendingLimit of the m egaco root package). This parameterspecies how many pending messages that can be received (for a sent transactionrequest). When the limit is exceeded, the transaction is considered lost, and anerror returned to the user (through the call-back function handl e trans r eply ).A positive integer or infinity .D efaults to infinity .

reply timer Wait for an ack. When a request is received, some info related to thereply is store internally (e.g. the binary of the reply). This info will live until eitheran ack is received or this timer expires. For instance, if the same request is received

42 Megaco/H .248


47/84


again (e.g. a request with the same transaction id), the (stored) reply will be (re-)sent automatically by megaco.A Timer (see explanation below, defaults to 30000).

send mod Send callback m odule w hich export s send message/2. The funct ionSendMod:send message(SendHandle, Binary) is invoked when the bytes needs tobe transmitted to the remote user. An atom, defaults to megaco tcp.

encoding mod Encoding callback module w hich exports encode message/2 anddecode message/2. The function EncodingMod: encode message(EncodingCon g,MegacoMessage) is invoked whenever a 'MegacoMessage' record needs to betranslated into an Erlang binary. The functionEncodingMod:decode message(EncodingCong, Binary) is invoked whenever anErlang binary needs to be translated into a 'MegacoMessage' record. An atom,defaults to megaco pretty text encoder.

encoding config Encoding module cong. A list, defaults to [].

protocol version Actual protocol version. Current default is 1.

strict version Strict version control, i.e. when a message is received, verify that theversion is that w hich wa s negotiated. D efault is true.

reply data D efault reply data. Any term, defaults to the atom undened.

threaded If a received message contains several transaction requests, this optionindicates whether the requests should be handled sequencially in the same process(false ), or if each request should be handled by it's own process ( true i.e. aseparate process is spawned for each request).D efaults to false .

A Timer may be:

infinity M eans that th e timer never will time out

Integer Waits the given number of milli seconds before it times out.

IncrTimer A megaco incr timer record. Waits a given number of milli seconds,recalculates a new timer by m ultiplying a static factor and adding a staticincrement and starts all over again after retransmitting the message again. Amaximum numb er of repetition can be stated.

update conn info(ConnHandle, Item, Value) - ok | f error, Reason g

Types:

C onnHandle = #megaco conn handle f g Item = conn info item() Value = conn info value() Reason = term()

Update information about an active connection

Requires that the connection is activated. See megaco:conn info/2 about w hich itemsand values that are valid.

system info(Item) - Value | exit(Reason)

Types:

Item = system info item()

43Megaco /H .248


48/84


Lookup system information

The following items are valid:

text config The text encoding cong.

connections Lists all active connections. Returns a list of megaco conn handle records.

users Lists all active users. Returns a list of megaco mid()'s.n active requests Returns an integer representing the number of requests that has

originated from this Erlang node and still are active (and therefore consumessystem resources).

n active replies Returns an integer representing the number of replies that hasoriginated from this Erlang node and still are active (and therefore consumessystem resources).

n active connections Returns an integer representing the number of activeconnections.

connect(ReceiveHandle, RemoteMid, SendHandle, ControlPid) - f ok, ConnHandle g |f error, Reason g

Types:

ReceiveH andle = #megaco receive h andle f g RemoteMid = preliminary mid | megaco m id() SendHandle = term() ControlPid = pid() C onnHandle = #megaco conn handle f g Reason = term()

Establish a virtual connection

Activates a connection to a remote user. When this is done the connection can be used

to send messages (with SendMod :send m essage/2). The Co ntrolPid is the ident ier of aprocess that controls the connection. That process will be supervised and if it dies, thisw ill be detected a nd th e UserMod:ha ndle disconnect/2 callback funct ion will beinvoked. See the megaco user module for more info about the callback arguments. Theconnection ma y a lso explicitly be deact ivated b y invoking megaco:disconnect/2.

The ControlPid may be the identity of a process residing on another Erlang node. Thisis useful when you want to distribute a user over several Erlang nodes. In such a caseone of the nodes has the physical connection. When a user residing on one of the othernodes needs to send a request (w ith megaco:call/3 or megaco:cast/3), t he message willencoded on t he originating Erlang node, and then be forw arded to t he node w ith thephysical connection. When the reply arrives, it will be forwarded back to the originator.The distributed connection may explicitely be deactivated by a local call to

megaco:disconnect/2 or implicitely w hen the ph ysical connection is deactivat ed (w ithmegaco:disconnect/2, killing t he cont rolling process, ha lting t he ot her node, .. .).

The call of t his function w ill trigger the callback function U serMod:h andle connect/2 tobe invoked. See the m egaco user module for more info about the callback arguments.

A connection may be established in several ways:

provisioned MID The MG may explicitely invoke megaco:connect/4 and u se aprovisioned MID of t he MG C as the RemoteMid.

44 Megaco/H .248


49/84


upgrade preliminary MID The MG may explicitely invoke megaco:connect/4 w iththe at om 'preliminary m id' as a temporary MID of the MG C, send an intialmessage, th e Service Change Request, to the MG C and t hen w ait for an initialmessage, the Service C hange Reply. When the reply arrives, t he Megacoapplication w ill pick the MID of the MG C from th e message header andautomat ically upgrade the connection to be a normal connection. By using this

method of establishing the connection, t he callback functionUserMod:handle connect/2 to b e invoked tw ice. First w ith a C onnHandle w ith theremote mid-eld set to preliminary mid, and then w hen the connection upgrade isdone with the remote mid-eld set to the actual MID of the MG C.

automatic When the MG C receives its rst message, the Service Change Request, theMegaco application w ill autom atically establish t he connection by using the MGMID found in th e message header as remote mid.

distributed When a user (MG /MG C ) is distribut ed over several nodes, it is requiredthat the node hosting the connection already has activated the connection and th atit is in the normal stat e. The RemoteMid must be a real Megaco MID and not apreliminary mid.

An initial megaco receive handle record may be obtained w ithmegaco:user info(UserMid, receive handle)

The send handle is provided by the preferred transport module, e.g. megaco tcp,megaco udp. Read t he documentation about each transport module about t he details.

disconnect(ConnHandle, DiscoReason) - ok | f error, ErrReason g

Types:

ConnHandle = conn handle() D iscoReason = term() ErrReason = term()

Tear dow n a virtu al connection

C auses the U serMod: handle disconnect/2 callback function to be invoked. See themegaco user module for more info about the callback arguments.

call(ConnHandle, Actions, Options) - f ProtocolVersion, UserReply g

Types:

ConnHandle = conn handle() Actions = action reqs() | [action reqs()] action reqs() = binary() | [#'ActionRequest' f g ] Options = [send option()] send option() = f request timer, timer() g | f long request timer, timer() g |

f send handle, term() g | f protocol version, integer() g UserReply = user reply() | [user reply()] user reply() = success() | fa ilure() success() = f ok, [#'ActionReply' f g ] g failure() = message error() | other error() message error() = f error, error descr() g other error() = f error, term () g

45Megaco /H .248


50/84


Sends one or more transaction request(s) and waits for the reply.

When sending one transaction in a message, Actions should be action reqs()(UserReply will then be user reply() ). When sending several transactions in amessage, Actions should be [action reqs()] (UserReply w ill then be[user reply()] ). Each element of the list is part of one transaction.

For some of our codecs (not binary), it is also possible to pre-encode the actions, inwhich case Actions w ill be either a binary() or [binary()] .

The function returns when the reply arrives, when the request timer eventually timesout or when the outstanding requests are explicitly cancelled.

The default values of the send options are obtained by megaco:conn info(ConnHandle,Item). But the send options above, may explicitly be overridden.

The P rotocolVersion version is the version act ually encod ed in the reply message.

At success(), the UserReply contains a list of 'ActionReply' records possibly containingerror indications.

A message error(), indicates that the remote user has replied with an explicittransactionError.

An other error(), indicates some other error such as timeout or f user cancel,ReasonForCancel g .

cast(ConnHandle, Actions, Options) - ok | f error, Reason g

Types:

ConnHandle = conn handle() Actions = action reqs() | [action reqs()] action reqs() = binary() | [#'ActionRequest' f g ] Options = [send option()] send option() = f request timer, timer() g | f long request timer, timer() g |

f send handle, term() g | f reply data, reply data() g | f protocol version, integer() g Reason = term()

Sends one or more transaction request(s) but does NOT w ait for a reply

When sending one transaction in a message, Action should be action reqs() . Whensending several transactions in a message, Actions should be [action reqs()] . Eachelement of the list is part of one transaction.

For some of our codecs (not binary), it is also possible to pre-encode the actions, inwhich case Actions w ill be either a binary() or [binary()] .

The default values of the send options are obtained by megaco:conn info(ConnHandle,Item). But the send options above, may explicitly be overridden.

The P rotocolVersion version is the version act ually encod ed in the reply message.

The callback f unction U serMod: handle trans reply/4 is invoked w hen t he reply arrives,w hen the req uest t imer eventually times out or w hen the out standing requests areexplicitly cancelled. See the m egaco user module for more info about the callbackarguments.

G iven as U serD ata argument to UserMod:handle trans reply/4.

encode actions(ConnHandle, Actions, Options) - f ok, BinOrBins g | f error, Reason g

Types:

46 Megaco/H .248


51/84


ConnHandle = conn handle() Actions = action reqs() | [action reqs()] action reqs() = [#'ActionRequest' f g ] Options = [send option()] send option() = f request timer, timer() g | f long request timer, timer() g |

f send handle, term() g | f protocol version, integer() g BinOrBins = binary() | [binary()] Reason = term()

Encodes lists of action requests for one or more transaction request(s).

When encoding action requests for one transaction, Actions should be action reqs() .When encoding act ion req uests for several transactions, Actions should be[action reqs()] . Each element of th e list is part of one t ransaction.

token

Erlang/OTP Megaco Stack

Documents

Transcript of Erlang/OTP Megaco Stack