

 H.323 support for ASTERISK soft PBX
-------------------------------------

 The source files and the procedure described below
 incorporate OpenH323 support into the ASTERISK
 software PBX.

 This distribution is broken down into two components:

  1: "wrapper" (a library)
  2: "asterisk-driver" (a ASTERISK channel driver)


 Required packages
-------------------

 In order to build the ASTERISK PBX with OpenH323
 support, you will need some source packages. These
 are the following:

  o PWlib (Portable Text and GUI C/C++ Class Library)
    download from http://sourceforge.net/projects/openh323 (v1.8.3)
    (required)

  o OpenH323 (Class Library implementing the H.323 protocol)
    download from http://sourceforge.net/projects/openh323 (v1.15.2)
    (required)

  o Asterisk PBX (Open Source Linux PBX)
    download from http://www.asterisk.org (CVS v1-0 branch)
    (required)

  NOTE: Use latest CVS sources for Asterisk. CVS STABLE or older
        versions (e.g. 0.7.1) will not work.

  o OhPhone (Command line H.323 client)
    download from http://www.openh323.org (v1.13.5)
    (optional, used for testing)

  o OpenH323 Gatekeeper (H.323 Gatekeeper)
    download from http://www.gnugk.org (v2.0.7)
    (optional, used for testing)
    Although the usage of a gatekeeper is optional, it is
    recommended for easier address translation.

 This software has been developed and tested with the 
 aforementioned versions of the above packages. Using other versions
 may break things, so try these versions first.

 NOTE: If want to use OpenH323/PwLib versions 1.12.2/1.5.2, then download
       and install asterisk-oh323 version 0.5.9 or 0.5.10. 

 Download
----------

 Since this software is still under development, you should
 always check that you use the latest version. This can
 be downloaded from:

   http://www.inaccessnetworks.com/projects/asterisk-oh323

 
 Compiling
-----------

 First of all download Pwlib and OpenH323. These can be found in their official
 site <http://sourceforge.net/projects/openh323>. Be careful to grab the right
 versions (these mention above). Alternatively, the versions that we used can 
 always be found at <http://www.inaccessnetworks.com/projects/asterisk-oh323/Libraries>.
 Then build the OpenH323/Pwlib libraries. This step usually includes the 
 following actions:

   ~$ cd /path/to/pwlib
   pwlib$ ./configure
   pwlib$ make clean; make opt
   pwlib$ cd /path/to/openh323
   openh323$ ./configure
   openh323$ make clean; make opt

 There is no need to install the libraries, so don't do it!
 
 For Asterisk look at <http://www.asterisk.org/index.php?menu=download>
 for download/compile instructions.

 Then, edit "Makefile" inside the "asterisk-oh323-x.x.x" directory
 and set the paths/options according to your system. 

 Type "make" to build the oh323wrap library and the 
 ASTERISK OH323 channel driver.

 Type "make install" to install the binaries. This will also
 install a sample configuration file, if there isn't one.

 Next, add to your LD_LIBRARY_PATH the path where the oh323wrap
 library was installed (or edit your /etc/ld.so.conf file, add
 the library path, and run "ldconfig"). If you built the channel driver
 with statically linked the OpenH323/Pwlib/oh323wrap libraries, then
 you don't have to make these additions.

 Then, you would like to edit the driver's configuration
 file (see below).

 Finally, run "asterisk" and try it with a H.323 IP phone
 like "ohphone" from OpenH323 site or Netmeeting. See also
 the file "TESTS" for detailed configuration and setup.


 Configuration of OpenH323 channel driver
------------------------------------------

 Configuration info can be found in file "CONFIGURATION".


 Console commands
------------------

 The following commands are supported from within the ASTERISK's
 console:

 "oh323 show stats" - Displays statistics for the OpenH323 channel
                      driver (incoming calls, outgoing calls,
                      dropped calls, blocked calls, call errors, ...)

 "oh323 show channels" - Displays information about all active H.323 calls
                     (state, direction, format, ...)

 "oh323 show conf" - Displays configuration information about the
                     OpenH323 channel driver.

 "oh323 show vars" - Display variables of active H.323 channels. The variables
                     supported by the OH323 channel driver are shown in
                     the next section.

 "oh323 debug toggle" - Toggle OpenH323 channel driver's internal debug
                        flag on/off.


 OH323 channel variables
-------------------------

 Each active OH323 channel uses a set of special channel variables. These
 variables can be used to extract detailed information about the active call
 or to change the behavior of the driver when making calls. The following list 
 shows the variables and explains their role:

 ${OH323_CTOKEN} - Contains the H.323 call token. 
 ${OH323_SRCALIAS} - Contains the alias(es) of the source EP.
 ${OH323_DSTALIAS} - Contains the alias(es) of the dest. EP.
 ${OH323_SRCE164} - Contains the E.164 number of source EP.
 ${OH323_DSTE164} - Contains the E.164 number of dest. EP.
 ${OH323_REMOTEAPP} - Contains the name of the remote H.323 app. 
 ${OH323_CHANCODEC} - Contains the name of the codec in use.

 The above variables are updated by the driver on call initiation. They can
 be used by other Asterisk applications or AGI scripts to extract detailed
 information about each call (e.g. the IP address of the remote endpoint)
 and act on them.
 The variable below can be set from within the dialplan to alter the 
 configuration of the driver in run-time:

 ${OH323_OUTCODEC} - The codec to be used by the driver on an outgoing call.
                  The variable is checked by the driver when Asterisk requests
                  the initiation of an H.323 call (e.g. in Dial() app).
                  Valid values for the variable are: g723.1, gsm, ulaw,
                  alaw, g726, slinear, lpc10, adpcm, g729, speex, ilbc. Note
                  that not all of these are supported by the current
                  implementation of the driver.
                  Usage example:

 ; Reach 'michael' with a different codec, based on the extension dialed.
 exten => 111,1,SetGlobalVar(OH323_OUTCODEC=ulaw)
 exten => 112,1,SetGlobalVar(OH323_OUTCODEC=gsm)
 exten => 113,1,SetGlobalVar(OH323_OUTCODEC=g729)
 exten => _11X,2,Dial(OH323/michael)


 Licensing
-----------

 "H.323 support for ASTERISK" copyright (c) 2002-2005 InAccess Networks 

 "H.323 support for ASTERISK" is free software;
 you can redistribute it and/or modify it under the terms of the
 GNU General Public License as published by the Free Software Foundation;
 either version 2 of the License, or (at your option) any later version. 

 "H.323 support for ASTERISK" is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty
 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 See the GNU General Public License for more details. 

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to the Free Software
 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 

 In addition, specific permission is granted to OpenSSL, OpenH323 and PWLib
 libraries to link to the wrapper library and the channel driver
 of this software.


 Credits
---------

 Thanks to the following people for providing help with regard to 
 this software:
  - Mark Spencer for providing Asterisk (of course) and for several 
    suggestions and improvements,
  - Oliver Daudey for some bug fixes,
  - Lubomir Christov for extensive testing,
  - Pawel Golaszewski for minor additions in the make process
  - Marian Durkovic (Caller*ID fix and proper queueing of control frames)


Enjoy,

Michalis Manousos
Dimitris S. Economou

inAccess Networks S.A.
www.inaccessnetworks.com


