Copyright (C) 2004-2006 by Objective Systems, Inc.

Objective Open H.323 README

Introduction
============

Thank you for downloading the Objective Open H.323 software. This 
package contains a simple H.323 stack developed in C.  The ASN.1 
messaging code was developed using the Objective Systems ASN1C 
compiler to implement the core H.323 specifications (H.225, H.235, 
and H.245).  Additional code was then developed which makes use of 
the compiler generated code for presenting a comparatively high level 
stack API.

The media part, which includes RTP and audio support, is implemented
as a sample library. The media library uses G.711 code made available 
by Sun Microsystems to the open source community. Please refer to their 
license for more details.


Features
========

Features supported in this package include the following:

* H.225/Q.931 - the following message types are supported (including 
  support for FastStart and H.245 tunneling): 
  - Setup 
  - Connect
  - Call Proceeding
  - Alerting 
  - Facility
  - ReleaseComplete

* H.225/RAS - the following message types are supported
  - GateKeeperRequest / Response
  - RegistrationRequest / Response
  - AdmissionRequest / Response
  - DisengageRequest / Response

* H.245 - the following message types are supported
  - MasterSlaveDetermination
  - MasterSlaveDeterminationAck
  - MasterSlaveDeterminationReject
  - MasterSlaveDeterminationRelease
  - TerminalCapabilitySet
  - TerminalCapabilitySetReject
  - TerminalCapabilitySetRelease
  - TerminalCapabilitySetAck
  - OpenLogicalChannel
  - OpenLogicalChannelAck
  - OpenLogicalChannelReject
  - CloseLogicalChannel
  - CloseLogicalChannelAck
  - RequestChannelClose
  - RequestChannelCloseAck
  - RequestChannelCloseReject
  - RequestChannelCloseRelease

* A sample media library is provided with the test programs that can 
   send and receive RTP data. It can play the received audio onto 
   speakers and can collect audio from a microphone for transmission 
   as an RTP stream. This library also supports transmitting audio files
   over the RTP channel. The Windows version supports 16 bit, 8000 samples 
   per second wave file whereas the Linux version supports raw 16 bit audio
   data files.


Getting Started
===============

This section describes how to build the complete package on Linux and 
Windows systems respectively.
   
Building on Linux:
-----------------  
1. Change directory to the package root directory.

        cd ooh323c-0.8.2

   (note: the version number may be different depending on what distribution 
    you are working with).

2. Generate the makefiles:

        ./configure --prefix=<install-dir>

   The configure script will generate the requred makefiles. The 
   <install-dir> is where the libraries will be installed. By default 
   the libraries are installed in /usr/local/lib. Static and shared 
   versions of all of the different object libraries are installed.

   Note that if wish to use the libraries in your home directory, it is 
   necessary to set <install-dir> to the location in which the package 
   was installed prior to running the installation step (step 4).  For 
   example: 

        ./configure --prefix=$HOME/ooh323c-0.8.2

3. Execute the generated makefile:

        make

   This will build all the libraries and sample applications.  By default, 
   an optimized version is built.  This can also be done explciitly by 
   executing the following make command:
   
        make opt

   If you wish to build a debug version, execute the following command:

        make debug

4. To install the libraries, execute the following command:

        make install

   Note that it is necessary to do this even if the libraries are to be 
   used in your home directory.  If this is the case, configure must have 
   been run using --prefix as described in step 2.


Building on Windows:
-------------------

The package includes Visual Studio 6 based workspace and project files.

1. Open the package root directory ooh323c-0.8.2 (or whatever version 
   you have).
   
2. Open the ooh323c.dsw workspace which includes all the projects within
   the package.

3. You can now do a batch build to build the complete package.

4. To build individual projects, dependencies are as follows:

      oostk.dsp - none
      oomedia.dsp - none
      simple.dsp - oostk.dsp, oomedia.dsp
      ooPlayer.dsp - oostk.dsp, oomedia.dsp
      ooReceiver.dsp - oostk.dsp, oomedia.dsp
      oochansetup.dsp - oostk.dsp

