Internet Telephony Manager
Project Report


Ruigang Yang
Dept. of Computer Science, Columbia University
New York, NY 10027

Yuwen Tu
Dept. of Computer Science, Columbia University
New York, NY 10027

Caomei Long
Dept. of Computer Science, Columbia University
New York, NY 10027

Table of Content:


With fast growing of the Internet Telephony technology, people require more and more functionalities. This project aims to freindly and automatically process the incoming call. User can use ITM to deal with the daily imcoming calls. The project consists of three modules. Main modules, Group Maintenance module and CM Reader module.

Main module focuses on two interfaces implementation, which are Telephony Server with ITM and User with ITM , and also coordinates with the CM Reader module and Group Maintenance module.
Group Maintenance module
keeps call groups information and complishes the groups information management.
CM Reader module deals with the Calendar Manager interface and retrieve the appointment information.


Project Background

With the rapid growth of internet, intenet telephony becomes a more and more popular topic now. Before 1995, the market for Internet telephony products was virtually nonexistent. A few public domain programs had been released by researchers and hobbyists before then, but without seeing much widespread use. Since that time, dozens of companies have released Internet telephony products that provide real-time personal communications over the Internet using computers at each ends. Part of the reason for this explosive growth can be attributed to the growth of the Internet in general, and other reason is that before 1995, common knowledge was that it was impossible to get good real time communications across the Internet. But many good Intenet telephone applications came out in 1995, which proved this is wrong.

Since we are using computer at each ends for internet telephony, we can do something better than just using it as a dummy telephone. The computer should be able to reject, forward or answer the phone automatically if the user is not around. We found Calendar Manager(CM) is widely used by general Unix users, so the idea came out that we can create an Internet Telephony Manager(ITM) to connect CM with Internet telephony server to realize the above functionalities. User can use CM to type in the message, forward address and action for each individual or group callers for a specific time period. And ITM will retrieve these information if the call comes in this time period.

Widecard address is supported to let user enter an action for a group of callers from one host. To be more convenient, ITM maintains two caller groups. User can enter group information through ITM graphic user interface. The default action, message and forward address can be set for each group, and user is given the ability to override these default settings in CM. Also the widecard address is allowed in caller group. The caller group and widecard address give user great flexibility to specify an action for a set of desired callers.

At beginning of the project, we wanted to the hooked ITM to CM directly so that user can enter all the information in CM. But it seems impossible for us to do so because we don't have source code of CM. So we decided to make ITM a stand alone application. The only link between ITM and CM is that ITM will retrieve the information from CM files. This design works good as the project comes out. User enter the information in CM and ITM will retrieve the required information automatically for each call. The only time user will start ITM manually is when he/she wants to maintain caller groups. But we think this will not create great inconvenience, since the caller group is not intended to be changed frequently.

We choose Tcl/Tk to be the main language to write the program, because of its great simplicity in writing graphical user interface. But Tcl is not efficient in manipulating complex data structure. So we write the Profile keeping and CM reader in C. To keep 2 part working together, based on the original wishx ( the Tcl/Tk interpreter),we built out own customized wishx, that has the new command we need.

This approach integrated the simplicity of Tcl/Tk and the flexibility of C, it also made our program easy to port to different platform or add extension to it. Tcl script is platform independent and Profile keeping is written in ANSI C. The only thing that is needed to change according to different platform is CM reader, this is inevitable, because on different, there are different kind of calendar program, and they store their records in different format. But as you will see later (Interface between modules), the CM reader is a one-entry, one exit, self-contained module. So it is very easy to write a extension to ITM so that it can work on different platforms

High Level Architecture

ITM can be invoked in two modes, active mode and passive mode. As we mentioned before, user can start ITM to maintain call groups, which makes ITM in active mode. ITM can also be invoked by telephony server when a call comes in and user is not around. ITM will be in passive mode with this start up. No user interface will come up, all ITM need to do in this mode is to find the action, message and forward address user set for this time period and return the action code and action content to the telephony server.

ITM consists of three modules: Main, Group Maintenance, and CM reader. The high level architecture is shown as Fig.1-1.

Fig 1-1. ITM high level architecture

The function of each module is listed as following:

