readme

一个Megaco实现源代码

The Megaco Session application enables access of the Megaco/H.248
protocol stack in Erlang/OTP from foreign languages.

Prerequisites
-------------

Megaco Session is a component of the Erlang/OTP system and in order to
fully understand how this application works, the following
prerequisites is required:

    - the basics of the Megaco/H.248 protocol
    
    - the basics of the Interface Definition Language (IDL)
    
    - the basics of the Abstract Syntax Notation One (ASN.1)
    
    - familiarity with the Erlang/OTP system in general and
      the Megaco application plus erl_interface in particular

Architecture
------------

The Megaco application, which provides the Megaco/H.248 protocol
stack, is implemented in Erlang and is intended to be used from Erlang
applications. Megaco Session has adopted its interfaces and
terminology as far as possible. See the documentation of the Megaco
for the details about its functionality and behaviours.

The main interfaces of the Megaco Session application is specified in
IDL. OMG's IDL is normally used to define interfaces in a CORBA
environment, but the IDL compiler tool (IC) in Erlang/OTP is also able
to generate encoders/decoders which follows OMG's standardized type
mapping but instead of using IIOP as transport protocol it uses a much
more efficient alternative. This efficient transport protocol is the
same protocol as the Erlang system uses for inter node communication.

In the Erlang distribution protocol, asynchronous messages are sent
between threads (Erlang processes) where each one is identified with a
process identfier (pid). In an ordinary Erlang node, process
identifiers are generated automaticially by the runtime system when a
new process is spawned. But on a C or Java node, using the Erlang
distribution protocol, the process identifiers are created explicitly
by the user and may correspond to a thread but it does not have to do
that. On each of the hosts where the protocol stack is intended to be
running, a distributed Erlang node must be started. On that node a
MegacoSessionFactory process is running under some registered name.
This requires both the megaco and megaco session applications to be
started.

In the IDL specifications you will find interface definitions for:

    - MegacoSession, corresponds to the megaco module in the
      megaco application.

    - MegacoSessionUser, corresponds to the megaco_user callback
      module and needs to be implemented by you.

    - MegacoSessionTcp, corresponds to the megaco_tcp transport module

    - MegacoSessionUdp, corresponds to the megaco_udp transport module

    - MegacoSessionFactory, handles start and stop of MegacoSessions.

The main C/Java interface is derived by applying OMG's type mapping
rules on our IDL specs. Do also read the erl_interface documentation
about how to connect to an Erlang node. 

At startup a MegacoSessionUser instructs a MegacoSessionFactory on the
Erlang node to start a new MegacoSession process. The MegacoSession is
like a man in the middle and acts between the Megaco protocol stack
and its user (MegacoSessionUser). When the MegacoSessionUser needs to
reconfigure the protocol stack and/or send a Megaco message, this is
done via its MegacoSession. The interaction model is peer-to-peer and
a MegacoSession may also send asynchronous messages to its
MegacoSessionUser. This is typically initiated by a incoming message
over the Megaco protocol from the other part (MG/MGC).

Megaco message
--------------

The internal form for Megaco messages in the megaco application is
very similar to the ASN.1 spec for the Megaco/H.248 protocol as
defined in RFC 3015. When defining the MegacoMessage in IDL spec, the
same approach has bee choosen. As far as possible the following
mapping rules has been applied on the ASN.1 spec:

SEQUENCE      -> struct
SEQUENCE OF   -> sequence
NULL OPTIONAL -> boolean
BOOLEAN       -> boolean
OPTIONAL      -> sequence<Type, 1> sequence with zero or one elements
OCTET STRING  -> sequence<Type, MaxLen>
INTEGER       -> unsigned short when 0..65535
INTEGER       -> unsigned long  when 0..4294967295
IA5String     -> string
BIT STRING    -> sequence<EnumType>

The release
-----------
The release is basically a source release. With some exceptions.
- All IDL-files has been compiled 
  (i.g. C- and erlang-source genereted which are included in the delivery)
