ch23.htm

MAPI__SAPI__TAPI

    <tt><font FACE="Courier">dwParam1 = dwAppSpecific</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = 0</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = 0</font></tt>; </td>
    <td WIDTH="193">Sent when a tone is detected. The sending of this message is controlled 
    with the <tt><font FACE="Courier">lineMonitorTones </font></tt>function. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE</font></tt>_<tt><font FACE="Courier">REPLY</font></tt> 
    </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = 0</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = idRequest</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = Status</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = 0</font></tt>; </td>
    <td WIDTH="193">Sent to report the results of function calls that completed 
    asynchronously. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE</font></tt>_<tt><font FACE="Courier">REQUEST</font></tt> 
    </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = 0</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hRegistration</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = RequestMode</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 =<br>
    RequestModeDetail1</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 =<br>
    RequestModeDetail2</font></tt>; </td>
    <td WIDTH="193">Sent to report the arrival of a new request from another application. </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>Additional information about the TAPI line messages can be found in the Win32 
      documentation that ships with Microsoft Visual C++ and in the TAPI documentation that 
      ships with the MSDN Professional Level CD-ROM pack.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h2><a NAME="SupplementalTelephonyServices"><font SIZE="5" COLOR="#FF0000">Supplemental 
Telephony Services</font></a></h2>

<p>The Supplemental Telephony functions provide advanced line device handling (conference, 
park, hold, forward, and so on). Access to these advanced services is dependent on the 
type of telephone line to which the workstation is connected. In other words, even if you 
implement call forwarding functions within your TAPI application, these functions will 
only work if call forwarding services are available on the telephone line provided by the 
local telephone company. </p>

<p>The Supplemental Telephony functions also allow programmers to handle service requests 
for multiple-line phones. You can use Supplemental Telephony to mange a physical handset 
that has access to multiple physical lines (see Figure 23.2). </p>

<p><a HREF="f23-2.gif"><b>Figure 23.2 :</b> <i>Using Supplemental TAPI to manage a single 
handset linked to multiple physical lines</i></a>. </p>

<p>You can also use the Supplemental Telephony functions to manage multiple handsets using 
one or more physical lines. Because TAPI &quot;virtualizes&quot; both line and phone 
devices, there need not be a direct one-to-one correspondence between a defined phone 
device and a defined line device. In this way you can use TAPI to create a switchboard 
application to manage telephony services (see Figure 23.3). </p>

<p><a HREF="f23-3.gif"><b>Figure 23.3 : </b><i>Using Supplemental TAPI to provide 
switchboard services </i></a></p>

<p>Supplemental Telephony also provides access to defining and manipulating phone devices. 
To TAPI a phone device is any device that can accept or place calls. In effect, you can 
register your workstation as a phone device. Then you can use resources on your 
workstation to place or accept calls without the need of a handset or desktop phone. Of 
course, in order to act successfully as a phone device, your workstation must have audio 
input and output hardware. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>You'll learn more about telephony hardware under the TAPI model in <a HREF="ch25.htm">Chapter 
      25</a>, &quot;TAPI Hardware Considerations.&quot; </p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="SupplementalTelephonyAPIforLineDevi">Supplemental Telephony API for Line 
Devices</a></h3>

<p>The Supplemental API set for line devices adds advanced call control and other features 
to the API library. The set can be divided into the following related groups of functions: 

<ul>
  <li><i>Digit and tone handling functions</i> allow programmers to detect and generate digits 
    or tones along the phone line. This capability is needed to allow some systems to perform 
    advanced line operations such as forwarding, call holds, and so on. </li>
  <li><i>Advanced line-handling functions</i> provide call acceptance, rejection, redirection, 
    and other operations. These are most useful in an environment where the phone line is 
    connected to a central switch instead of directly to the external telephone service 
    provider. </li>
  <li><i>Advanced call features functions</i> provide Call Hold, Transfer, Park, Forward, and 
    Pickup capabilities. These functions only work if the telephone line supports the advanced 
    call features. </li>
  <li><i>Miscellaneous advanced features functions</i> provide added features specific to TAPI 
    service requests, such as monitoring lines and setting call parameters. </li>
</ul>

<p>Table 23.4 shows all the Supplemental Telephony API functions for the advanced line 
device features.<br>
</p>

