ch23.htm

MAPI__SAPI__TAPI

    <td WIDTH="197">Enables or disables media mode notification on a specified call. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSetMediaControl</font></tt> </td>
    <td WIDTH="197">Sets up a call's media stream for media control. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">LineSetMediaMode</font></tt> </td>
    <td WIDTH="197">Sets the media mode(s) of the specified call in its <tt><font
    FACE="Courier">LINECALLINFO</font></tt> structure. </td>
  </tr>
</table>
</center></div>

<h3><a NAME="SupplementalTelephonyAPIforPhoneDev">Supplemental Telephony API for Phone 
Devices</a></h3>

<p>The Supplemental Telephony API also provides function calls for the handling of phone 
devices. To TAPI, any device that can place or accept calls can be a phone device. The 
phone device API set allows programmers to invent their own phone devices in code. In 
effect, you can create a virtual handset using the TAPI phone device. This allows properly 
equipped workstations to act as single- or multiple-line phones in an office environment. 
If your pc has appropriate audio input and output hardware (speakers, sound card, 
microphone, and so on) and is connected to the telephone service, you can create a 
&quot;handset&quot; using the phone device API set. </p>

<p>The Supplemental Telephony API set for phone devices can be divided into the following 
function groups: 

<ul>
  <li><i>Basic phone-handling functions</i> provide basic initialization and shutdown, opening 
    and closing a phone device, and ringing the open device. </li>
  <li><i>Phone settings and status functions</i> allow programmers to read and write various 
    settings of the phone device such as volume, gain, hookswitch behavior, and so on. </li>
  <li><i>Physical display, data, button, and lamp functions</i> can be used to read and write 
    display information to desktop units. Since TAPI can be used to support more than just pc 
    workstations, these functions allow a central TAPI program to monitor and update LCD 
    displays, to flash lamps, to change buttons labels, and to store and retrieve data from 
    desktop terminals. </li>
</ul>

<p>Table 23.5 shows all the Supplemental Telephony phone device API calls along with short 
descriptions of their use.<br>
</p>

<p align="center"><b>Table 23.5. The Supplemental Telephony API for phone 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">Basic phone handling</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneInitialize</font></tt> </td>
    <td WIDTH="197">Initializes the Telephony API phone device for use by the invoking 
    application. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneShutdown</font></tt> </td>
    <td WIDTH="197">Shuts down the applica-tion's use of the phone Telephony API. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneNegotiateAPIVersion</font></tt> </td>
    <td WIDTH="197">Allows an application to negotiate an API version to use. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneOpen</font></tt> </td>
    <td WIDTH="197">Opens the specified phone device, giving the application either owner or 
    monitor privileges. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneClose</font></tt> </td>
    <td WIDTH="197">Closes a specified open phone device.</td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetRing</font></tt> </td>
    <td WIDTH="197">Rings an open phone device according to a given ring mode. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetRing</font></tt> </td>
    <td WIDTH="197">Returns the current ring mode of an opened phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">Phone settings and status</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneGetDevCaps</font></tt> </td>
    <td WIDTH="197">Returns the capabilities of a given phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetID</font></tt> </td>
    <td WIDTH="197">Returns a device ID for the given device class associated with the 
    specified phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetIcon</font></tt> </td>
    <td WIDTH="197">Allows an application to retrieve an icon for display to the user. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneConfigDialog</font></tt> </td>
    <td WIDTH="197">Causes the provider of the specified phone device to display a dialog that 
    allows the user to configure parameters related to the phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetStatusMessages</font></tt> </td>
    <td WIDTH="197">Specifies the status changes for which the application wants to be 
    notified. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetStatusMessages</font></tt> </td>
    <td WIDTH="197">Returns the status changes for which the application wants to be notified. 
    </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetStatus</font></tt> </td>
    <td WIDTH="197">Returns the complete status of an open phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetHookSwitch</font></tt> </td>
    <td WIDTH="197">Sets the hookswitch mode of one or more of the hook-switch devices of an 
    open phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetHookSwitch</font></tt> </td>
    <td WIDTH="197">Queries the hookswitch mode of a hookswitch device of an open phone 
    device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetVolume</font></tt> </td>
    <td WIDTH="197">Sets the volume of a hook-switch device's speaker of an open phone device. 
    </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetVolume</font></tt> </td>
    <td WIDTH="197">Returns the volume setting of a hookswitch device's speaker of an open 
    phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetGain</font></tt> </td>
    <td WIDTH="197">Sets the gain of a hookswitch device's mic of an open phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetGain</font></tt> </td>
    <td WIDTH="197">Returns the gain setting of a hookswitch device's mic of an open phone 
    device. </td>
  </tr>
  <tr>
    <td WIDTH="197">Physical display, data, buttons, and lamps</td>
    <td WIDTH="197"><tt><font FACE="Courier">phoneSetDisplay</font></tt> </td>
    <td WIDTH="197">Writes information to the display of an open phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetDisplay</font></tt> </td>
    <td WIDTH="197">Returns the current contents of a phone's display. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetButtonInfo</font></tt> </td>
    <td WIDTH="197">Sets the information associated with a button on a phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetButtonInfo</font></tt> </td>
    <td WIDTH="197">Returns information associated with a button on a phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetLamp</font></tt> </td>
    <td WIDTH="197">Lights a lamp on a specified open phone device in a given lamp-lighting 
    mode. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetLamp</font></tt> </td>
    <td WIDTH="197">Returns the current lamp mode of the specified lamp. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneSetData</font></tt> </td>
    <td WIDTH="197">Downloads a buffer of data to a given data area in the phone device. </td>
  </tr>
  <tr>
    <td WIDTH="197">　</td>
    <td WIDTH="197"><tt><font FACE="Courier">PhoneGetData</font></tt> </td>
    <td WIDTH="197">Uploads the contents of a given data area in the phone device to a buffer. 
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="TheSupplementalTelephonyPhoneDevice">The Supplemental Telephony Phone Device 
Structures</a></h3>

