📄 ch24.htm
字号:
<html>
<head>
<title>Chapter 24 -- TAPI Basics</title>
<meta NAME="GENERATOR" CONTENT="Microsoft FrontPage 3.0">
</head>
<body TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000EE" VLINK="#551A8B" ALINK="#CE2910">
<!-- Spidersoft WebZIP Ad Banner Insert -->
<!-- End of Spidersoft WebZIP Ad Banner Insert-->
<h1><font COLOR="#FF0000">Chapter 24</font></h1>
<h1><b><font SIZE="5" COLOR="#FF0000">TAPI Basics</font></b> </h1>
<hr WIDTH="100%">
<h3 ALIGN="CENTER"><font SIZE="+2" COLOR="#000000">CONTENTS<a NAME="CONTENTS"></a> </font></h3>
<ul>
<li><a HREF="#UsingTAPItoPlaceOutboundCalls">Using TAPI to Place Outbound Calls</a> <ul>
<li><a HREF="#CallinglineInitializetoStarttheTAPI">Calling lineInitialize to Start the TAPI
Session</a> </li>
<li><a HREF="#CallinglineNegotiateAPIVersiontoCheck">Calling lineNegotiateAPIVersion to
Check TAPI Services</a> </li>
<li><a HREF="#UsinglineOpentoLocateanAppropriate">Using lineOpen to Locate an Appropriate
TAPI Line Device</a> </li>
<li><a HREF="#SettingCallParameterswiththeLINECAL">Setting Call Parameters with the
LINECALLPARAMS Structure</a> </li>
<li><a HREF="#UsinglineMakeCalltoPlacetheCall">Using lineMakeCall to Place the Call</a> </li>
</ul>
</li>
<li><a HREF="#TheTAPIOutProject">The TAPIOut Project</a> <ul>
<li><a HREF="#TheInitialDeclarations">The Initial Declarations</a> </li>
<li><a HREF="#TheUserDialogBoxandtheWinMainProc">The User Dialog Box and the WinMain
Procedure</a> </li>
<li><a HREF="#ThePlaceCallFunction">The PlaceCall Function</a> </li>
<li><a HREF="#TheShowProgressandSetVarPropsProcedu">The ShowProgress and SetVarProps
Procedures</a> </li>
<li><a HREF="#ThelineCallBackProcProcedure">The lineCallBackProc Procedure</a> </li>
</ul>
</li>
<li><a HREF="#TestingtheTAPIOutProject">Testing the TAPIOut Project</a> </li>
<li><a HREF="#Summary">Summary</a> </li>
</ul>
<hr>
<p><font COLOR="#000000">In this chapter, you'll learn how to build a simple TAPI dialer
application in C using the Basic Telephony level of service. This application will be used
to highlight the basic operations required to build TAPI applications (in any language).</font>
</p>
<p>You'll learn how to perform line initialization, locate a usable outbound line, and
open it in preparation for dialing. You'll also learn how to place an outbound call and
use the TAPI line callback function to monitor call progress. Finally, you'll learn how to
safely close down a line after the call has been completed. </p>
<p>When you are done with the example in this chapter, you'll understand the basics of
writing TAPI applications and know how to use Basic Telephony services in your own
applications. </p>
<div align="center"><center>
<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
<tr>
<td><b>Note</b></td>
</tr>
<tr>
<td><blockquote>
<p>The project in this chapter was written using the Microsoft Visual C++ 4.1 compiler.
However, the code is compatible with the Microsoft VC 2.0 compiler. If you do not have a C
compiler, you can still get a lot out of the chapter. The same techniques covered here
will be used when you build TAPI applications in Microsoft Visual Basic 4.0 later in this
section of the book.</p>
</blockquote>
</td>
</tr>
</table>
</center></div>
<h2><a NAME="UsingTAPItoPlaceOutboundCalls"><font SIZE="5" COLOR="#FF0000">Using TAPI to
Place Outbound Calls</font></a></h2>
<p>Before starting the review of the <tt><font FACE="Courier">TAPIOUT</font></tt> project,
it is a good idea to cover the minimal steps needed to place an outbound call using TAPI
services. There are really only a few steps:
<ul>
<li><font COLOR="#000000">Call </font><tt><font FACE="Courier">lineInitialize</font></tt> to
start the TAPI session. </li>
<li><font COLOR="#000000">Call </font><tt><font FACE="Courier">lineNegotiateAPIVersion</font></tt>
to make sure you can use the installed TAPI services. </li>
<li><font COLOR="#000000">Call </font><tt><font FACE="Courier">lineOpen</font></tt> to get a
line that is appropriate for your needs (data, fax, voice, and so on). </li>
<li><font COLOR="#000000">Use the </font><tt><font FACE="Courier">LINECALLPARAMS</font></tt>
structure to set up calling parameters before you place your call. </li>
<li><font COLOR="#000000">Call </font><tt><font FACE="Courier">lineMakeCall</font></tt> to
actually attempt to place a TAPI call. </li>
</ul>
<p>After you complete these steps, you can use the messages received by the registered
callback function to track call progress and respond accordingly. The next few sections
cover the outbound calling steps in greater detail. </p>
<h3><a NAME="CallinglineInitializetoStarttheTAPI">Calling <tt><font SIZE="4"
FACE="Courier">lineInitialize</font></tt><font SIZE="4"> to Start the TAPI Session</font></a></h3>
<p>The first thing you need to do to start a TAPI session is to call the <tt><font
FACE="Courier">lineInitialize</font></tt> routine to initialize the link between your
application and the TAPI service provider. The <tt><font FACE="Courier">lineInitialize</font></tt>
routine includes a pointer to the callback function in your code that will handle all
messages. </p>
<p>After successful initialization, the routine returns a value in the <tt><font
FACE="Courier">lineHandle</font></tt> parameter. You'll use this value throughout your
TAPI session. You will also get a count of the total number of TAPI lines defined for this
workstation. You'll use that information to check the API version and line parameters of
each line before you attempt to place a call. </p>
<p>If an error occurs, a non-zero value is returned. You can check the errors using a case
switch and present a message to the user. </p>
<h3><a NAME="CallinglineNegotiateAPIVersiontoCheck">Calling <tt><font SIZE="4"
FACE="Courier">lineNegotiateAPIVersion</font></tt><font SIZE="4"> to Check TAPI Services</font></a></h3>
<p>After you successfully open the TAPI session, you need to call the <tt><font
FACE="Courier">lineNegotiateAPIVersion</font></tt> function for each line in the
collection. The total number of lines was returned as part of the <tt><font FACE="Courier">lineInitialize</font></tt>
routine. You need to check this value because it is possible that you will be requesting a
version of TAPI this is not available for this machine. </p>
<p>You pass your API version request to the function and get a value back that is the
version of TAPI that the workstation can provide to your application. You can also get a
pointer to a structure that holds information about vendor-specific extension services
available on this workstation. This is a method for allowing non-TAPI services to be
recognized using the TAPI interface. </p>
<h3><a NAME="UsinglineOpentoLocateanAppropriate">Using <tt><font SIZE="4" FACE="Courier">lineOpen</font></tt><font
SIZE="4"> to Locate an Appropriate TAPI Line Device</font></a></h3>
<p>Once you have successfully negotiated an API version, you must use the <tt><font
FACE="Courier">lineOpen</font></tt> function to pass through each line and request the
appropriate level of service. For example, if you wanted to place an interactive voice
call, you'd use the <tt><font FACE="Courier">lineOpen</font></tt> function to locate a
line that supports interactive voice. </p>
<p>This is an important point. It is quite possible that the workstation will have several
TAPI devices defined, but only one may provide the type of service you need (voice, fax,
data, and so on). If there is no device available (none exists or the current one is
busy), you'll get an error message. However, if an appropriate line is available, you'll
receive a zero as a return code and a value indicating the handle of the open line. You'll
use this value in subsequent TAPI calls. </p>
<h3><a NAME="SettingCallParameterswiththeLINECAL">Setting Call Parameters with the <tt><font
SIZE="4" FACE="Courier">LINECALLPARAMS</font></tt><font SIZE="4"> Structure</font></a></h3>
<p>Once you locate an appropriate line, you can set calling parameters using the <tt><font
FACE="Courier">LINECALLPARAMS</font></tt> structure. You use this structure to tell TAPI
the speed and media type (data, voice, and so on) of your call and other values. </p>
<p>Setting the <tt><font FACE="Courier">LINECALLPARAMS</font></tt> structure is optional.
If you do not set any value for the <tt><font FACE="Courier">LINECALLPARAMS</font></tt>,
Microsoft TAPI will use default values. For most calls, the default values will work just
fine. </p>
<h3><a NAME="UsinglineMakeCalltoPlacetheCall">Using <tt><font SIZE="4" FACE="Courier">lineMakeCall</font></tt><font
SIZE="4"> to Place the Call</font></a></h3>
<p>The last step in the process is actually placing the call using the <tt><font
FACE="Courier">lineMakeCall</font></tt> function. This function passes the string that
contains the phone number to call, a handle for the open line (you got that from <tt><font
FACE="Courier">lineOpen</font></tt>) and, optionally, a pointer to the <tt><font
FACE="Courier">LINECALLPARAMS</font></tt> structure. </p>
<p>If the call is placed successfully, a call handle is returned. You'll use this call
handle in subsequent TAPI functions. If there is trouble making the call, the return code
is non-zero and can be checked for appropriate action. </p>
<p>It is important to note that at this point the call has been <i>placed</i> but not
completed. All TAPI knows for sure is that digits have been dialed and the phone line is
active. TAPI will continue to receive status information and route that to your
application through the callback function registered when you called <tt><font
FACE="Courier">lineInitialize</font></tt>. The quality of the status information (dialing,
ringing, busy, idle, and so on) is all determined by the hardware vendor and TAPI service
provider application. The more sophisticated the hardware, the more accurate the progress
information. </p>
<p>For example, standard data/fax modems do not report call progress information. When you
place your TAPI call, you'll be notified by the hardware that the call is in progress and
will see nothing else until the call is completed or a time-out occurs. Other hardware
(advanced voice/data modems) may provide additional call-progress data. High-end telephony
cards provide the most accurate information. </p>
<p>Now that you know the basics of placing an outbound call using TAPI, it's time to
review the <tt><font FACE="Courier">TAPIOUT</font></tt> project on the CD-ROM that
accompanies this book. </p>
<h2><a NAME="TheTAPIOutProject"><font SIZE="5" COLOR="#FF0000">The </font><tt><font
SIZE="5" COLOR="#FF0000" FACE="Courier">TAPIOut</font></tt><font SIZE="5" COLOR="#FF0000">
Project</font></a></h2>
<p>The <tt><font FACE="Courier">TAPIOUT</font></tt> project that ships on the CD-ROM is a
C program that allows users to enter a phone number and use TAPI to place an outbound
call. This project is very rudimentary. There are no extra bells and whistles. However,
the code in this project gives a good review of what it takes to provide basic TAPI
services. The next several sections of this chapter review the <tt><font FACE="Courier">TAPIOUT</font></tt>
project step-by-step. You'll see how you can use the TAPI functions described earlier in
the chapter to create a functional TAPI dialer. </p>
<p>If you have a copy of Microsoft VC++ 2.0 or later, start it now and load the <tt><font
FACE="Courier">TAPIOUT.MAK</font></tt> (or <tt><font FACE="Courier">TAPIOUT.MDP</font></tt>)
project from the CD-ROM. You can follow along with the examples in the chapter </p>
<div align="center"><center>
<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
<tr>
<td><b>Tip</b></td>
</tr>
<tr>
<td><blockquote>
<p>You'll need to have the TAPI SDK installed on your machine before you can compile this
project. Once you load the project, be sure to select <tt><font FACE="Courier">Tools |
Update All</font></tt> <tt><font FACE="Courier">Dependencies</font></tt> to resolve
references to the <tt><font FACE="Courier">TAPI.H</font></tt> and <tt><font FACE="Courier">TAPI32.LIB</font></tt>
files in the project. You may need to reload these files into the project using <tt><font
FACE="Courier">Insert | Files into Project...</font></tt> </p>
</blockquote>
</td>
</tr>
</table>
</center></div>
<h3><a NAME="TheInitialDeclarations">The Initial Declarations</a> </h3>
<p>This first step in the process is declaring all the needed includes, defines, function
prototypes, and global variables. Listing 24.1 shows how this looks in the <tt><font
FACE="Courier">TAPIOUT</font></tt> project. </p>
<hr>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -