ch23.htm

MAPI__SAPI__TAPI

  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEGENERATETONE</font></tt> </td>
    <td WIDTH="324">Contains information about a tone to be generated. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINELOCATIONENTRY</font></tt> </td>
    <td WIDTH="324">Describes a location used to provide an address translation context. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEMEDIACONTROLCALLSTATE</font></tt> </td>
    <td WIDTH="324">Describes a media action to be executed when detecting transitions into 
    one or more call states. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEMEDIACONTROLDIGIT</font></tt> </td>
    <td WIDTH="324">Describes a media action to be executed when detecting a digit. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEMEDIACONTROLMEDIA</font></tt> </td>
    <td WIDTH="324">Describes a media action to be executed when detecting a media-mode 
    change. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEMEDIACONTROLTONE</font></tt> </td>
    <td WIDTH="324">Describes a media action to be executed when a tone has been detected. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEMONITORTONE</font></tt> </td>
    <td WIDTH="324">Describes a tone to be monitored.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEPROVIDERENTRY</font></tt> </td>
    <td WIDTH="324">Provides the information for a single-service provider entry. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEPROVIDERLIST</font></tt> </td>
    <td WIDTH="324">Describes a list of service providers.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEREQMAKECALL</font></tt> </td>
    <td WIDTH="324">Describes a <tt><font FACE="Courier">tapiRequestMakeCall</font></tt> 
    request. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINETERMCAPS</font></tt> </td>
    <td WIDTH="324">Describes the capabilities of a line's terminal device. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINETRANSLATECAPS</font></tt> </td>
    <td WIDTH="324">Describes the address translation capabilities. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINETRANSLATEOUTPUT</font></tt> </td>
    <td WIDTH="324">Describes the result of an address translation. </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 WIDTH="581"><blockquote>
      <p>A detailed listing of all TAPI structures is included in the Microsoft Visual C++ Win32 
      documentation. You can also find complete TAPI documentation on the MSDN Professional 
      Level CD-ROMs.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<h3><a NAME="BasicTelephonyLineDeviceMessages">Basic Telephony Line Device Messages</a></h3>

<p>The Telephony API uses Windows messages to communicate with the requesting application. 
When the requesting application first performs a <tt><font FACE="Courier">LineInitialize</font></tt> 
function, a callback function address must be supplied. All messages are then sent to this 
callback function. </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 language 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 used throughout the book to show how you can link Visual 
      Basic and other VBA-compliant languages to TAPI services.</p>
    </blockquote>
    </td>
  </tr>
</table>
</center></div>

<p>Each message returns the same set of parameters. The first is the relevant handle. 
Usually this is the call handle, but it may also be a line handle. The second parameter is 
the callback instance value. This value will always be the instance handle of the current 
running application. The next three values vary depending on the message. One or more of 
these return values will contain non-zero data. Table 23.3 contains a list of the Basic 
Telephony messages, their parameters, and short descriptions.<br>
</p>

