ch27.htm

MAPI__SAPI__TAPI

<p>The entries shown in Listing 27.6 are the required minimum entries for each 
provider-specific section. TSPs can also add other values to their sections if they wish. 
These values could identify individual lines and phones, provide additional configuration 
settings used by the TSP, and so on. Microsoft suggests TSPs establish a system for 
identifying line or phone parameters similar to the one used for identifying providers. 
For example, each line could have an ID and name value along with any special settings. 
Listing 27.7 shows how this might look in the <tt><font FACE="Courier">TELEPHON.INI</font></tt> 
file. </p>

<hr>

<blockquote>
  <b><p>Listing 27.7. Extended provider-specific entries.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>[Provider1]<br>
  NumLines=2<br>
  NumPhones=1<br>
  NextLineID=2<br>
  NextPhoneID=1<br>
  LineID0=1<br>
  LineName1=MCA's Data Line<br>
  LinePort1=COM1<br>
  LineInitString1=ATH0<br>
  LineID1=2<br>
  LineName2=Voice Line<br>
  LinePort2=COM2<br>
  LineInitString2=</font></tt> </p>
</blockquote>

<hr>

<p>Notice the use of the <tt><font FACE="Courier">NextLineID</font></tt> and <tt><font
FACE="Courier">NextPhoneID</font></tt> settings. This will allow the TSP to add future 
lines or phones with unique values. The additional settings here are related to 
communications ports and initialization strings, but they could be anything at all that 
the TSP needs to manage the TAPI service on the line. </p>

<p>The main thing to keep in mind about the provider settings is that they are managed by 
the Telephony service provider application-not the <tt><font FACE="Courier">TAPI.DLL</font></tt> 
or your own desktop applications. All settings that appear here are the result of actions 
by the TSPs. You run the risk of trashing your TAPI installation if you meddle with these 
values! </p>

<h2><a NAME="HandoffPrioritiesInformation"><font SIZE="5" COLOR="#FF0000">Handoff 
Priorities Information</font></a></h2>

<p>When there is more than one TAPI application registered on the workstation, the TAPI 
system must have some process for deciding which service request is handled by which TAPI 
application. The <tt><font FACE="Courier">[HandOffProrities]</font></tt> section of the <tt><font
FACE="Courier">TELEPHON.INI</font></tt> file helps TAPI handle this situation. The <tt><font
FACE="Courier">[HandOffPriorities]</font></tt> section lists all the applications that can 
handle inbound and outbound calls. Also, the applications are listed in preference order. 
The first items on the list should be called before the last items on the list. </p>

<p>Each entry in the <tt><font FACE="Courier">[HandOffPriorities]</font></tt> section 
lists the type of TAPI service request followed by one or more registered programs capable 
of handling the request. Listing 27.8 shows a typical <tt><font FACE="Courier">[HandOffPriorities]</font></tt> 
section from the <tt><font FACE="Courier">TELEPHON.INI</font></tt> file. </p>

<hr>

<blockquote>
  <b><p>Listing 27.8. A typical <tt><font FACE="Courier">[HandOffPriorities]</font></tt> 
  section.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>[HandoffPriorities]<br>
  datamodem=rasapi32.dll,<br>
  interactivevoice=AMENGINE.DLL,MSPHONE.EXE,<br>
  automatedvoice=AMENGINE.DLL,<br>
  RequestMakeCall=C:\PROGRA~1\MICROS~3\MSPHONE.EXE,C:\WINDOWS\DIALER.EXE,</font></tt> </p>
</blockquote>

<hr>

<p>Listing 27.8 shows that the workstation can support four TAPI service request types: 

<ul>
  <li><tt><font FACE="Courier">datamodem</font></tt>-Used for handling data-oriented calls. </li>
  <li><tt><font FACE="Courier">interactivevoice</font></tt>-Used for handling live voice 
    calls. </li>
  <li><tt><font FACE="Courier">automatedvoice</font></tt>-Used for handling recorded voice 
    calls. </li>
  <li><tt><font FACE="Courier">RequestMakeCall</font></tt>-Used for handling assisted TAPI 
    requests from other programs on the workstation. </li>
</ul>

<p>You'll notice that the last entry in the section (<tt><font FACE="Courier">RequestMakeCall</font></tt>) 
shows that there are two different programs on the workstation that can handle the TAPI 
service request. In this case, when a program makes a call to the <tt><font FACE="Courier">RequestMakeCall</font></tt> 
TAPI function, TAPI will attempt to hand the request to the <tt><font FACE="Courier">MSPHONE.EXE</font></tt> 
application first. If that application does not respond (it is busy with another call or 
not working properly), then TAPI will attempt to pass the service request to DIALER.EXE. </p>

<p>The <tt><font FACE="Courier">[HandOffPriorities]</font></tt> section can contain 
several different entries, each corresponding to a media mode recognized by TAPI. Listing 
27.9 shows a prototype of the <tt><font FACE="Courier">[HandOffPriorities]</font></tt> 
section with all the known media modes and a sample extended media mode listed. </p>

<hr>

<blockquote>
  <b><p>Listing 27.9. A prototype <tt><font FACE="Courier">[HandOffPriorities]</font></tt> 
  section.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>[HandoffPriorities]<br>
  RequestMakeCall=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  RequestMediaCall=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  unknown=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  interactivevoice=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  automatedvoice=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  g3fax=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  g4fax=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  datamodem=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  teletex=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  videotex=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  telex=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  mixed=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  tdd=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  adsi=[&lt;appname&gt;[,&lt;appname&gt;]...]<br>
  digitaldata=[&lt;appname&gt;[,&lt;appname&gt;]...]</font></tt> </p>
</blockquote>

<hr>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>TAPI also allows TSPs to define their own media modes and place them in the <tt><font
      FACE="Courier">[HandOffPriorities]</font></tt> section. These settings are important only 
      to those developing TSPs and are not covered in this book. For more on TSPs and extended 
      media modes, you can refer to the Win32 Extensions documentation that ships with Microsoft 
      Visual C++, or versions of the TAPI documentation that appear on the MSDN Professional 
      Level CD-ROMs. </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>Like the provider section, the values in this section are manipulated by the TAPI 
applications that are designed to fulfill TAPI service requests. If you develop an 
application that is designed to process a particular type of media, you can place its name 
in this section. Most of the examples covered in this book are designed to make TAPI 
requests, not respond to them. For this reason, you will not be making any changes to the 
entries in the <tt><font FACE="Courier">[HandOffPriorities]</font></tt> section of the <tt><font
FACE="Courier">TELEPHON.INI</font></tt> file. </p>

<h2><a NAME="DialingLocationInformation"><font SIZE="5" COLOR="#FF0000">Dialing Location 
Information</font></a></h2>

<p>The next important section is the <tt><font FACE="Courier">[Locations]</font></tt> 
section. This section holds information on the current location from which the workstation 
is placing calls. The values here are used to determine how to actually dial the telephone 
numbers provided to TAPI. For example, TAPI will attempt to determine if the telephone 
number can be handled using local dialing rules, long distance rules, or international 
rules. </p>

<p>The TAPI system allows users to define more than one location entry for the 
workstation. This way, users can move their computer to different locations and not have 
to reinstall or reinitialize the TAPI location each time. The best example of this is a 
laptop user who travels to different locations, but still wants to use TAPI services to 
place and receive calls. When the user arrives at a new location, the TAPI system need 
only be informed of the current location (and its dialing rules) and all applications will 
behave as normal, without any changing of phone numbers or dialing rules. </p>

<p>There are three main entries in the <tt><font FACE="Courier">[Locations]</font></tt> 
section of the <tt><font FACE="Courier">TELEPHON.INI</font></tt>: 

<ul>
  <li><tt><font FACE="Courier">Locations</font></tt>-This entry tells TAPI how many locations 
    are defined in the <tt><font FACE="Courier">[Locations]</font></tt> section. </li>
  <li><tt><font FACE="Courier">CurrentLocation</font></tt>-This entry tells TAPI which of the 
    location entries is currently selected. </li>
  <li><tt><font FACE="Courier">Location</font></tt>-This entry contains information about the 
    dialing parameters for the defined location. There is one of these entries for each 
    location defined in the <tt><font FACE="Courier">[Locations]</font></tt> section. </li>
</ul>

<p>Listing 27.10 shows a typical <tt><font FACE="Courier">[Locations]</font></tt> section 
of the <tt><font FACE="Courier">TELEPHON.INI</font></tt> file. </p>

<hr>

<blockquote>
  <b><p>Listing 27.10. A typical <tt><font FACE="Courier">[Locations]</font></tt> section.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>[Locations]<br>
  CurrentLocation=5,3<br>
  Locations=4,6<br>
  Location0=0,&quot;Default 
  Location&quot;,&quot;&quot;,&quot;&quot;,&quot;606&quot;,1,0,0,1,&quot;&quot;,0,&quot;&quot; 
  <br>
  Location1=1,&quot;Office&quot;,&quot;&quot;,&quot;&quot;,&quot;513&quot;,1,0,0,0,&quot;&quot;,0,&quot;&quot; 
  <br>
  Location2=3,&quot;Oak Ridge, 
  TN&quot;,&quot;&quot;,&quot;&quot;,&quot;423&quot;,1,0,0,0,&quot;&quot;,0,&quot;&quot; <br>
  Location3=5,&quot;Sweden 
  Office&quot;,&quot;9&quot;,&quot;8&quot;,&quot;013&quot;,46,1,0,0,&quot;&quot;,0,&quot;&quot;</font></tt> 
  </p>
</blockquote>

<hr>

<p>The first entry in the section (<tt><font FACE="Courier">CurrentLocation</font></tt>) 
tells TAPI that the current location is location index &quot;5&quot;. The second parameter 
tells TAPI apps that they can find location index &quot;5&quot; by looking at the third 
location item in the list. This speeds selection of the record. </p>

<p>The second entry in the section (<tt><font FACE="Courier">Locations</font></tt>) tells 
TAPI how many locations are defined here (4) and what the index value of the next location 
will be (&quot;6&quot;). This is used when adding new locations to the list. </p>

<p>The rest of the entries in the <tt><font FACE="Courier">[Locations]</font></tt> section 
contain information about each defined location for this workstation. Listing 27.11 shows 
the prototype for all location entries in the <tt><font FACE="Courier">TELEPHON.INI</font></tt> 
file. </p>

<hr>

<blockquote>
  <b><p>Listing 27.11. The <tt><font FACE="Courier">Location</font></tt> entry prototype.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>Location&lt;index&gt;=&lt;LocationID&gt;,&quot;&lt;FriendlyName&gt;&quot;,&quot;&lt;LocalPrefix&gt;&quot;,&quot;&lt;LDPrefix&gt;&quot;,&quot;&lt;AreaCode&gt;&quot;,&lt;CountryCode&gt;, 
  <br>
  <font FACE="ZAPFDINGBATS">&Acirc;</font>&lt;PreferredCardID&gt;,&lt;CardHint&gt;,&lt;InsertAreaCode&gt;,&quot;&lt;TollPrefixes&gt;&quot;,&lt;TonePulseDialing&gt;, 
  <br>
  <font FACE="ZAPFDINGBATS">&Acirc;</font>&lt;DisableCallWaiting&gt;</font></tt> </p>
</blockquote>

<hr>

<p>Table 27.2 shows the list of parameters in the location line along with a short 
description of their use and meaning. The parameters are listed in the order in which they 
appear in the <tt><font FACE="Courier">Location</font></tt> entry.<br>
</p>

<p align="center"><b>Table 27.2. The <tt><font FACE="Courier">Location</font></tt> entry 
parameters.</b> </p>
<div align="center"><center>

<table BORDER="1" WIDTH="80%">
  <tr>
    <td WIDTH="199"><i>Parameter</i></td>
    <td WIDTH="391"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;LocationID&gt;</font></tt> </td>
    <td WIDTH="391">This is the unique ID value for this location. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;FriendlyName&gt;</font></tt> </td>
    <td WIDTH="391">This is the easy-to-read name for this location (such as &quot;Cincinnati, 
    OH&quot; or &quot;My Home Office&quot;). </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;LocalPrefix&gt;</font></tt> </td>
    <td WIDTH="391">This is the digit(s) that must be dialed in order to place a local call 
    from the location. This can be used in offices where users must dial &quot;9&quot; to 
    reach an outside line, and so on. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;LdPrefix&gt;</font></tt> </td>
    <td WIDTH="391">This is the digit(s) that must be dialed in order to place a long distance 
    call from the location. This can be used in offices that must gain direct access to long 
    distance lines before placing a call. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;AreaCode&gt;</font></tt> </td>
    <td WIDTH="391">This is the area or city code for the location. This is compared against 
    the requested outbound number to see if long distance must be used to complete the call. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;CountryCode&gt;</font></tt> </td>
    <td WIDTH="391">This is the country code for the current location. This is used to 
    determine whether international dialing rules must be employed to complete the requested 
    outbound call. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;PreferredCardID&gt;</font></tt> </td>
    <td WIDTH="391">This is the calling card that should be used to complete the long distance 
    call. </td>
  </tr>
  <tr>
    <td WIDTH="199"><tt><font FACE="Courier">&lt;CardHint&gt;</font></tt> </td>
    <td WIDTH="391">This is the direct index value of the calling card indicated in the <tt><font
    FACE="Courier">&lt;PreferredCardID&gt;</font></tt> entry. This speeds the collection of