README.TXT

TAPI 3.0 
INCOMING Sample Application 
 
 
Overview: 
 
INCOMING is a Visual Basic sample TAPI 3.0 application that waits for  
and answers incoming calls: phone calls or H323 audio calls. 
This sample was developed using Visual Basic 5. 
 
In order to receive incoming call notifications, as well as any call 
state event notifications, the application must call RegisterCallTypes 
specifying the media types for which it wants to be notified (therefore 
not all incoming calls will be offered to the app, but only those that 
have the desired media types). This sample registers the first two  
media types, that are expected to be audio in and out. 
 
The application must also declare an Address object "with events", and  
implement for it the event procedure that processes the event  
"CallEventNotification". This is actually the function that will get  
called by Tapi3.dll each time when a new call is offered, and also when  
the call changes its state. 
 
In order for Tapi3.dll to know about this event procedure, the address  
with events must be assigned the value of the real address object  
that corresponds to the address on which calls are to be received. 
This is equivalent with "registering an outgoing interface" from C/C++. 
For more information about declaring and using objects with events, see 
Visual Basic's Books Online. 
 
INCOMING shows how to use an address object with events in order to  
receive incoming calls, and how to answer and eventually disconnect  
the incoming call. 
 
 
How to use: 
 
To run the INCOMING sample application, simply build and run incoming.exe, 
using Visual Basic 5. 
A small dialog box will appear, and the user is supposed to select the  
desired call type and press "Register". After that, the status will be  
"Waiting for a call." 
The 2 possible call types (for this application) are: phone calls and  
H323 calls. In order to succesfully register for receiving phone calls, 
a voice modem must be used. 
 
In the case of phone calls, a phone set is needed to be plugged into  
the modem. Whenever a phone call is received, the application will  
display the "offering" state of the call, and allow the call to be  
answered, and after that the phone set must be used to actually talk  
with the phone from the other end of the call. 
 
In the case of an H323 call, the application counts on the existence  
of a sound card (full duplex). The app selects on the call the  
first 2 media types (that should be "audio in" and "audio out") and  
their default terminals (that should be "speakers" and "microphone"), 
therefore after the call is answered you should be able to use  
the microphone and the speakers currently existing on the computer 
to speak with the person from the other end of the call. Note that  
the other end of the call should be an H323 client too. 
 
 
Limitations: 
 
The way this sample was implemented, in the case of phone calls it  
will allow only "interactive voice" calls, which means that a phone 
set must be plugged into the modem and used for talking, after the  
connection is established. But Tapi 3.0 actually allows also two  
other types of phone calls: "automated voice" calls, and "data" calls. 
In order to support those too, the application should be changed in 
the following way: 
- for "automated voice" calls: "audio in" and "audio out" are the  
media types that must be registered, but instead of using their  
default terminals, the terminals that correspond to the devices  
"speakers" and "microphone" should be used. 
- for "data" calls: "data modem" is the media type that should be  
registered instead of "audio in" and "audio out", in conjunction  
with the "Null" terminal, which anyway corresponds to the default  
terminal. 
 
The "Register" button can be pressed only once. This actually means 
that the application must be restarted in order to change the type  
of calls that the application can listen for.  
 
 
What functionality does this sample show: 
 
The incoming sample application demostrates how to receive new call 
notification and call state event notifications.  It also demonstrates 
the basic TAPI 3.0 functions involved in answering a call. 
 
 
What this sample does not show: 
 
This sample does not let the user choose the TAPI address for the 
application to use (in case there are several addresses that meet the  
same criteria, the sample will always use the first one). It does not  
allow the user to decide what media types to listen for, and it does  
not allow the user to decide what terminals to use: the sample always 
selects the first 2 media types (which are expected to be audio in  
and audio out) and their default terminals. 
 
 
Hints: 
 
In the case of an H323 call: if the sound card installed on the  
computer is not full duplex, the sample should be changed to select  
only 1 media type on the call, instead of 2. 
An H323 address will exist on your computer if H323 provider is  
installed, and if the computer is part of a network: the H323 provider 
uses the machine's IP address to actually implement the "H323 address". 
Control Panel - Telephony applet should be use for adding TSPs 
(telephony service providers). 
 
In case you want to use the sample for receiving phone calls, a voice 
modem should be installed; the data modems will not work with this sample 
because they don't support registering for receving "interactive voice"  
calls (which is the only case illustrated by this sample).