ch26.htm

MAPI__SAPI__TAPI

      <a HREF="ch23.htm"><p>Chapter 23</a>, &quot;TAPI Architecture,&quot; describes the <tt><font
      FACE="Courier">TAPILINE</font></tt> messages, their parameters, and their use. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="TheTAPILINEOCXProperties">The <tt><font SIZE="4" FACE="Courier">TAPILINE.OCX</font></tt><font
SIZE="4"> Properties</font></a></h3>

<p>The <tt><font FACE="Courier">TAPILINE.OCX</font></tt> has 12 unique, TAPI-related 
properties. <tt><font FACE="Courier">TAPILINE</font></tt> uses these properties to keep 
track of important handles, ID values, and other settings. You can read or write these 
values using standard Visual Basic code or manipulate them at design time through the 
Properties window of Visual Basic. Table 26.2 shows the 12 TAPI-related properties along 
with short descriptions.<br>
</p>

<p align="center"><b>Table 26.2. The <tt><font FACE="Courier">TAPILINE.OCX</font></tt> 
properties.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Property</i></td>
    <td WIDTH="385"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">AddressID</font></tt> </td>
    <td WIDTH="385">This is a value from 0 to the maximum number of addresses available on a 
    line device. Use this value to identify multiple addresses for the same line 
    (multiple-line phones only). </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">APIVersion</font></tt> </td>
    <td WIDTH="385">This is the value of the TAPI API version currently in use. This is set by 
    TAPI. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">CompletionID</font></tt> </td>
    <td WIDTH="385">This is a unique value set by TAPI to identify a call that is in progress. 
    Used in multiline systems that allow call camp and other advanced features. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">GatheredDigits</font></tt> </td>
    <td WIDTH="385">This is a string of digits pressed by the user. This is the results of the 
    <tt><font FACE="Courier">lineGatherDigits</font></tt> function. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">HandleToCall</font></tt> </td>
    <td WIDTH="385">This is the unique handle of the current call. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">HandleToConfCall</font></tt> </td>
    <td WIDTH="385">This is the unique handle of a conference call in progress. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">HandleToConsultCall</font></tt> </td>
    <td WIDTH="385">This is the unique handle of a call transfer that is in progress. This is 
    used by several Supplemental TAPI functions. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">LineApp</font></tt> </td>
    <td WIDTH="385">This is the unique ID of this session between Visual Basic and TAPI. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">LineHandle</font></tt> </td>
    <td WIDTH="385">This is the unique ID of the line that has been opened for use. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">NumberOfRings</font></tt> </td>
    <td WIDTH="385">This is the maximum number of rings to allow for an outbound call. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">NumDevices</font></tt> </td>
    <td WIDTH="385">This is the total number of devices TAPI recognizes on the workstation. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">PermanentProviderID</font></tt> </td>
    <td WIDTH="385">This is the unique ID of the TAPI service provider that is being used to 
    complete the TAPI service request. </td>
  </tr>
  <tr>
    <td WIDTH="205"><tt><font FACE="Courier">Priority</font></tt> </td>
    <td WIDTH="385">This is the priority value used to complete the last TAPI service request. 
    </td>
  </tr>
</table>
</center></div>

<p>Most of these values are set at run-time by TAPI. You can read them to get status 
information about the state of a TAPI service request. As you will see in the example 
project built later in this chapter, there are a few properties here which you can 
manipulate safely during run-time. However, most should be treated as read-only 
properties. </p>

<h3><a NAME="TheTAPILINEOCXMethods">The <tt><font SIZE="4" FACE="Courier">TAPILINE.OCX</font></tt><font
SIZE="4"> Methods</font></a></h3>