<p align="center"><b>Table 23.3. Basic Telephony line device messages.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Message</i></td>
    <td WIDTH="212"><i>Parameters</i> </td>
    <td WIDTH="193"><i>Description</i></td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_ADDRESSSTATE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice =</font></tt> <tt><font FACE="Courier">hLine</font></tt>; 
    <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">Callback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = idAddress</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = AddressState</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 =</font></tt> <tt><font FACE="Courier">(DWORD) 0</font></tt>; 
    </td>
    <td WIDTH="193">Sent when the status of an address changes on a line that is currently 
    open by the application. The application can invoke <tt><font FACE="Courier">lineGetAddressStatus</font></tt>to 
    determine the current status of the address. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_CALLINFO</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice =</font></tt> <tt><font FACE="Courier">hCall</font></tt>; 
    <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = CallInfoState</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = (DWORD) 0</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = (DWORD) 0</font></tt>; </td>
    <td WIDTH="193">Sent when the call information about the specified call has changed. The 
    application can invoke <tt><font FACE="Courier">lineGetCallInfo</font></tt> to determine 
    the current call information. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_CALLSTATE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = CallState</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 =</font></tt> <br>
    <tt><font FACE="Courier">CallStateDetail</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = <br>
    CallPrivilege</font></tt>; </td>
    <td WIDTH="193">Sent when the status of the specified call has changed. Several such 
    messages will typically be received during the lifetime of a call. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_CLOSE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hLine</font></tt>; <br>
    dwCallbackInstance = <br>
    hCallback;<br>
    <tt><font FACE="Courier">dwParam1 = (DWORD) 0</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = (DWORD) 0</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = (DWORD) 0</font></tt>; </td>
    <td WIDTH="193">Sent when the specified line device has been forcibly closed. The line 
    device handle or any call handles for calls on the line are no longer valid once this 
    message has been sent. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_CREATE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = 0</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance = 0</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = idDevice</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 to inform the application of the creation of a new line device. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_DEVSPECIFIC</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hLineOrCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceSpecific1</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 =<br>
    DeviceSpecific2</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 =<br>
    DeviceSpecific3</font></tt>; </td>
    <td WIDTH="193">Sent to notify the application about device-specific events occurring on a 
    line, address, or call. The meaning of the message and the interpretation of the 
    parameters is device specific. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_DEVSPECIFICFEATURE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hLineOrCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceSpecific1</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceSpecific2</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceSpecific3</font></tt>; </td>
    <td WIDTH="193">Sent to notify the application about device-specific events occurring on a 
    line, address, or call. The meaning of the message and the interpretation of the 
    parameters is device specific. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_GATHERDIGITS</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 =</font></tt> <br>
    <tt><font FACE="Courier">GatherTermination</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 the current buffered digit-gathering request has terminated or 
    is canceled. The digit buffer may be examined after this message has been received by the 
    application. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_GENERATE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 =</font></tt> <br>
    <tt><font FACE="Courier">GenerateTermination</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 to notify the application that the current digit or tone generation 
    has terminated. Note that only one such generation request can be in progress on a given 
    call at any time. This message is also sent when digit or tone generation is canceled. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE_LINEDEVSTATE</font></tt> </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hLine</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = DeviceState</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceStateDetail1</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 =</font></tt> <br>
    <tt><font FACE="Courier">DeviceStateDetail2</font></tt> </td>
    <td WIDTH="193">Sent when the state of a line device has changed. The application can 
    invoke <tt><font FACE="Courier">lineGetLineDevStatus</font></tt> to determine the new 
    status of the line. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE</font></tt>_<tt><font FACE="Courier">MONITORDIGITS</font></tt> 
    </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = Digit</font></tt>;<br>
    <tt><font FACE="Courier">dwParam2 = DigitMode</font></tt>;<br>
    <tt><font FACE="Courier">dwParam3 = 0</font></tt>; </td>
    <td WIDTH="193">Sent when a digit is detected. The sending of this message is controlled 
    with the <tt><font FACE="Courier">lineMonitorDigits</font></tt> function. </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE</font></tt>_<tt><font FACE="Courier">MONITORMEDIA</font></tt> 
    </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>;<br>
    <tt><font FACE="Courier">dwParam1 = MediaMode</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 change in the call's media mode is detected. The sending of 
    this message is controlled with the <tt><font FACE="Courier">lineMonitorMedia </font></tt>function. 
    </td>
  </tr>
  <tr>
    <td WIDTH="186"><tt><font FACE="Courier">LINE</font></tt>_<tt><font FACE="Courier">MONITORTONE</font></tt> 
    </td>
    <td WIDTH="212"><tt><font FACE="Courier">dwDevice = hCall</font></tt>; <br>
    <tt><font FACE="Courier">dwCallbackInstance =</font></tt> <br>
    <tt><font FACE="Courier">hCallback</font></tt>; <br>