<p align="center"><b>Table 23.4. The Supplemental Telephony API set for line devices.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Function Group</i></td>
    <td WIDTH="197"><i>API Call</i> </td>
    <td WIDTH="197"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="197">Digit and tone handling</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineMonitorDigits</font></tt> </td>
    <td WIDTH="197">Enables or disables digit detection notification on a specified call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineGatherDigits</font></tt> </td>
    <td WIDTH="197">Performs the buffered gathering of digits on a call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineMonitorTones</font></tt> </td>
    <td WIDTH="197">Specifies which tones to detect on a specified call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineGenerateDigits</font></tt> </td>
    <td WIDTH="197">Generates inband digits on a call.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineGenerateTone</font></tt> </td>
    <td WIDTH="197">Generates a given set of tones inband on a call. </td>
  </tr>
  <tr>
    <td WIDTH="197">Advanced call handling</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineAccept</font></tt> </td>
    <td WIDTH="197">Accepts an offered call and starts alerting both caller (ring-back) and 
    called party (ring). </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineRedirect</font></tt> </td>
    <td WIDTH="197">Redirects an offering call to another address. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSecureCall</font></tt> </td>
    <td WIDTH="197">Secures an existing call from interference by other events such as 
    call-waiting beeps on data connections. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineCompleteCall</font></tt> </td>
    <td WIDTH="197">Places a call completion request.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineUncompleteCall</font></tt> </td>
    <td WIDTH="197">Cancels a call completion request.</td>
  </tr>
  <tr>
    <td WIDTH="197">Call hold</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineHold</font></tt> </td>
    <td WIDTH="197">Places the specified call on hard hold.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineUnhold</font></tt> </td>
    <td WIDTH="197">Retrieves a held call.</td>
  </tr>
  <tr>
    <td WIDTH="197">Call transfer</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineSetupTransfer</font></tt> </td>
    <td WIDTH="197">Prepares a specified call for transfer to another address. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineCompleteTransfer</font></tt> </td>
    <td WIDTH="197">Transfers a call that was set up for transfer to another call, or enters a 
    three-way conference. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineBlindTransfer</font></tt> </td>
    <td WIDTH="197">Transfers a call to another party.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSwapHold</font></tt> </td>
    <td WIDTH="197">Swaps the active call with the call currently on consultation hold. </td>
  </tr>
  <tr>
    <td WIDTH="197">Call conference</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineSetupConference</font></tt> </td>
    <td WIDTH="197">Prepares a given call for the addition of another party. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LinePrepareAddToConference</font></tt> </td>
    <td WIDTH="197">Prepares to add a party to an existing conference call by allocating a 
    consultation call that can later be added to the conference call that is placed on 
    conference hold. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineAddToConference</font></tt> </td>
    <td WIDTH="197">Adds a consultation call to an existing conference call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineRemoveFromConference</font></tt> </td>
    <td WIDTH="197">Removes a party from a conference call.</td>
  </tr>
  <tr>
    <td WIDTH="197">Call park</td>
    <td WIDTH="197"><tt><font FACE="Courier">linePark</font></tt> </td>
    <td WIDTH="197">Parks a given call at another address.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineUnpark</font></tt> </td>
    <td WIDTH="197">Retrieves a parked call.</td>
  </tr>
  <tr>
    <td WIDTH="197">Call forwarding</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineForward</font></tt> </td>
    <td WIDTH="197">Sets or cancels call forwarding requests.</td>
  </tr>
  <tr>
    <td WIDTH="197">Call pickup</td>
    <td WIDTH="197"><tt><font FACE="Courier">linePickup</font></tt> </td>
    <td WIDTH="197">Picks up a call that is alerting at another number. Picks up a call 
    alerting at another destination address and returns a call handle for the picked up call (<tt><font
    FACE="Courier">linePickup</font></tt> can also be used for call waiting). </td>
  </tr>
  <tr>
    <td WIDTH="197">Miscellaneous advanced features</td>
    <td WIDTH="197"><tt><font FACE="Courier">lineSendUserUserInfo</font></tt> </td>
    <td WIDTH="197">Sends user-to-user information to the remote party on the specified call 
    (ISDN only). </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSetTerminal</font></tt> </td>
    <td WIDTH="197">Specifies the terminal device to which the specified line, address events, 
    or call media stream events are routed. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSetCallParams</font></tt> </td>
    <td WIDTH="197">Requests a change in the call parameters of an existing call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineMonitorMedia</font></tt> </td>