home *** CD-ROM | disk | FTP | other *** search
/ ftp.muug.mb.ca / 2014.06.ftp.muug.mb.ca.tar / ftp.muug.mb.ca / pub / openh323.tar.gz / openh323.tar / openh323 / ReadMe.txt < prev    next >
Text File  |  2003-08-04  |  21KB  |  531 lines
  1.               OpenH323 Library
  2.               ================
  3.  
  4.  
  5.  
  6. The OpenH323 project aims to create a full featured, interoperable, Open
  7. Source implementation of the ITU H.323 teleconferencing protocol that can be
  8. used by personal developers and commercial users without charge.
  9.  
  10. OpenH323 development is coordinated by an Australian company, Equivalence Pty
  11. Ltd (http://www.equival.com), but is open to any interested party. Commercial
  12. and private use of the OpenH323 code, including use in commercial products
  13. and resale,  is enouraged through use of the MPL (Mozilla Public license).
  14.  
  15.  
  16. For more details see http://www.openh323.org
  17.  
  18. You can subscribe to the mailing list at http://www.openh323.org/mailman/listinfo
  19.  
  20. Frequently asked questions are answered at http://www.openh323.org/faq.html
  21.  
  22.  
  23.  
  24. Building the OpenH323 Code
  25. ==========================
  26.  
  27. This page describes how to compile the OpenH323 code release. Note these
  28. instructions will always refer to the latest snapshot available on the
  29. download page.
  30.  
  31. The OpenH323 source will have been compiled and tested under Linux x86, and
  32. Windows NT. If it does not compile for you then the problem is likely to be a
  33. setup/configuration problem with your system and not a problem with the
  34. source code itself.
  35.  
  36. The libraries and applications should also compile on Windows 95/98, BeOS
  37. (thanks Yuri!), Linux PPC, FreeBSD x86, OpenBSD x86 (thanks Roger!) and
  38. Solaris Sparc & x86. They are not automatically compiled on every release
  39. however so there could be problems, but the chances are that there aren't.
  40. Note also that not all of these platforms may have ports of the sound
  41. interface.
  42.  
  43. We are also happy to port it to other Unix flavours providing people out
  44. there can provide an account and a fair bit of disk space!
  45.  
  46. These instructions should contain all of the steps need. If you have a problem,
  47. please double check that you have performed ALL of the steps below,
  48. particularly setting the include file paths under MSVC. Some of the more
  49. common errors are described below.
  50.  
  51. If you get a lot of compile or link errors, then the chances are that you
  52. have missed something in the list. If you are positive that something is
  53. wrong and you have followed the instructions, then send an e-mail to the
  54. mailing list, and we'll answer it for everyone to see. Bear in mind that the
  55. first question asked will be "did you follow the instructions".
  56.  
  57.  
  58.  
  59.  
  60. Windows
  61. -------
  62.  
  63. 1.  Download the pwlib_1.xx.zip and openh323_1.x.zip files from the OpenH323
  64.     download page. 
  65.  
  66. 2.  Follow the instructions for building PWLib. 
  67.  
  68. 3.  Start MSVC (v5 or v6). If you have another compiler you are on your own!
  69.     Go into the Tools menu, Options item, Directories tab and add to the
  70.     beginning of the Include files path (note the order is important!):
  71.  
  72.     C:\OpenH323\Include
  73.  
  74.     and add to the Lib Files path and the Executable Files path the following:
  75.  
  76.     C:\OpenH323\Lib
  77.  
  78.     Also make sure the last directory is in your PATH environment variable.
  79.  
  80.     Note this is in addition to the ones in PWLib!!
  81.  
  82. 4.  Use the OpenH323.dsw file to build the sample code, eg SimpH323.
  83.  
  84.     The build should automatically create a file openh323/include/openh323buildopts.h
  85.     via the configure.exe program that should be in the openh323 directory. If
  86.     you have any problems try running the program directly from a command
  87.     line. Use ".\configure --help" to get information on options such as
  88.     forcing a feature or library dependency.
  89.  
  90.     Note there are additional notes in the "Platform Specific Issues" on how
  91.     to compile the various libraries in a manner suitable for use by OpenH323
  92.     under Windows.
  93.  
  94. 5.  Run the program, and you are on your own! 
  95.  
  96.  
  97.  
  98. Unix
  99. ----
  100.  
  101. 1.  Download the pwlib_min_1.xx.tar.gz and openh323_1.xx.tar.gz files from
  102.     the OpenH323 download page. 
  103.  
  104. 2.  Follow the instructions for building PWLib. 
  105.  
  106. 3.  Extract the contents of the openh323_1.x.tar.gz file somewhere, eg:
  107.  
  108.       cd
  109.       tar -xzvf openh323_1.1alpha1.tar.gz
  110.  
  111. 4.  If you have not installed OpenH323 in your home directory (~/openh323)
  112.     then you will have to define the environment variable OPENH323DIR to
  113.     point to the correct directory.
  114.  
  115.     Also make sure you have added the $OPENH323DIR/lib directory to your
  116.     LD_LIBRARY_PATH environment variable if you intend to use shared libraries
  117.     (the default under Linux).
  118.  
  119.     There are examples for sh/bash and csh/tcsh below.
  120.  
  121. 5.  Build the H323 bootstrap code. This will automatically build the ASN
  122.     compiler (in the $PWLIBDIR/tools/asnparser directory), though this should
  123.     have already been built previously. Enter:
  124.  
  125.     cd $(OPENH323DIR)
  126.         ./configure
  127.     make opt
  128.  
  129.     This may take some time, especially with the h245_*.cxx and h225.cxx
  130.     files. You may also need to add more swap space - 64M of real memory and
  131.     64M of swap might just be enough, if your machine does nothing else! Some
  132.     people have reported needing as much as 256M of swap - if your compiler
  133.     bombs out with a "virtual memory exhausted" error compiling h245_*.cxx
  134.     and h225.cxx, then increase your swap space.
  135.  
  136.     Less space is required if you build the debug version - Debug builds on 64M ram are
  137.     very achievable. Opt builds on 164M ram are doable, but only just.
  138.  
  139. 6.  The result should be an executable called simph323, which will be located
  140.     in a directory dependent on the platform, eg sample/simple/obj_linux_x86_d.
  141.     To run it, use the following command:
  142.  
  143.     ./sample/simple/obj_linux_x86_r/simph323
  144.  
  145.     and you should get the usage help text.
  146.  
  147. 9.  Now you're on your own! 
  148.  
  149.  
  150.  
  151. Voice Age G.729 Codec
  152. ---------------------
  153.  
  154. For the Windows system it is possible to also have a G.729 codec
  155. for non-commercial use by adding the Voice Age G.729A library to the system.
  156. To do this:
  157.  
  158. 1.  Get the Voice Age G.729 library from http://www.voiceage.com/g729/
  159.  
  160. 2.  Unpack it somewhere, preferably at teh same level as OpenH323, eg if
  161.     c:\work\openh323, then c:\work\va_g729a
  162.  
  163. 3.  Re-run the configure program.
  164.  
  165. 4.  Recompile your project.
  166.  
  167.  
  168.  
  169. H263 Support.
  170. =============
  171.  
  172.   H263 is a video compression format which is especially suited for low
  173.   bandwidth situations, such as a dial up link. By adding the requisite
  174.   library, recompiling openh323 and ohphone applications, H263 support is
  175.   available.
  176.  
  177.   Two H263 codecs are in the Openh323 codebase.
  178.   1)ffmpeg, and 2)vich263
  179.  
  180.   1)ffmpeg.
  181.   Note that the H.263 support in OpenH323 is not yet compliant with RFC 2190,
  182.   which means it is not yet interoperable with applications like NetMeeting.
  183.  
  184.   OpenH323 implemented H263 using the ffmpeg library, which does NOT use the
  185.   same license as OpenH323. Please read the license  information at
  186.   http://ffmpeg.sourceforge.net to ensure that your usage of this code is
  187.   allowed.
  188.   OpenH323 has labelled the H263 support from ffmpeg as non standard. Some non
  189.   standard hacks were added to the packets generated by ffmpeg to get it working
  190.   in a voip environment.
  191.   To be absolutely certain of no license problems from ffmpegs LGPL/GPL, ffmpeg
  192.   is dynamically opened by openh323 at run time with dlopen.
  193.  
  194.   2)vich263
  195.    is more compliant than the ffmpeg version.
  196.    Andrew Morrow who did the hard part of the implementation reports that:
  197.     I got something working using vic's H.263 (not plus) in OpenH323.
  198.                                                                                                                                             
  199.    It does not interoperate with NetMeeting, but it does interoperate with
  200.    IBM's J323/JMF.
  201.  
  202. Unix
  203. ----
  204.     The library was built with
  205.       cd external/ffmpeg
  206.       ./configure --enable-shared --disable-a52
  207.       cd libavcodec
  208.       make 
  209.       make install
  210.       
  211.     The code is in the CVS, external/ffmpeg directory at sourceforge.
  212.     Instructions on using the cvs are at http://sourceforge.net/cvs/?group_id=80674
  213.  
  214.     cd external/vich263
  215.     make
  216.     make install
  217.  
  218.     ====
  219.     If you have the external directory on your box, with vich263 and ffmpeg, but do
  220.     not wish to enable ffmpeg or vich263, you can
  221.         
  222.        cd openh323
  223.        /configure
  224.        make
  225.  
  226.        on recompiling the openh323 directory, you will not do configure again, so
  227.        your ffmpeg and vich263 settings will remain.
  228.  
  229.      Should you wish to build in support for both H263 codecs, do:
  230.  
  231.        export H323_VICH263=1
  232.        export H323_AVCODEC=1
  233.        cd openh323
  234.        /configure
  235.        make
  236.  
  237.        Now, if you just want 1 codec, just have the appropriate export statement.
  238.        Note that when you do ./configure, there is a clear statement what codec is on.
  239.        If you wish to remove both codecs, (after doing a configure with them on), do
  240.  
  241.        export H323_VICH263=""
  242.        export H323_AVCODEC=""
  243.        cd openh323
  244.        /configure
  245.        make
  246.  
  247.     Now, these settings are fixed, and remain in place on subsequent makes. Thus,
  248.     on recompiling the openh323 dir, you don't need to rerun configure.
  249.  
  250.     Now, to test the operation of the H263 codec. I used the command below in
  251.     the ohphone directory:
  252.      
  253.       ./obj_linux_x86_r/ohphone -ln --videotest --videolocal \
  254.             --videoreceive sdl --videodevice fake --videoinput 1 \
  255.             --videobitrate 24
  256.  
  257.     This brings up a SDL display window with two copies of the same image. The
  258.     image on the right is generated by the fake video device, on channel 1.
  259.     The image on the left is the decoded form of an image that has been
  260.     encoded with H263.
  261.  
  262.     Wait a while, and then type q, the display will tell you what bit rate
  263.     was achieved, and the frame rate. The achieved bit rate should always be
  264.     less than that specified in the --videobitrate option
  265.  
  266.     Now, you can try the H261 codec instead. To use H261, add to the command
  267.     line -D 263, so your command line becomes:
  268.  
  269.       ./obj_linux_x86_r/ohphone -ln --videotest --videolocal \
  270.             --videoreceive sdl --videodevice fake --videoinput 1 \
  271.             --videobitrate 24 -D 263
  272.  
  273.     Get mean, set a bit rate of 12 Kilobits/sec
  274.  
  275.     Now, you might have a problem with it not finding the libavcodec.so library.
  276.     In this case, you need to extend your LD_LIBRARY_PATH
  277.  
  278.       export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
  279.  
  280.     or append to /etc/ld.so.conf the directory /usr/local/lib and rerun ldconfig
  281.  
  282.       ldconfig -C /etc/ld.so.conf   Do this command as root.
  283.  
  284.     Alternatively, append to the configure command above the phrase
  285.     --prefix=/usr. This will cause all the ffmpeg stuff to go in system
  286.     directories, where it will be found guaranteed.
  287.  
  288.  
  289. Windows
  290. -------
  291.   The ffmpeg codec is built with MingW. There have been some valiant efforts to get ffmpeg
  292.   to build under msvc. However, many many code changes were required. Consequently, the code
  293.   became not standard with the source code.
  294.  
  295.   1) move ffmpeg directory
  296.      from c:\external to c:\msys\1.0\home\administrator
  297.                                                                                                                                             
  298.   2) start msys
  299.                                                                                                                                             
  300.   3) cd ffmpeg
  301.                                                                                                                                             
  302.   4) do
  303.    ./configure --cc="gcc -mno-cygwin -mms-bitfields" --with-mingw32 "gcc -mno-cygwin -mms-bitfields"
  304.        --enable-shared --disable-a52 --disable-ffserver --disable-ffplay
  305.                                                                                                                                             
  306.    this configure command is in external/ffmpeg/windows file
  307.                                                                                                                                              
  308.   5) cd libavcodec
  309.                                                                                                                                             
  310.   6) make
  311.        (don't worry about the message about symbols)
  312.                                                                                                                                             
  313.   7) exit msys (just type exit)
  314.                                                                                                                                             
  315.   8) move ffmpeg back to c:\external (opposite of step 1)
  316.                                                                                                                                             
  317.   9) move c:\external\ffmpeg\libavcodec.dll to c:\openh323\lib
  318.                                                                                                                                             
  319.  10) compile libvich263
  320.      Simply go to external\vich263
  321.      open the libvich263 workspace.
  322.      select batch build, buld release and debug.
  323.      leave libvich263.lib where it puts this library.
  324.                                                                                                                                             
  325.  11) Open up a dos terminal
  326.                                                                                                                                             
  327.      go to c:\openh323
  328.                                                                                                                                             
  329.      configure
  330.                                                                                                                                             
  331.      Check that options are set correctly in
  332.        c:\openh323\include\openh323buildopts.h
  333.                                                                                                                                             
  334.       (note, openh323buildopts.h is from openh323buildopts.h.in)
  335.                                                                                                                                             
  336.     If it fails to build openh323buildopts.h, well, it is OK.
  337.     copy from pwlib/tools/configure the files configure.cpp and configure.dsp
  338.       to the directory c:\openh323
  339.     Open configure.dsp project in msvc, build and run configure.exe
  340.  
  341.     recompile the OpenH323Lib and OpenH323DLL
  342.     projects to create new OpenH323 libraries.
  343.  
  344.  
  345. Common errors
  346. -------------
  347.  
  348. Here are common errors you might encounter for both Windows and Unix builds.
  349.  
  350.   An error like:
  351.     "Makefile", line 175: Missing dependency operator
  352.     "Makefile", line 177: Need an operator
  353.     "Makefile", line 179: Missing dependency operator
  354.     "Makefile", line 181: Need an operator
  355.     "Makefile", line 183: Missing dependency operator
  356.     "Makefile", line 185: Need an operator
  357.  
  358.     Indicates you are using BSD Unix's Make command. You need to use
  359.     gmake (GNU Make).
  360.  
  361.   Thinking there are missing files.
  362.  
  363.     A number of files, eg h235.h, h225.h etc, are generated files that are
  364.     created during the build process. If they are missing then something
  365.     went wrong with the creation of the asnparser or your installation of
  366.     flex/bison.
  367.  
  368.   An error like:
  369.     /home/newbie/pwlib/tools/asnparser/obj_linux_x86_r/asnparser: error in loading
  370.     shared libraries: libpt_linux_x86_r.so.1: cannot open shared object file: No
  371.     such file or directory
  372.  
  373.     Indicates you have not set the LD_LIBRARY_PATH environment variable.
  374.     There are examples for sh/bash and csh/tcsh.
  375.  
  376.   An error like:
  377.     Linking...
  378.     LINK : fatal error LNK1181: cannot open input file "ptlib.lib"
  379.     Error executing link.exe.
  380.  
  381.     Indicates you have not set the paths in MSVC directories.
  382.  
  383.   An error like:
  384.     Performing Bison Step
  385.     c:\tools\share\bison.simple: No such file or directory
  386.     C:\PWLIB\TOOLS\ASNPAR~1\BISON.EXE: Cannot move asn_grammar_tab.c - No such file or directory
  387.     Cannot move asn_grammar_tab.h - No such file or directory
  388.  
  389.     Indicates you have not installed bison correctly. In particular the
  390.     bison.simple file must be available to bison. Check the bison
  391.     documentation for details on this.
  392.  
  393.   Attempting to compile GUI systems under Unix.
  394.  
  395.     There are a number of partial implementations of the GUI code in the
  396.     $PWLIBDIR/src/pwlib directory tree. These are not required to get the
  397.     OhPhone application compiled. If you get those systems from the CVS
  398.     then you are basically on your own. Do not ask for support unless you
  399.     intend to help with the implementation!
  400.  
  401.  
  402. See the FAQ at http://www.openh323.org/~openh323/fom.cgi for more.
  403.  
  404.  
  405.  
  406. Example environment for sh/bash
  407. -------------------------------
  408.  
  409. PWLIBDIR=$HOME/pwlib
  410. export PWLIBDIR
  411. OPENH323DIR=$HOME/openh323
  412. export OPENH323DIR
  413. LD_LIBRARY_PATH=$PWLIBDIR/lib:$OPENH323DIR/lib
  414. export LD_LIBRARY_PATH
  415. Example environment for csh/tcsh:
  416.  
  417. setenv PWLIBDIR $HOME/pwlib
  418. setenv OPENH323DIR $HOME/openh323
  419. setenv LD_LIBRARY_PATH $PWLIBDIR/lib:$OPENH323DIR/lib
  420.  
  421.  
  422.  
  423.  
  424. Bison problem under Unix
  425. ------------------------
  426.  
  427. The bison.simple file on many releases will not compile with the options used
  428. by the PWLib getdate.y grammar. The options are required to make the date
  429. parser thread safe so it is necessary to edit the bison.simple file to fix
  430. the problem.
  431.  
  432. The file is usually at /usr/lib/bison.simple but in the tradition of unix
  433. could actually be anywhere. We leave it up to you to find it.
  434.  
  435. The code:
  436.  
  437. /* Prevent warning if -Wstrict-prototypes. */
  438. #ifdef __GNUC__
  439. int yyparse (void);
  440. #endif
  441. should be changed to
  442.  
  443. /* Prevent warning if -Wstrict-prototypes. */
  444. #ifdef __GNUC__
  445. #ifndef YYPARSE_PARAM
  446. int yyparse (void);
  447. #endif
  448. #endif
  449.  
  450. To prevent the incorrect function prototype from being defined. The getdate.y
  451. should then produce a getdate.tab.c file that will actually compile.
  452.  
  453.  
  454.  
  455.  
  456. Licensing
  457. ---------
  458.  
  459. The bulk of this library is licensed under the MPL (Mozilla Public License)
  460. version 1.0. In simple terms this license allows you to use the library for
  461. any purpose, commercial or otherwise, provided the library is kept in tact
  462. as a separate entity and any changes made to the library are made publicly
  463. available under the same (MPL) license. It is important to realise that that
  464. refers to changes to the library and not your application that is merely
  465. linked to the library.
  466.  
  467. Note that due to a restriction in the GPL, any application you write that
  468. uses anything another than GPL, eg our library with MPL, is technically in
  469. breach of the GPL license. However, it should be noted that MPL does not
  470. care about the license of the final application, and as only the author of
  471. the GPL application is in breach of his own license and is unlikely to sue
  472. themselves for that breach, in practice there is no problem with a GPL
  473. application using an MPL or any other commercial library.
  474.  
  475.  
  476.  
  477. Portions of this library are derived from TOAST, using the copyright:
  478.  
  479. Copyright 1992, 1993, 1994 by Jutta Degener and Carsten Bormann,
  480. Technische Universitaet Berlin
  481.  
  482. Any use of this software is permitted provided that this notice is not
  483. removed and that neither the authors nor the Technische Universitaet Berlin
  484. are deemed to have made any representations as to the suitability of this
  485. software for any purpose nor are held responsible for any defects of
  486. this software.  THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
  487.  
  488. As a matter of courtesy, the authors request to be informed about uses
  489. this software has found, about bugs in this software, and about any
  490. improvements that may be of general interest.
  491.  
  492.  
  493.  
  494. Portions of this library is derived from vic, http://www-nrg.ee.lbl.gov/vic/
  495. Their copyright notice is below.
  496.  
  497.  * Copyright (c) 1993-1995 The Regents of the University of California.
  498.  * All rights reserved.
  499.  * 
  500.  * Redistribution and use in source and binary forms, with or without
  501.  * modification, are permitted provided that the following conditions
  502.  * are met:
  503.  * 1. Redistributions of source code must retain the above copyright
  504.  *    notice, this list of conditions and the following disclaimer.
  505.  * 2. Redistributions in binary form must reproduce the above copyright
  506.  *    notice, this list of conditions and the following disclaimer in the
  507.  *    documentation and/or other materials provided with the distribution.
  508.  * 3. All advertising materials mentioning features or use of this software
  509.  *    must display the following acknowledgement:
  510.  *      This product includes software developed by the Network Research
  511.  *      Group at Lawrence Berkeley National Laboratory.
  512.  * 4. Neither the name of the University nor of the Laboratory may be used
  513.  *    to endorse or promote products derived from this software without
  514.  *    specific prior written permission.
  515.  * 
  516.  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  517.  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  518.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  519.  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  520.  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  521.  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  522.  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  523.  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  524.  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  525.  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  526.  * SUCH DAMAGE.
  527.  
  528.  
  529.  
  530.               __oo^oo__
  531.