<p>The <tt><font FACE="Courier">TAPILINE.OCX</font></tt> has numerous methods that can be 
used to make TAPI service requests. In fact, all of the TAPI line functions have been 
recreated as methods for the <tt><font FACE="Courier">TAPILINE.OCX</font></tt> control. 
Instead of listing all the methods here, you can use the <tt><font FACE="Courier">TAPILINE.HLP</font></tt> 
file that ships with the <tt><font FACE="Courier">TAPILINE.OCX</font></tt> control. This 
file contains detailed information on each of the methods. To use the help file as a 
reference, click the <tt><font FACE="Courier">TAPILINE.HLP</font></tt> file and then press 
the <tt><font FACE="Courier">Help Topics</font></tt> button to bring up the search dialog 
box. You can browse the search list or type in search strings to locate the desired 
function. Figure 26.3 shows you how the help file looks when it is first loaded. </p>

<p><a HREF="f26-3.gif"><b>Figure 26.3 : </b><i>Loading the TAPILINE help file </i></a></p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Tip</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>You can also refer to <a HREF="ch23.htm">Chapter 23</a>, &quot;TAPI Architecture,&quot; 
      to get a complete list of all <tt><font FACE="Courier">TAPILINE</font></tt> functions, 
      including short descriptions. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="TheTAPILINEDLLFunctions">The <tt><font SIZE="4" FACE="Courier">TAPILINE</font></tt><font
SIZE="4"> DLL Functions</font></a></h3>

<p>The TAPI system makes extensive use of data structures. In fact, several of the 
structures are variable in length. These are difficult to pass between Visual Basic and 
Windows DLLs or OCX controls. In order to simplify the process, the <tt><font
FACE="Courier">TAPILINE</font></tt> control comes with a helper DLL called <tt><font
FACE="Courier">PSTAPIDLL32</font></tt>. This DLL contains 17 functions that are used to 
pass data structures. Listing 26.3 shows a sample of the API declarations used to link 
these helper functions to your Visual Basic programs. </p>

<hr>

<blockquote>
  <b><p>Listing 26.3. Declaring the DLL helper functions for <tt><font FACE="Courier">TAPILINE</font></tt>. 
  <br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Declare Sub LineMonitorToneFunc Lib &quot;pstapidll32&quot; 
  (ByVal nMode As Long, structdata <font FACE="ZAPFDINGBATS">&Acirc;</font>As 
  LINEMONITORTONE)<br>
  Declare Sub LineTranslateOutputFunc Lib &quot;pstapidll32&quot; (ByVal nMode As Long, <font
  FACE="ZAPFDINGBATS">&Acirc;</font>structdata As LINETRANSLATEOUTPUT, ByVal ExtraData As 
  String)</font></tt> </p>
</blockquote>

<hr>

<p>Each call has at least two parameters and several of them have three. The first 
parameter (<tt><font FACE="Courier">nMode</font></tt>) is used to indicate whether you are 
attempting to read (1) or write (0) TAPI data. The second parameter is a pre-defined data 
structure that contains the TAPI-related information. You will have other <tt><font
FACE="Courier">Type...End Type</font></tt> statements in your Visual Basic program that 
match these data structures. </p>

<p>Some of the DLL calls have a third parameter called <tt><font FACE="Courier">sExtraData</font></tt>. 
This parameter contains string information that will be used to augment the structured 
data sent in the same call. This is how the <tt><font FACE="Courier">TAPILINE</font></tt> 
control passes variable-length structures between Visual Basic and the TAPI system. </p>

<p>You'll see all 17 of the helper DLL calls in the next section of the chapter when you 
build the <tt><font FACE="Courier">TAPILine Test</font></tt> application. </p>

<h2><a NAME="TheTAPILINETestProject"><font SIZE="5" COLOR="#FF0000">The </font><tt><font
SIZE="5" COLOR="#FF0000" FACE="Courier">TAPILINE Test</font></tt><font SIZE="5"
COLOR="#FF0000"> Project</font></a> </h2>

<p>The <tt><font FACE="Courier">TAPILINE Test</font></tt> project will show you how to 
build TAPI applications using Visual Basic 4.0. You'll see how to use the <tt><font
FACE="Courier">TAPILINE</font></tt> control and the <tt><font FACE="Courier">PSTAPIDLL32</font></tt> 
dynamic link library to perform TAPI service requests. You'll see how these two added 
resources (along with a bit of Visual Basic code) can give you extensive access to the 
TAPI services built into every Win95 and WinNT machine. </p>