- All erlang source (including the generated files) has been compiled 
  (since beam-files are platform independant this is OK).
These exceptions will make it possible to build the application even 
on platforms for which we have no official open source release (e.g. 
windows).

The release consists of the application itself, a simple MG example and 
a simple MGC example. Note that these examples are indended to 
illustrate how to use the megaco_session to interface with the megaco
application. Not how to write good and solid C-programs...


Building
--------
Building the application is very simple:

- Enter the top directory of the application.

- Run configure: make conf

- Compile it all with or without debug compilation:

  make DEBUG=true

  or

  make

Now you are ready to use the application and the supplied example(s).


Using the example
-----------------
With the release we provide a simple MGC example. To use this example,
do the following (assuming megaco_session has been built):

- Open a terminal window and go to the example directory:

  cd <megaco_session_path>/examples/simple_MGC

- Start the megaco_session erlang application:

  ./megaco_session

- Open another terminal window and go to the example directory:

  cd <megaco_session_path>/examples/simple_MGC

- Start the example MGC program:

  ./mgc -v


With this release we also provide a simple MG example. To use this example,
do the following (assuming megaco_session has been built):

- Open a terminal window and go to the example directory:

  cd <megaco_session_path>/examples/simple_MG

- Start the megaco_session erlang application:

  ./megaco_session

- Open another terminal window and go to the example directory:

  cd <megaco_session_path>/examples/simple_MG

- Start the example MG program:

  ./mg -v -mhost <mgc-host-name> -uname <name> -t udp -e text




Use cases
---------

Starting MGC
- - - - - - -

        foreign MG      erlang          c
          |               |             |
          |               | <---------- | startSession("own pid")
          |               |             |
          |               | ----------> | startSessionResponse("pid")
          |               |             |
          |               | <---------- | startUser
          |               |             |
          |               | ----------> | startUserResponse
          |               |             |
          |               | <---------- | (udp) open (or init other transport)
          |               |             |
          |               | ----------> | (udp) openResponse
          |  Service Ch.  |             |
          |    (req)      |             |
          | =============>|             | 
          |               |             |
          |               | ----------> | handleConnect
          |               |             |
          |               | <---------- | handleConnectResponse
          |               |             |
          .               .             .
          .   Receive message scenario  .
          .               .             .
 

Receive message
- - - - - - - - 

        foreign         erlang          c
          |      req      |             |
          | ============> |             |
          |               |     req     |
          |               | ----------> | handleTransRequest
          |               |   pending   |
          |               | <- - - - -  | handleTransRequestPending
          |    pending    |             |
          | <= = = = = =  |             |
          |               |    reply    |
          |               | <---------- | handleTransRequestResponse
          |     reply     |             |
          | <============ |             |
          |      ack      |             |
          |  = = = = = => |             |
          |               |     ack     |
          |               |  - - - - -> | handleTransAck
          |               |             |

Starting MG
- - - - - - -

        foreign MGC     erlang          c
          |               |             |
          |               | <---------- | startSession("own pid")
          |               |             |
          |               | ----------> | startSessionResponse("pid")
          |               |             |
          |               | <---------- | startUser
          |               |             |
          |               | ----------> | startUserResponse
          |               |             |
          |               | <---------- | (udp) open (or init other transport)
          |               |             |
          |               | ----------> | (udp) openResponse
          |               |             |
          |               | <---------- | connect
          |               |             |
          |               | ----------> | handleConnect
          |               |             |
          |               | <---------- | handleConnectResponse
          |               |             |
          |               | ----------> | connectResponse
          |               |             |
          .               .             .
          .   Send message scenario     . Service Change Req
          .               .             .
 
Sending message
- - - - - - - - 

        foreign         erlang          c
          |               |     req     |
          |               | <---------- | sendTransRequest
          |      req      |             |
          | <============ |             |
          |    pending    |             |
          |  = = = = = => |             |
          |     reply     |             |
          | ============> |             |
          |               |    reply    |
          |               | ----------> | handleTransReply
          |               |             |