$Id: README,v 1.29.2.1 2003/03/28 05:25:50 bko Exp $

====================================================================
Software Name Version Number README or Module Name README 
====================================================================
Media Gateway Control Protocol (MGCP) Stack
Release 1.2.0
March 22, 2001

====================================================================
LICENSE AND COPYRIGHT 
====================================================================
The Vovida Software License, Version 1.0 
Copyright (c) 2000 Vovida Networks, Inc.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. The names "VOCAL", "Vovida Open Communication Application Library",
   and "Vovida Open Communication Application Library (VOCAL)" must
   not be used to endorse or promote products derived from this
   software without prior written permission. For written
   permission, please contact vocal@vovida.org.

4. Products derived from this software may not be called "VOCAL", nor
   may "VOCAL" appear in their name, without prior written
   permission of Vovida Networks, Inc.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
NON-INFRINGEMENT ARE DISCLAIMED.  IN NO EVENT SHALL VOVIDA
NETWORKS, INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT DAMAGES
IN EXCESS OF $1,000, NOR FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
--------------------------------------------------------------------
All third party licenses and copyright notices and other required
legends also need to be complied with as well.

====================================================================
INTRODUCTION 
====================================================================
The current version of this MGCP library is intended to implement
RFC2705 Media Gateway Control Protocol (MGCP) Version 1.0 from October 1999.

The library implements a MGCP protocol stack that can be used in either 
a Media Gateway Controller (Call Agent) application or a Media Gateway application
that needs to send and receive MGCP messages over the network.


The following have been implemented:
	All commands
	Most messages
	Memory management via reference counting
	All 0 argument package events and signals
	Enough messaging to build a call between two gateways via an agent

Included in the code is a trivial demo of a call using MGCP. The call
can be simulated using several tty interfaces (consoles or xterms) or
performed (including audio) using two Quicknet Internet Phone Jack
cards and their Linux drivers (see REQUIREMENTS, below).

The example code is not intended to be a usable gateway or call agent
implementation, but to show how to use the MGCP layer via C++.
====================================================================
NEW FEATURES AND FUNCTIONS IN THIS RELEASE 
====================================================================
As of 1.2.0 (VOCAL Asiago Release)

- code review changes, no new features or functions.

====================================================================
BUG FIXES 
====================================================================
This section lists fixed bugs:
- Removed C Api interface to the stack since they are not complete. 
- Removed msgTest.c file from examples directory as files it depends on
(C Api files) are removed.
- Added a required new line above the sdp in CRCX and MDCX response message

====================================================================
KNOWN LIMITATIONS
====================================================================
These limitations are known to exists in this release of the software:

- Refer to the TODO file in the same directory for a list of items that
still need to be implemented.

- Some access to the shared queues in MgAgent.cxx and MgcGateway.cxx may
not be synched which can cause race condition and memory corruption

- parseParameter() function should not split message
elements based on whitespace, as whitespace is optional.

- parseParameter() function uses static variable for multiple Z: lines
to accomodate NCS AUEP response. It is wrong since the variable is never reset
for the next AUEP response.

====================================================================
GETTING STARTED
====================================================================

SOFTWARE DEPENDENCIES
--------------------------------------------------------------------
This software has been successfully compiled with the following tools:

- Linux (Redhat 6.2/i386)
- For hardware support, Linux kernel 2.2.14
- gcc egcs-2.91.66 19990314 (egcs-1.1.2) and gcc-2.95.1
- GNU make 3.76.1
- bash 1.14.7

In addition, the MGCP sample applications can use the Quicknet Linux
drivers for the Internet phone jack. Version 0.3.18 is included in
this version, in the contrib/quicknet directory. Since the driver for
the Internet phone jack requires Linux 2.2.14, you must use the sample
code with that version of the kernel to take advantage of the Quicknet
cards.

In theory, the code should build (software only) under any Posix-y OS
with a recent egcs-1.0/gcc-2.9x and pthreads. We have had reports of
prior versions of the code building on Linux/PPC but with runtime
problems; we are investigating these issues.


INSTALLATION INSTRUCTIONS
--------------------------------------------------------------------
tar -zxf mgcp-x.y.z.tar.gz (where x.y.z is the release number)


COMPILE INSTRUCTIONS
--------------------------------------------------------------------
The following steps should build the code:

1. cd mgcp-x.y.z

2. make mgcp_demo


For people specifically want a NCS compliant stack, follow these instructions instead:
Building PacketCable NCS compliant code (stack and example demos):

1. cd mgcp-x.y.z

2. Open Makefiles in directories mgcp/libmgcp, mgcp/lowlevel, mgcp/examples/agent and 
   mgcp/examples/gateway, and remove the "#" in front of the 
   "DEFINES += NCS_PROFILE" in each of them.

3. cd to mgcp-x.y.z (where x.y.z is the release number) and do "make mgcp_demo"


USING THE SOFTWARE
--------------------------------------------------------------------
Developer documentation, including information about API's (application programming interfaces), is 

not currently available.


RUNNING DEMO TEST APPLICATION
--------------------------------------------------------------------

If this make compiles correctly, sample applications should be built
in the release/bin.i686 directory.  The directory listing should look
like this:

	agent
	gateway
	msgTest

The main sample applications are the agent and the gateway.  These
applications form a simple MGCP system which can do two way "hotline"
(no dialing) calling, either locally (via the loopback interface) or
over a TCP/IP network.

By default, the system is configured to use the loopback interface (so
all three applications will run on a single machine), using the "null"
hardware interface.  


Using the Null Hardware Interface on a Single Machine


The "null" hardware interface is a simulation of an MGCP gateway the
tty.  No audio is provided.

You will need to start the two gateway applications first, in two
separate terminal windows.

In window 1:

	./gateway null localhost 5050


In window 2:

	./gateway null localhost 5051

Now, you can start the agent, in a third window.

In window 3:

	./agent

At this point, in window 1, you should see:

	State changed to: stateUninitialized
	handle agent command
	State changed to: stateIdle

in window 2:

	State changed to: stateUninitialized
	handle agent command
	State changed to: stateIdle

in window 3:

	Usage: agent gatewayHostName1 gatewayHostName2
	Defaulting both gateways to localhost


Simulating a call:

To simulate going off hook, press "a" .
To simulate going on hook, press "z" . 

To simulate pressing digits on a set when offhook, press 0-9 .

To make a call from gateway 1 to gateway 2:


1. press "a" to go off hook on window 1.  

2.  You should see a message "Start ringing" on window 2.  press "a"
in window 2 to go offhook and answer the call.

3.  At this point, you should see the "Establishing audio" message in
both windows.  You're having a conversation (well, not really).

4.  At this point, you can press digits in either window 1 or 2 of the
call.  The other side should indicate that digits are being pressed.

5.  To hang up, press z in either window.

6.  The "stopping audio" message should appear.  Hang up in the other
window by pressing "z".

7.  At this point, you are ready to go back to step 1, and make
another call.


Multiple machines

To use the null interface with multiple machines, change the arguments
passed to the gateways and the agent.  Let's say that you have two
machines to simulate the gateways, named gateway1 and gateway2, and
one machine to simulate the agent, named call-agent.  Then, invoke
like so:

	./gateway null call-agent 5050
	./gateway null call-agent 5051
	./agent gateway1 gateway2

Note that 5050 corresponds to the first argument passed to the agent,
and 5051 corresponds to the second argument.

Again, you can use a, z, and digits to go off hook, on hook, and
simulate DTMF digits.



Using the quicknet hardware

To use the Quicknet hardware, you must install the Quicknet drivers
under Linux. A complete copy of the quicknet drivers v 0.1.27 is
included in this package, in contrib/quicknet/ixj-0.1.27. The most
recent version of Quicknet's drivers are available from their web
page, at

	http://www.quicknet.net/

To use the quicknet hardware instead of the null hardware, supply the
argument "tpjack" as the first argument to the gateways.  Note that
gatewayCommon1 and gatewayCommon2 both expect to use /dev/ixj0 , so
using both on a single machine is not recommended without recompiling.

	./gateway tpjack call-agent 5050
	./gateway tpjack call-agent 5051
	./agent gateway1 gateway2