<p>Before you can begin running TAPI applications from Visual Basic, you need a few 
support modules that contain DLL declarations, structured data types, global constants, 
and several internal help routines to decipher the messages returned by TAPI. </p>

<p>Once you have the DLL declarations, the line constants and structures, and the helper 
functions, you are ready to lay out the <tt><font FACE="Courier">TAPILINE</font></tt> <tt><font
FACE="Courier">Test</font></tt> form and place code behind several buttons to see how TAPI 
services work from within Visual Basic programs. </p>

<p>Creating the support code of declarations, data structures, and constants is a big (and 
tedious) job. Instead of asking you to type all the code yourself, a set of support 
modules is included on the CD-ROM that accompanies this book. You can find the code 
support routines in the <tt><font FACE="Courier">TAPILINE\VBTAPI</font></tt> folder on the 
CD-ROM. Table 26.3 lists the Visual Basic support modules along with short descriptions of 
their uses.<br>
</p>

<p align="center"><b>Table 26.3. The <tt><font FACE="Courier">TAPILINE</font></tt> support 
modules for Visual Basic.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Module Name</i></td>
    <td WIDTH="452"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">TAPILINE.BAS</font></tt> </td>
    <td WIDTH="452">All the DLL declarations, line constants, and line data structures needed 
    for creating TAPI applications that use line devices. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">TAPIPHON.BAS</font></tt> </td>
    <td WIDTH="452">All the constants and data structures needed to handle phone devices. </td>
  </tr>
  <tr>
    <td WIDTH="138"><tt><font FACE="Courier">TAPICALL.BAS</font></tt> </td>
    <td WIDTH="452">A set of helper functions that handle TAPI callback messages and other 
    routines </td>
  </tr>
</table>
</center></div><div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>The <tt><font FACE="Courier">TAPILINE.OCX</font></tt> can only handle line devices. The 
      <tt><font FACE="Courier">TAPIPHON.BAS</font></tt> module is included to help you if you 
      wish to develop additional OCX or DLL code to support phone device programming from Visual 
      Basic. It is possible that <tt><font FACE="Courier">TAPILINE</font></tt> will support 
      phone device programming in the future. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>Copy the modules listed in Table 26.3 onto your own hard disk and use them whenever you 
use the <tt><font FACE="Courier">TAPILINE.OCX</font></tt> file. The next section of the 
chapter reviews the modules listed to help you understand what is in them and to give you 
a good idea of how they work. </p>

<h3><a NAME="TheDLLDeclarationsandGeneralTAPICo">The DLL Declarations and General TAPI 
Constants</a></h3>

<p>The first code in the <tt><font FACE="Courier">TAPILINE.BAS</font></tt> module is the 
set of DLL declarations needed to call the <tt><font FACE="Courier">TAPILINE</font></tt> 
helper functions for passing structured data. Listing 26.4 shows the code that handles the 
DLL declarations. </p>

<hr>

<blockquote>
  <b><p>Listing 26.4. <tt><font FACE="Courier">PSTAPIDLL32</font></tt> DLL declarations.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>'<br>
  ' DLL declares for TAPILine control<br>
  '<br>
  Declare Sub LineCallParamsFunc Lib &quot;pstapidll32&quot; (ByVal nMode As Long, 
  structdata <font FACE="ZAPFDINGBATS">&Acirc;</font>As LINECALLPARAMS, ByVal ExtraData As 
  String)<br>
  Declare Sub LineForwardListFunc Lib &quot;pstapidll32&quot; (ByVal nMode As Long, 
  structdata <font FACE="ZAPFDINGBATS">&Acirc;</font>As LINEFORWARDLIST, ByVal ExtraData As 
  String)<br>
  Declare Sub LineGenerateToneFunc Lib &quot;pstapidll32&quot; (ByVal nMode As Long, 
  structdata <font FACE="ZAPFDINGBATS">&Acirc;</font>As LINEGENERATETONE_TYPE, ByVal 
  ExtraData As String)<br>
  Declare Sub LineAddressCapsFunc Lib &quot;pstapidll32&quot; (ByVal nMode As Long,