<p>Just as the line device API set has a series of data structures, the phone device set 
also has related data structures. These structures are used to pass information between 
the desktop program and the TAPI service provider. </p>

<p>The phone device structures most often used are the <tt><font FACE="Courier">PHONECAPS</font></tt> 
and <tt><font FACE="Courier">PHONESTATUS</font></tt> structures. Table 23.6 shows all the 
phone device structures along with brief descriptions of their use.<br>
</p>

<p align="center"><b>Table 23.6. The Supplemental Telephony phone device structures.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Structure</i></td>
    <td WIDTH="414"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="176"><tt><font FACE="Courier">PHONEBUTTONINFO</font></tt> </td>
    <td WIDTH="414">Contains information about a button on a phone device. </td>
  </tr>
  <tr>
    <td WIDTH="176"><tt><font FACE="Courier">PHONECAPS</font></tt> </td>
    <td WIDTH="414">Describes the capabilities of a phone device. </td>
  </tr>
  <tr>
    <td WIDTH="176"><tt><font FACE="Courier">PHONEEXTENSIONID</font></tt> </td>
    <td WIDTH="414">Describes an extension ID. Extension IDs are used to identify service 
    provider-specific extensions for phone device classes. Used mostly for Extended Telephony. 
    </td>
  </tr>
  <tr>
    <td WIDTH="176"><tt><font FACE="Courier">PHONESTATUS</font></tt> </td>
    <td WIDTH="414">Describes the current status of a phone device. </td>
  </tr>
  <tr>
    <td WIDTH="176"><tt><font FACE="Courier">VARSTRING</font></tt> </td>
    <td WIDTH="414">Used for returning variably sized strings. It is used both by the line 
    device class and the phone device class. </td>
  </tr>
</table>
</center></div>

<h3><a NAME="TheupplementalTelephonyPhoneDeviceM">The Supplemental Telephony Phone Device 
Messages</a></h3>

<p>The Supplemental Telephony phone device also uses a callback function to register a 
function address to receive Windows messages. This callback address is established during 
the <tt><font FACE="Courier">phoneInitialize</font></tt> API call. </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><b>Note</b></td>
  </tr>
  <tr>
    <td><blockquote>
      <p>The fact that TAPI uses callbacks for messages means that any high-level languages such 
      as Visual Basic must use either a DLL or OCX or establish the callback link or use some 
      other tool that can capture windows messages. A sample OCX is included on the CD-ROM that 
      ships with this book. This OCX is