Main module is the interface to telephony server (in passive mode) and to user (in active mode). when invoked by telephony server, Main will call CM reader first to search for the action, message and forward address user entered in CM file. If the search is unsuccessful or the group flag is set on, Main will activate Group Maintenance module to search the group files. If either of the searches is successful, Main will return action code and action content to telephony server; otherwise, the call will be rejected with very general content (e.g. "Sorry, I am not available"). When invoked by user, Main will create a graphic user interface to allow user maintain call group files. It will call the functions in Group Maintenance module as required (see module functionality).

Group Maintenance module maintains two call group files. In active mode, it allows user to modify call list, searches a caller by name, moves a caller between groups, sets preference for each group. In passive mode, it checks the caller address in group files and returns the group preference if the address is found in a group.

CM reader module deals with Calendar Manager interface, accepts the incoming caller address and matches the current Calendar Manager appointments, then retrieves the appropriate information.

Functions of Modules

Interface Specification:

Main moduleTelephony Server:

Telephony server input:   caller-address ?subject?
Main module output:       action  reason
                                     action = REJECT |FORWARD
                                     reason may be forward address  or reject reason.

Main moduleGroup Maintenance module:

Module Implementation:

Main module:
It is the main control module, responsible for communication between the other 2 modules. It is also the interface to telephony server and users. Another major function of this module is to set up the user interface. The follow chart of Main is shown as Fig 2-1, Fig 2-3 show the window hierarchy of the program.

Group Maintenance module :

Group Maintenance module maintains a data structure holds default information and callers in each groups.

typedef struct {                     /* caller */
        int      seq;                /* caller seq # as shown on screen (0 based) */ 
        char     name[15];           /* name */ 
        char     address[20];        /* address */ 
        int      group;              /* level group # (1 or 2) */ 
} caller_t;

typedef struct {                     /* data buffer*/ 
        int     grp1_num;           /* number of callers in group1 */ 
        char 	grp1_act[8];            /* group 1 default action */ 
        char 	grp1_msg[30];           /* group 1 default message */ 
        char 	grp1_adr[30];           /* group 1 default address*/ 
        caller_t grp1[MAXCALLER];    /* group 1 caller list */ 
        int 	grp2_num;                /* number of callers in group 2 */ 
        char 	grp2_act[8];            /* group 2 default action */ 
        char 	grp2_msg[30];           /* group 2 default message */ 
        char 	grp2_adr[30];           /* group 2 default address */ 
        caller_t grp2[MAXCALLER];    /* group 2 caller list */ 
} data_t;

Initial(): This function gets called when ITM starts. It allocates memory for a big data structure Data, which consists of number of callers, default action, default message, default forward address and list of callers for each group. Then loads data_t Data with group files. All other functions will operate on structure Data.

ShutDown(): This function gets called when ITM ends. It writes Data to group files and closes the application.

