Introduction

Welcome to H323 Auto Caller. This application is a simple OpenH323-based WAV file player: you use it to call a H.323 telephone and it will play a WAV file to the remote telephone over the H.323 connection. It has many uses, examples include using it as a Voice Pager in Nagios to notify techs of system problems, using it as a wakeup service with cron, or using it to Voice Spam audio advertisements to phones. If you put it to other interesting uses, please email me to let me know what you have thought up.

Building the Application

Note: h323ac was written and with pwlib_1.4.10 and openh323_1.11.6 It may not work properly with newer versions.

First, you need to have PWLib and OpenH323. We will not explain in detail how to get and compile the two libraries, see the OpenH323 site for detailed instructions. A quick recipe for building the "noshared" targets on a Linux/Unix platform follows. We prefer the "noshared" build targets here because they are slightly easier to use. For example, you can transfer the executables to another machine without having to install the PWLib and OpenH323 libraries.

   1. Put PWLib and OpenH323 into your home directory, i.e. PWLib is in ~/pwlib and OpenH323 is in ~/openh323,
   2. go to ~/pwlib and run
            make bothdepend
            make bothnoshared , 
   3. go to ~/openh323 and run
            make bothdepend
            make bothnoshared . 

If your compiler is gcc 2.96, you need to have optimally 256 MB of RAM (plus 128 MB of swap) or at least 196 MB of RAM (plus more swap) to build both the debug and optimized versions of OpenH323 in reasonable time. If you do not have enough RAM and still wish to experiment with the software, try building only the debug version, using make debugnoshared .

If your gcc is of a version other than 2.96, e.g. 2.95 or 3.2, the memory requirements are smaller. For example, with gcc 3.2 you should be able to build both the debug and optimized versions of OpenH323 with 128 MB of RAM and 128 MB of swap space.

Next, download the file h323ac-1.0.3.tar.bz2 (or any newer version, see the downloads page) to a directory and unpack it using the command

      tar jxvf h323ac-1.0.3.tar.bz2 

Enter the directory h323ac-1.0.3 and build the application using make bothdepend; make bothnoshared. This will give you both the release and debug versions. If you do not need both, use either make optnoshared or make debugnoshared . If you have PWLib and OpenH323 located somewhere else than ~/pwlib and ~/openh323, you must set two shell variables (PWLIBDIR and OPENH323DIR) before compiling. The shell commands are:

      export PWLIBDIR=/somewhere/else/pwlib
      export OPENH323DIR=/somewhere/else/openh323 

The object files (*.o) and h323ac executables (the release and debug version, respectively) will be created in subdirectories obj_linux_x86_r and obj_linux_x86_d. The names of the subdirectories may differ if your platform is not a Linux system on a x86-compatible processor.

The executables produced using the noshared targets already contain all the required code from PWLib and OpenH323. They however depend on several dynamic libraries ? standard C library, standard C++ library, pthreads library, and a few others. If you want to see the full list of dependencies, run ldd h323ac . 

Using the Application

This section is a brief "user manual" for the h323ac application.
Command-line Options

h323ac has the following command-line options:

-f foo --file foo
    Read audio data from WAV file "foo". The file must have the following format: PCM, mono, sampling rate 8000 Hz, sample size 16 bits. This is a mandatory command-line parameter. 
-c bar --call bar
    Call user/number "bar". This can be a standalone user/number if you are using a gatekeeper or a user@gateway (or user@gateway:port) string if you are not. This is a mandatory command-line parameter.
-g addr --gatekeeper addr
    Set gatekeeper's address to addr. 
-G id --gatekeeper-id id
    Set gatekeeper's identifier to id. 
-h --help
    Print help message and exit. 
-n --no-gatekeeper
    Do not register with gatekeeper. 
-o file --output file
    Write trace output to file. 
-p portnum --port portnum
    Listen for incoming call connections at TCP port portnum. The default value is 1820, to allow for simple coexistence with ohphone or another software H.323 telephone on the same computer. 
-t --trace
    Enable trace. Can be used multiple times to increase the detail of trace output. 
-u userid --user userid
    Set user alias to userid. The default value is the login name of the current user. The option can be used more than once to set several aliases. 

If neither -g nor -G are given, the default is to try to discover a gatekeeper with any gatekeeper ID. Use the option -n to override this behaviour.

Examples

* A single computer, no gatekeeper

To try h323ac with ohphone or simph323 on a single computer, without using a gatekeeper, you need to invoke h323ac with the following command:

      ./h323ac -f audio.wav -n -u 320 -c 321@localhost

When started with these options, h323ac will attempt to connect to a H323 phone running on localhost. The file audio.wav must be in the required format. The user alias will be set to 320.


* Registering h323ac with a gatekeeper

Suppose you have a gatekeeper running at IP address 10.1.2.3. Start h323ac as:

      ./h323ac -f audio.wav -u 320 -g 10.1.2.3 -c 321

To use ohphone as the recieving endpoint, start it as follows:

      ./ohphone -l -a -g 10.1.2.3 -u 321 

Once you have ohphone running, it should auto answer any calls to 321 due to the "-a" switch.