This report details what I have done and achieved throughout the Fall 1999 semester investigating the ITX project for Professor Henning Schulzrinne. I also intend it to guide other people who want to install the package and write ITX applications themselves. Hopefully, this document will help them avoid starting from scratch.
The ITX package is developed at Cornell University, Ithaca, New York. It is a Java API package for developing network-based telephony application. The package consists of four main Java packages: directory service, signaling, data exchange, and gateway. The package also interacts with some amount of native codes, focused on the Windows NT platform. The choice of Windows NT seems to be because currently, the gateway card of choice--the Dialogic type--works only on NT. However, the directory server (implemented with BIND, widely used as a DNS server) needs to be installed in a UNIX-based machine, because the ITX package relies on the dynamic update capability of BIND, which is available only on version 8 and available only for the UNIX platform.
A common application of an ITX application will be calling another user registered on the same directory server. The process begins when the application registers itself to the directory server; the server will store the application's location. Now, when the application wants to call another application (used by another user), it will check the directory server whether the other application is registered. The server returns the location of the destination user, if he has also registered himself. Then the process will be in the form of a 3-way handshake: the initiating application sends an invitation packet to the destination application, the destination acknowledges the receipt of the invitation by sending an accept or reject packet, and the initiator send an acknowledgement packet when it receives the packet from the user. If the destination accepts the invitation, then a connection is established and they start the call. For an animated explanation, please check http://www.cs.cornell.edu/cnrg/telephony/JavaDocs/flash/itx_core_components.htm
Logically, there are two kinds of application that you need with ITX: a directory service manager, and the telephony application itself. The gateway itself can be run by running the cnrg.itx.gtwy.Gateway class (the class contains a main() method), or you can also run gateway.exe at %ITX Directory%\CNRG\CU Telephony\gateway\gateway.exe (it is an executable that wraps the runnable class).
There are four levels of users for the directory service, defined by static variables in the cnrg.itx.ds.DirectoryService class:
Only the administrator has the priviliged of accessing the methods that modify users' data in the server. Currently, there is not a way to initialize the administrator in the database, so this process needs to be done manually. You need to modify the db.ext2user, db.userid2sec, and db.userid2ext files. The format can be seen in this document. To obtain the encoded password for the administrator, you can write a small application that utilizes the cnrg.itx.ds.Password.toString() method.
If you have the administrator set up, you can proceed with writing the directory service manager. The administrator needs to initialize the cnrg.itx.ds.DirectoryService object; for this, he needs to have the resolv.conf file (configuration file containing the address of the directory server), and puts the path as a parameter when initializing DirectoryService. At this point, he is not yet logged in; the method DirectoryService.declareIdentity() needs to be called to login. To check whether the logged in user is an administrator, you can use the DirectoryService.getAccessLevel() method. Once it is verified that the user has administrator's privileges, then the administrator can manage the users. Some of the useful methods are DirectoryService.addUser(), DirectoryService.removeUser(), and DirectoryService.setPIN() (to change the password of a user). I have written a GUI-based implementation of the directory service manager; I explain more about this a little bit later.
There are two sides to the telephony application: and the initiating side and the destination side. Both can and usually exist together in a telephony application, but their behaviors differ. But before detailing the differences, I will illustrate their common features in the ITX context.
An ITX telephony application needs to instantiate a cnrg.itx.signal.DesktopSignaling object. Moreover, a two-way (full duplex) ITX telephony application needs to have an input channel, an output channel, an audio connection, and a signal connection. These are implemented using cnrg.itx.datax.Channel objects for both the input and output channels, a cnrg.itx.datax.AudioConnection object for the audio connection, and a cnrg.itx.datax.SignalConnection object for the signal connection.
When the initiator wants to initiate a call, it calls the DesktopSignaling.Dial() method for the user. The parameters to this method are the user or address to call, and the connection. The further details are handled by this method. Unless there is an exception (such as a reject packet), the initiator can open the audio connection, assuming it has been initialized, and the call is made.
The destination needs to implement the cnrg.itx.signal.SignalingObserver. Extending the cnrg.itx.signal.AbstractSignalingObserver is, in some cases, easier. Basically, the destination waits for an event from the initiator, and upon its arrival, an event-handling method is called. There are five event-handling methods declared in the SignalingObserver interface:
On onInvite, the destination can either accept or reject the call, and also initialize the channels and connection used for the call. On onStartCall, the destination opens the connection and starts the call. The channels need to be closed in onAbortCall and onHangup so that it can be used for another call. These are the general implementation for these methods, but the application developer can add their own implementation.
NOTE TO ITX DEVELOPERS: There needs to be more information about when to manually initialize the channels and the connections, and when they are initialized automatically by the library. In a more general sense, there needs to be more information about the differences and the impacts of the overloaded methods, including overloaded constructors, of all the ITX classes. This will help the developer to make an informed decision about which method(s) to use among the overloaded options.
DSManager is an ITX directory service manager that I wrote. There is a DSAuthenticator responsible for the authentication process, and a DSUserManager responsible for managing the users (after authentication). The GUI is implemented using Swing. Because of the time constraint, I did not use any formal design approach, neither did I comment much of the source code. However, I tried in my best to make the design adhere as much as possible to object-oriented principles and used self-explanatory names for the variables and methods. So I hope by spending a minimal amount of reading through the source code, one can understand how the application works.
The first thing that an administrator needs to do is to load a configuration
file. Once loaded, the administrator can login and do the user management tasks.
Loading another configuration file forces the administrator to login again.
Check the menus under File for these options.
The add user and remove user buttons and menus are self explanatory. To add
a user, the administrator needs to put a user ID, extension, password (twice),
access level, and custom message (usually the real name of the user). To remove
a user, the administrator first needs to highlight a user in the users table.
NOTE: for the gateway server, you need to have a special user with server access level. In the current implementation, the user name for the gateway server is "gatewaysrv" and the password is "itxgw". But you can change this by changing the source code for the cnrg.itx.gtwy.SignalInterface class (look for the SignalInterface(Gateway, boolean) constructor).
There are two problems in the source code that I delved into. The first one concerns the "stupid bug" mentioned in the cnrg.itx.datax.jaudio.JAudioInfo class. The stupid bug relates to a link error occuring everytime JAudioInfo.numDevicesN. The source of this bug is because the library "jaudio" has not been loaded. I have fixed this, and it is included in the source for JAudioInfo that I include with the zipped package for the project.
The second problem concerns the hangup event for the gateway, specifically in the native code for the method cnrg.itx.gtwy.SignalInterface.recordPacket(). The current implementation--also the implementation included in the zipped package--specifies a hangup as when the sr_getevttype() function returns a TDX_RECORD. However, at least for the phone at Columbia's CS department and the gateway card used, this is not necessarily the case. I tried to change the hangup as all the closing events except for the user-defined event (VCHAN_RECORD), but this does not work in some cases. So I leave the original implementation intact to be fixed at some point in the future.
Another issue, unsolvable unless by rewriting a major part of the native implementation, is the reliance of the JAudio system with Microsoft's RNI (Raw Native Interface) proprietary technology. This means the telephony application can be run only with Microsoft VM. Microsoft VM does not support Java 1.2, so developers wanting to build a user interface with Swing will face a dead-end. One alternative for developers desiring a user interface is to use Microsoft's WFC (Windows Foundation Class), but this also brings the consequence of limiting the platform to Windows. Another alternative, harder to do but will theoretically solve the problem, is to convert the RNI implementation to JNI. I do not have any knowledge whether the use of RNI is actually preferable to that of JNI.
Other issues that come up, but which have not been investigated deeply, and the features that have not been looked at thoroughly, are
In addition, the performance of the application has not been looked into yet. It might be the case that changing some of the implementation will improve the performance of the system; someone needs to look at this.
The ITX package provides an API to write telephony applications. It is a good starting point for the developers so that they do not have to worry about the low level details of implementing their applications; some works, however, still need to be done to solve the issues and improve the package further. In addition, developers can also use it as a reference point to build their own telephony API package.
Indrayana Rustandi
ir74@cs.columbia.edu