Back to files

 ---        asterisk-oh323        ---
 ---     OH323 channel driver     ---

Introduction

The source files and the procedure described below incorporate H.323 support into the ASTERISK software PBX. The H.323 protocol stack is provided by the OpenH323 project.

This distribution is broken down into two components:

The "wrapper", a library that implements the required glue-logic and abstraction layer between the internals of OpenH323 and the application (Asterisk in our case).
The "asterisk-driver", a standard Asterisk channel driver.

Required packages

In order to build the OH323 Asterisk channel driver you will need some other packages. We recommend to download their source and build them. These are the following:

PWlib (Portable Text and GUI C/C++ Class Library) download from http://sourceforge.net/projects/openh323 (v1.8.7/Mimas_patch2) (required)
OpenH323 (Class Library implementing the H.323 protocol) download from http://sourceforge.net/projects/openh323 (v1.15.6/Mimas_patch2) (required)
Asterisk PBX (Open Source Linux PBX) download from http://www.asterisk.org (CVS v1-0, 2005-09-08) (required)
OhPhone (Command line H.323 client) download from http://www.openh323.org (v1.13.5) (optional, used for testing)
OpenH323 Gatekeeper (H.323 Gatekeeper) download from http://www.gnugk.org (v2.2.2) (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.

Download

Since this software is still under development, you should always check that you use the latest version. This can always 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

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. If you compile asterisk-oh323 with OpenH323/Pwlib older that the Pandora series (e.g. Janus series) something that we do not recommend, then in the Makefile uncomment the line:

USE_OLD_CAPABILITIES_API=1

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").

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. The following list shows the variables and explains their role:

${OH323_CTOKEN} - Contains the H.323 call token. ${OH323_CALLID} - The call ID.
${OH323_CONFID} - The conference ID of the call. ${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. ${OH323_RADDR} - Contains the remote IP address/port of the connection. ${OH323_LADDR} - Contains the local IP address/port of the connection.

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 (e.g. block calls from specific IPs). 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" 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,
Derek Smithies and Craig Southeren for suggestions and comments,
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),
Stefan Grossberger for proper call transfer handling

Enjoy,

Michalis Manousos
Dimitris S. Economou

inAccess Networks S.A.
www.inaccessnetworks.com