ModifyCallerList(group#, index, mode, name, address): This function gets called every time user wants to modify a caller list. There are three possible modes: 1=add, 2=change, 3=delete. In add mode, it inserts a caller in group# list according to name order. In change mode, it changes a caller with index in group# and resort the list if name is changed. In delete mode, it deletes a caller with index in group# and shift all the following callers up one position. The caller list is always sorted in name ordered. The function returns TCL_ERROR and error message ("Name already exists!") if duplicate name is entered.

GetUserListItem(index, group#): This function returns a caller entity with index in the group# caller list. A caller entity consists of caller sequence number, caller name, caller address and caller group number.

GetUserListNum(group#): This function returns the number of callers in the group# caller list.

SearchByName(name, group#): This function searches a caller by comparing pass in name with each caller name in group# caller list. The match method is case sensitive. If the search is successful, It returns the caller sequence number, caller name and caller address; otherwise, TCL_ERROR is returned.

ChangeGroup(fromgroup#, togroup#, index): This function moves a caller with index from fromgroup# caller list to togroup# caller list. It returns TCL_ERROR and error message ("Name already exists!") if the name of moved in caller already exists in the togroup# caller list.

GetDefault(): This function returns the default action, message, forward address for both groups

PutDefault(action1, message1, address1, action2, message2, address2): This function sets the default action, message, forward address for each group with the corresponding pass in parameters.

CheckAddress(address, group#): This function gets called when ITM is in passive mode. It searches a pass in address in group# caller list or both groups if group# is 0. The match method is case sensitive. The pass in address is used for search first. If no match is found, a widecard address based on the pass in address will be used for search. It assumes that user enters either a specific address (e.g. or a widecard address for all callers from one host (e.g. * in caller group list. If the search is successful, it returns the default action code and action content for the group in which the address is found; otherwise, TCL_ERROR is returned.

CM Reader module

CM reader module is written in C language, compiled in Sun Solaris Unix System.

CM reader module accepts the incoming caller address(email address) and user-ID as input, which is passed from Main module call. Then checks whether there are some matches in the current calendar CM file for this address. Finally, returns a structure, which include the necessary calendar information, to Main module. The figure 2-3 shows the architecture of CM reader Module.

For the purpose of implement the above functionality, we make the following rules:

1.Input address. Because the caller can give any arbitrary address, but in our program, we only deal with this current common email address like: input address is any other arbitrary character string without @, we will treat it as error input.

2.We use UNIX x-window’s calendar manager(CM) as calendar information interface. Also we follow the complex syntax mentioned before, for example:

-m I am in meeting
-c,* -a reject-partial
-c bclinton@whitehouse.gvn,group1 -a reject-detail

Here "-m " gives the detail message "I am in meeting", "-f " gives the forward address "", "-c " specifies the caller list, which can be one of any case of exact email address, wildcard address, group1, group2. ",  *,  group1,bclinto@whitehouse.gvn". "-a " defines the action corresponding to the caller list before it, which can be reject-partial, reject-detail, reject-none, forward.

In this example, for caller list ", * " the action code is "reject-partial", whereas for caller list "bclinton@whitehouse.gvn, group1" the action code is " reject-detail".

The actual implementation of actions corresponding to the incoming call is done by the Main module. CM reader has only responsibility to check incoming caller address and retrieve the   appropriate information then return to the Main module.

The details of implementation of CM reader module:

1. Calendar Manager file.  This file resides in:          usr/spool/calendar/callog.$USER

It contains all the information inputted by user from Calendar Manager interface.        $USER is user ID to login the UNIX system, which is passed from main module. CM  reader retrieves all information and return to Main module.

Since cm file is organized as appending fashion according the time, (eg. the new input appointment was appended by the end of the old file) so if there is any "removing" or "changing" operation on the appointment, you can only know by reading all cm file. Thus CM reader module maintain an array of structure with two fields. The first one is a character string store the one appointment information created by Calendar Manager, the second one is a integer flag which records the state associated with the appointment ( flag = 0 means the appointment is available, and flag = 1 means the appointment is removed).

2. CM reader matches the incoming caller address with cm file "-c" fields in this order:    exact email address, wildcard email address, group1, group2.  Whenever matching   operation is successfully completed, CM reader returns necessary information to Main module and stop. If there is no match, return no match information to main module.

3. CM reader returns a structure like:

struct {
char message[1000];                     //the detail message of appointment such as " I am in meeting "
char address[30];                          // forward address specified in the "-f " field
char action[30];                            // action specified in the "-a " field
char time[2][30];                          // time[0] and time[1] give the start and end time of the appointment respectly
int  flag;                                            // macth status

Here flag=0, specifies no match or there is no appointment now.
        flag=1, specifies the is a match with exact email address or wildcard address,
        flag=2, means in "-c " field there is "group1" item.
        flag=3, means in "-c " field there is "gropp2" item.

4. CM reader composes by two functions, ConvTime and CMReader
ConvTime implement time conversion. Since we need compute the appointment start and end time from cm file, then return the readable time format for the caller if necessary.
CMReader implement the matching incoming address and retrieving the information from cm file.

5. Finally as the main module is written in Tcl language, CM reader module have to deal with the compatibility with main module. Thus the final version of CM reader module is in Tcl function.

User's Manual

Task List

Mr. Ruigang Yang is the coordinator of this project. He did:

Mr. Yuwen Tu did:

Miss. Caomei Long did:

The syntax in the CM file was initially defined by the 3 group members, the final version of the syntax was defined by Miss Caomei Long. The remaining part of the report is written by its corresponding programmers.


Prof. Henning G. Schulzrinne  gave us the basic idea of the telephony manager. Mr. Tobias H. Hoellere ( a Ph.D. student of Prof. Steve Feiner ) gave great help in building the tcl interpreter. Mr. Stefan Hoffmann provided userful infomation about the telephony server. We here present our gratitude for their kind help.

Last modified on Dec 3rd, 1996