5. After a successful build, the libraries will be installed in 
   ooh323c-0.8.2\lib\release and ooh323c-0.8.2\lib\debug directories.


Sample Programs
===============

To run the sample programs, 
	On Linux, make sure the path to the media shared object library 
	(liboomedia.so) is set in LD_LIBRARY_PATH:

        LD_LIBRARY_PATH=<install-dir>/lib
        export LD_LIBRARY_PATH

	On Windows, make sure the path to the media plug-in library DLL 
	(oomedia.dll) is in your PATH.  The DLL is located in the 
	ooh323c-0.8.2\lib\release and ooh323c-0.8.2\lib\debug directories. 

The sample programs are locates in the 'tests' subdirectory.  The following 
programs are available:

*  receiver - an audio receiver program that will listen for incoming 
   requests and then play audio as it is received.

*  player - an audio player program that will play a sample audio file.

*  simple - an H.323 endpoint sample program.  This is a sample H.323 
   VoIP phone application which opens g711ulaw64k channels and transmits 
   and receives voice. It has been tested successfully against ohPhone, 
   a widely used open source H.323 phone application and NetMeeting.

*  chansetup - This is a sample program developed for testing multiple calls.
   This program allows stack testing by placing multiple calls. The number of
   calls, duration of each call and interval between successive calls are 
   configurable.  

The receiver and player program must be run in parallel as follows: 

1. Run receiver first to listen for incoming connections: 

        cd tests/receiver
        ./ooReceiver [--use-ip <ip>] [--use-port <port>]

   where, [--use-ip <ip>] and [--use-port <port>] options are used to specify
   local ip address and port number. By deafault, receiver application tries
   to determine ip address on it's own and uses standard H.323 port 1720.

   A log file will be created in the tests/receiver directory 
   (ooReceiver.log). Also, the log file for the media plugin will
   be created in the same directory (media.log).

2. Run the player:
   Note: Player supports wave file format on windows and raw audio format on 
   linux.

        cd ../player
        ./ooPlayer --audio-file space.raw [--use-ip <ip>] (linux)
        ./ooPlayer --audio-file states.wav [--use-ip <ip>] (win32)
        

   where, --audio-file is used to specify the audio file to be played.
   [--use-ip <ip>] is used to specify local ip address. By deafault, player 
   application tries to determine ip address on it's own.space.raw

   A log file will be created in the tests/player directory 
   (ooPlayer.log). Also, a log file for the media plug-in will be
   created in the same directory (media.log).


To run the H.323 endpoint sample application:

1. Set working directory to the simple test directory:

        cd tests/simple

2. To see the usage information including various options:
        ./simple OR ./simple --help

3. To make a call:

        ./simple [options]  <remote>

   where,
 <remote>    -  is the dotted representation of the destinations IP address. In
                case of gatekeeper, aliases can also be used.
      
4. To receive a call:

        ./simple [options] --listen

   You will find simple.log and media.log in the current directory.
      

5. For testing against ohphone, make sure the -n option for ohphone 
   is enabled. If you want to use a gatekeeper, you will have to enable
   the gatekeeper mode in simple.c

To run the stack test application chansetup

1. Two instances of this program have to be run. Can be run on same machine or
   different machines.

2. First change to chansetup directory.

        cd tests/chansetup

2. For running listener instance, 

        ./h323peer [--use-ip ip] [--use-port port]

   where local ip address and port can be specified for listening to incoming 
   calls. By default, application determines ip address and uses default H323
   port number 1720.

3. For running calling instance
 
        ./h323peer [--use-ip ip] -n <number of calls> -duration <call duration>
                   -interval <inetrval between successive calls> destination
      
   where all times are in seconds. Interval of 0 means next call will be placed
   after current call finishes. "destination" is the dotted ip address of the
   endpoint running listener instance.


Reporting Problems:
==================

Report problems you encounter by sending E-mail to 
ooh323c-devel@lists.sourceforge.net. 

If you have any further questions or comments on what you would like to
see in the product or what is difficult to use or understand, please 
communicate them to us. Your feedback is important to us. Please let us
know how it works out for you - either good or bad. 