In this case, going off hook / on hook on a set hooked up to the
tpjack card will go offhook and onhook, and two-way speech between the
phones should work.  When the call is established, you should also be
able to press DTMF digits on either set and the far end set should be
able to detect the digit presses.


====================================================================
SOURCE CODE INFORMATION
====================================================================
The stack is implemented as a two-level stack -- the upper layer is
the externally callable API, while the lowlevel code builds, parses,
and encodes the messages.

The MGCP stack has a class for each MGCP command (e.g. Request
Notification, Delete Connection, etc.).  The message sender creates an
object, and calls methods of that object to set the various possible
parameters.

When the other side receives the message, an object is generated and
passed to the receiving process.  The process can use methods to
examine the contents of the message.

The stack has API support for both blocking and non-blocking sends --
the blocking sends block until the other side successfully responds or
until a time out has occured.

The MGCP stack code is in the mgcp directory. More information is
available in libmgcp and lowlevelmgcp.

Generating MGCP Stack Documentation using Doc++
----------------------------------------------
You can use Doc++ to generate API documentation. 
Doc++ generates an alphabetical and hierarchical index of 
classes, functions, and variables. To use Doc++: 

1. Download Doc++ from http://www.zib.de/Visual/software/doc++/
2. Untar the file.
3. Locate the doc++ and docify files. These files should be in
   the /bin directory.
4. Copy the doc++ and docify files to directory where the source
   code is located.
5. Type: make doc 
6. Doc++ generated documentation will be saved in a html directory.
7. Select index.html from the html directory.

====================================================================
DIRECTORY STRUCTURE 
====================================================================
This directory contains the following subdirectories or files:
directory name: description of what is in the directory

build: build structure
contrib: 
contrib/andreasen:
contrib/perl: run perl scripts in tools directory. e.g. buildTokenRecognizer
contrib/quicknet: run with demo gateway application using quicknet card in mgcp/examples/gateway directory
contrib/rsvp:
mgcp: MGCP stack library code and demo applications
mgcp/examples: contains demo agent and gateway applications
mgcp/examples/agent: demo agent application
mgcp/examples/asyncAgent: contains sample code for using asyn APIs in the stack
mgcp/examples/gateway: demo gateway application
mgcp/examples/testcases: some test code for various APIs in the stack
mgcp/examples/testcases/sendudp: a perl script for sending RSIP to a CA
mgcp/libmgcp: contains upper level APIs in the stack
mgcp/libmgcp/html: generated by "make doc" command, contains class/hierarchy info
mgcp/lowlevel: low level stack code for parsing and encoding MGCP messages
mgcp/lowlevel/html: generated by "make doc" command, contains class/hierarchy info
rtp: RTP stack code used by MGCP demo gateway application
rtp/codec:
rtp/html:
rtp/test:
rtp/test/obsolete:
sdp: SDP stack code used in MGCP stack
sdp/html:
tools: tools needed by build

====================================================================
CONTRIBUTORS 
====================================================================  
This software consists of voluntary contributions made by Vovida
Networks, Inc., Cisco Systems, Inc., and many individuals.


====================================================================
CONTACT INFORMATION AND WEBSITE
====================================================================
We welcome your feedback, suggestions and contributions. Contact us
via email if you have questions, feedback, code submissions, 
and bug reports.

For general inquiries - info@vovida.org

We have mailing lists for the VOCAL applications and proctocol stacks: 
VOCAL - vocal@vovida.org
COPS - cops@vovida.org
MGCP - mgcp@vovida.org
RADIUS - radius@vovida.org
RTP - rtp@vovida.org
SIP - sip@vovida.org
TRIP - trip@vovida.org
You can subscribe to the mailing lists on www.vovida.org. 

You can submit bug, patches, software contributions, and feature 
requests using Bugzilla.  Access Bugzilla from www.vovida.org. 
====================================================================
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.29.2.1 2003/03/28 05:25:50 bko Exp $
