What we accomplished

Changes from initial specification

It turns out that most of the necessary code is already written.  It is called the Dialogic SDK   What we actually had to do was to figure out how to use it for this specific functionality. 

We also found that we had to deviate quite a bit from the original specification due to hardware limitations.

• The Dialogic card provided (D/41E) has only four phone lines, not eight.
• It turns out that digitized data can only be accessed via a voice channel device that can either record or play data, but not both at the same time. As a result we are using two channels per phone connection.  Since there are only four channels, we can serve at most two simultaneous connections.
• The smallest possible read buffer size is 512 bytes, and the smallest write buffer size is 1024 - we do not know whether this is a hardware or a software limitation.  As a result, the delay introduced by the gateway is already so big that we do not have to worry about making it a little bit bigger.
• Since we were told that the IPLink card does not work, we did not try to use it.

The data exchange team's design for multi-point communication did not require anything special in the gateway.

How our code works

C library

We discussed several possible languages for implementing the gateway, such as Java, C++ and Ocaml (ML dialect).  However, the Dialogic SDK provides a API for C, so the library implementing all of our basic functionality is written in C.

We provide a function to establish a connection, that

• Makes sure the phone line is "off-hook"
• Creates two unidirectional SCBus routes between a phone line analog channel device and two voice channel devices.
• Programs one voice channel device to play data and another - to record data. The devices are programmed to use the user I/O functions to retrieve and store data. The recording channel is also instructed to terminate recording when DTMF tone is detected.

The user I/O functions are simple:

• The read function asks Data Exchange for data, converts acquired data from linear PCM to mu-law format. If necessary, it pads data with silence.
• The write function converts data from mu-law to linear PCM and gives it to Data Exchange.

When the channel notifies, via an event handler, that the playing or recording was terminated, we determine the reason why. If the reason is that a DTMF tone was detected, we notify Signaling and resume recording (playing should not be terminated by DTMF).   Otherwise, we notify Signaling that a fatal error occurred and the communication should be terminated.  Since termination is synchronous, and cannot be done from an event handler, we do not terminate the connection immediately.  However, Signaling will later tell us to terminate the connection. The TerminateConnection function:

• Makes sure the phone line is "on-hook"
• Stops playing and recording
• Restores the SCBus routing for the involved channels

We also provide an initialization function that

• Gets the Dialogic board information, making sure it really has 4 channels.
• Creates the Dialogic filedescriptor for each of  the channels
• Restores the SCBus routing to its default state
• Makes sure each phone line is "on hook"

Also, we provide a function that dials a number. If channel is busy, this function temporarily terminates the playout on a channel.

Java code

Alas, the rest of the group has done everything in Java.  For the gateway to be able to communicate with anyone else, we needed to provide a Java layer for the C library.   After looking at RNI (Raw Native Interface), JNI (Java Native Interface), and J/Direct, we decided to use J/Direct, as it seemed to be the easiest (Dan S. mentioned the word "automagically" a couple of times). 

The easy part was allowing the other teams to call our C library functions from Java.   But we also needed to be able to call Java functions from C in order to do Data Exchange and to notify Signaling of any events.  J/Direct uses an object called a Callback, which then needs to be registered in the C library.  So we wrote an initialization function in Java that registers the Callbacks as well as calling the C initialization function.

We have three callback objects, the DEReadProc, the DEWriteProc, and the SIEventHandler.  DEReadProc and DEWriteProc basically call the appropriate DataExchange read and write functions.  Most of SIEventHandler was written by Signaling, and sends all of the appropriate signaling messages.

Summary

It works!