OpenH323 Library
================
The OpenH323 project aims to create a full featured, interoperable, Open
Source implementation of the ITU H.323 teleconferencing protocol that can be
used by personal developers and commercial users without charge.
OpenH323 development is coordinated by an Australian company, Equivalence Pty
Ltd (http://www.equival.com), but is open to any interested party. Commercial
and private use of the OpenH323 code, including use in commercial products
and resale, is enouraged through use of the MPL (Mozilla Public license).
For more details see http://www.openh323.org
You can subscribe to the mailing list at http://www.openh323.org/mailman/listinfo
Frequently asked questions are answered at http://www.openh323.org/faq.html
Building the OpenH323 Code
==========================
This page describes how to compile the OpenH323 code release. Note these
instructions will always refer to the latest snapshot available on the
download page.
The OpenH323 source will have been compiled and tested under Linux x86, and
Windows NT. If it does not compile for you then the problem is likely to be a
setup/configuration problem with your system and not a problem with the
source code itself.
The libraries and applications should also compile on Windows 95/98, BeOS
(thanks Yuri!), Linux PPC, FreeBSD x86, OpenBSD x86 (thanks Roger!) and
Solaris Sparc & x86. They are not automatically compiled on every release
however so there could be problems, but the chances are that there aren't.
Note also that not all of these platforms may have ports of the sound
interface.
We are also happy to port it to other Unix flavours providing people out
there can provide an account and a fair bit of disk space!
These instructions should contain all of the steps need. If you have a problem,
please double check that you have performed ALL of the steps below,
particularly setting the include file paths under MSVC. Some of the more
common errors are described below.
If you get a lot of compile or link errors, then the chances are that you
have missed something in the list. If you are positive that something is
wrong and you have followed the instructions, then send an e-mail to the
mailing list, and we'll answer it for everyone to see. Bear in mind that the
first question asked will be "did you follow the instructions".
Windows
-------
1. Download the pwlib_1.xx.zip and openh323_1.x.zip files from the OpenH323
download page.
2. Extract the pwlib_1.xx.zip file somewhere eg c:\, making sure the
directory structure is preserved.
3. Start MSVC (v5 or v6). If you have another compiler you are on your own!
Go into the Tools menu, Options item, Directories tab and add to the
beginning of the Include files path (note the order is important!):
C:\PWLib\Include\PwLib\MSWIN
C:\PWLib\Include\PtLib\MSOS
C:\PWLib\Include
C:\OpenH323\Include
and add to the Lib Files path and the Executable Files path the following:
C:\PWLib\Lib
C:\OpenH323\Lib
Also make sure these directories are in your PATH environment variable.
3a. If you have OpenSSL installed and compiled on your system then you
can define the following environment variables to get SSL support:
OPENSSLFLAG=1
OPENSSLDIR=c:\some\where\openssl
OPENSSLLIBS=ssleay32.lib libeay32.lib
If you have NOT included these variables then you will get a warning
during the build. You can safely ignore this warning.
3b. If you have EXPAT installed and compiled on your system then you
can define the following environment variables to get XML support:
EXPATFLAG=1
EXPATDIR=c:\some\where\expat
EXPATLIBS=expat.lib
If you have NOT included these variables then you will get a warning
during the build. You can safely ignore this warning.
3c. If you have the Voice Age G.729 library installed and compiled on your
system then you can define the following environment variables to get
G.729 support:
VAG729FLAG=1
VAG729DIR=c:\some\where\
VAG729LIB=va_g729a.lib
If you have NOT included these variables then you will get a warning
during the build. You can safely ignore this warning.
4. Note you will need bison and flex to compile the system. You can get a
copy from the openh323 site, follow the instructions included in that
package for setting it up and put the executables (Note they should be
called bison.exe and flex.exe) somewhere in your path.
5. Open the pwlib.dsw file in the pwlib top directory.
6. Use the Batch Build command and build the "ASNParser - Win32 Release",
"pwtest - Win32 Release" and "pwtest - Win32 Debug" targets. Make sure
all other targets are not checked.
7. Extract the contents of the openh323_1.x.zip file somewhere.
8. Use the OpenH323.dsw file to build the sample application code.
9. Run the program, and you are on your own!
Unix
----
1. Download the pwlib_min_1.xx.tar.gz and openh323_1.xx.tar.gz files from
the OpenH323 download page.
2. Extract the pwlib_min_1.xx.tar.gz somewhere, preferably in your home
directory, eg:
cd
tar -xzvf pwlib_min_1.14.tar.gz
This should result in a ./pwlib directory tree.
3. If you have not installed PWLib in your home directory (~/pwlib) then you
will have to define the environment variable PWLIBDIR to point to the
correct directory.
Also make sure you have added the $PWLIBDIR/lib directory to your
LD_LIBRARY_PATH environment variable if you intend to use shared
libraries (the default under Linux).
There are examples for sh/bash and csh/tcsh below.
4. Build the debug and release versions of the PWLib library as follows:
cd $PWLIBDIR
make both
This may take some time. Note, you will need GNU make (>=3.75),
bison(>=1.25) and flex (>=2.5.4) for this to compile, most Unix systems
have these packages.
WARNING: there is a bug in some of the bison.simple files, see below for
details.
If you are getting huge numbers of errors from make then you are probably
not using the GNU make. FreeBSD and OpenBSD users must install gmake and
use gmake instead of make in these instructions. If the errors are during
the compile, then it is likely your platform is not supported, or you
have incorrectly set the OSTYPE and MACHTYPE variables. There will be a
large warning printed about this, don't ignore it!
5. Extract the contents of the openh323_1.x.tar.gz file somewhere, eg:
cd
tar -xzvf openh323_1.1alpha1.tar.gz
6. If you have not installed OpenH323 in your home directory (~/openh323)
then you will have to define the environment variable OPENH323DIR to
point to the correct directory.
Also make sure you have added the $OPENH323DIR/lib directory to your
LD_LIBRARY_PATH environment variable if you intend to use shared libraries
(the default under Linux).
There are examples for sh/bash and csh/tcsh below.
7. Build the H323 bootstrap code. This will automatically build the ASN
compiler (in the $PWLIBDIR/tools/asnparser directory), though this should
have already been built previously. Enter:
cd $(OPENH323DIR)
make opt
This may take some time, especially with the h245_*.cxx and h225.cxx
files. You may also need to add more swap space - 64M of real memory and
64M of swap might just be enough, if your machine does nothing else! Some
people have reported needing as much as 128M of swap - if your compiler
bombs out with a "virtual memory exhausted" error compiling h245_*.cxx
and h225.cxx, then increase your swap space.
8. The result should be an executable called simph323, which will be located
in a directory dependent on the platform, eg sample/simple/obj_linux_x86_d. To
run it, use the following command:
./sample/simple/obj_linux_x86_r/simph323
and you should get the usage help text.
9. Now you're on your own!
Common errors
-------------
Here are common errors you might encounter for both Windows and Unix builds.
An error like:
"Makefile", line 175: Missing dependency operator
"Makefile", line 177: Need an operator
"Makefile", line 179: Missing dependency operator
"Makefile", line 181: Need an operator
"Makefile", line 183: Missing dependency operator
"Makefile", line 185: Need an operator
Indicates you are using BSD Unix's Make command. You need to use
gmake (GNU Make).
Thinking there are missing files.
A number of files, eg h235.h, h225.h etc, are generated files that are
created during the build process. If they are missing then something
went wrong with the creation of the asnparser or your installation of
flex/bison.
An error like:
/home/newbie/pwlib/tools/asnparser/obj_linux_x86_r/asnparser: error in loading
shared libraries: libpt_linux_x86_r.so.1: cannot open shared object file: No
such file or directory
Indicates you have not set the LD_LIBRARY_PATH environment variable.
There are examples for sh/bash and csh/tcsh.
An error like:
Linking...
LINK : fatal error LNK1181: cannot open input file "ptlib.lib"
Error executing link.exe.
Indicates you have not set the paths in MSVC directories.
An error like:
Performing Bison Step
c:\tools\share\bison.simple: No such file or directory
C:\PWLIB\TOOLS\ASNPAR~1\BISON.EXE: Cannot move asn_grammar_tab.c - No such file or directory
Cannot move asn_grammar_tab.h - No such file or directory
Indicates you have not installed bison correctly. In particular the
bison.simple file must be available to bison. Check the bison
documentation for details on this.
Attempting to compile GUI systems under Unix.
There are a number of partial implementations of the GUI code in the
$PWLIBDIR/src/pwlib directory tree. These are not required to get the
OhPhone application compiled. If you get those systems from the CVS
then you are basically on your own. Do not ask for support unless you
intend to help with the implementation!
See the FAQ at http://www.openh323.org/~openh323/fom.cgi for more.
Example environment for sh/bash
-------------------------------
PWLIBDIR=$HOME/pwlib
export PWLIBDIR
OPENH323DIR=$HOME/openh323
export OPENH323DIR
LD_LIBRARY_PATH=$PWLIBDIR/lib:$OPENH323DIR/lib
export LD_LIBRARY_PATH
Example environment for csh/tcsh:
setenv PWLIBDIR $HOME/pwlib
setenv OPENH323DIR $HOME/openh323
setenv LD_LIBRARY_PATH $PWLIBDIR/lib:$OPENH323DIR/lib
Bison problem under Unix
------------------------
The bison.simple file on many releases will not compile with the options used
by the PWLib getdate.y grammar. The options are required to make the date
parser thread safe so it is necessary to edit the bison.simple file to fix
the problem.
The file is usually at /usr/lib/bison.simple but in the tradition of unix
could actually be anywhere. We leave it up to you to find it.
The code:
/* Prevent warning if -Wstrict-prototypes. */
#ifdef __GNUC__
int yyparse (void);
#endif
should be changed to
/* Prevent warning if -Wstrict-prototypes. */
#ifdef __GNUC__
#ifndef YYPARSE_PARAM
int yyparse (void);
#endif
#endif
To prevent the incorrect function prototype from being defined. The getdate.y
should then produce a getdate.tab.c file that will actually compile.
Voice Age G.729 Codec
---------------------
For the Windows system it is possible to also have a G.729 codec
for non-commercial use by adding the Voice Age G.729A library to the system.
To do this:
1. Get the Voice Age G.729 library from http://www.voiceage.com/g729/
2. In the Settings property window of your project, go to the C/C++ tab and
add VOICE_AGE_G729A in the "preprocessor definitions" text box.
3. In the Settings property window of g729codec.cxx, go to the General tab
and uncheck "exclude from build"
4. Recompile your project.
Licensing
---------
The bulk of this library is licensed under the MPL (Mozilla Public License)
version 1.0. In simple terms this license allows you to use the library for
any purpose, commercial or otherwise, provided the library is kept in tact
as a separate entity and any changes made to the library are made publicly
available under the same (MPL) license. It is important to realise that that
refers to changes to the library and not your application that is merely
linked to the library.
Note that due to a restriction in the GPL, any application you write that
uses anything another than GPL, eg our library with MPL, is technically in
breach of the GPL license. However, it should be noted that MPL does not
care about the license of the final application, and as only the author of
the GPL application is in breach of his own license and is unlikely to sue
themselves for that breach, in practice there is no problem with a GPL
application using an MPL or any other commercial library.
Portions of this library are derived from TOAST, using the copyright:
Copyright 1992, 1993, 1994 by Jutta Degener and Carsten Bormann,
Technische Universitaet Berlin
Any use of this software is permitted provided that this notice is not
removed and that neither the authors nor the Technische Universitaet Berlin
are deemed to have made any representations as to the suitability of this
software for any purpose nor are held responsible for any defects of
this software. THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
As a matter of courtesy, the authors request to be informed about uses
this software has found, about bugs in this software, and about any
improvements that may be of general interest.
Portions of this library is derived from vic, http://www-nrg.ee.lbl.gov/vic/
Their copyright notice is below.
* Copyright (c) 1993-1995 The Regents of the University of California.
* 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. All advertising materials mentioning features or use of this software
* must display the following acknowledgement:
* This product includes software developed by the Network Research
* Group at Lawrence Berkeley National Laboratory.
* 4. Neither the name of the University nor of the Laboratory may be used
* to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, 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.
__oo^oo__
