ch23.htm

MAPI__SAPI__TAPI

    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetlineDevStatus</font></tt> </td>
    <td WIDTH="249">Returns the current status of the specified open line device. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetDevConfig</font></tt> </td>
    <td WIDTH="249">Sets the configuration of the specified media stream device. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetStatusMessages</font></tt> </td>
    <td WIDTH="249">Specifies the status changes for which the application wants to be 
    notified. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetStatusMessages</font></tt> </td>
    <td WIDTH="249">Returns the application's current line and address status message 
    settings. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetID</font></tt> </td>
    <td WIDTH="249">Retrieves a device ID associated with the specified open line, address, or 
    call. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetNumRings</font></tt> </td>
    <td WIDTH="249">Indicates the number of rings after which inbound calls are to be 
    answered. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetNumRings</font></tt> </td>
    <td WIDTH="249">This function returns the minimum number of rings requested with <tt><font
    FACE="Courier">lineSetNumRings</font></tt>. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetIcon</font></tt> </td>
    <td WIDTH="249">Allows an application to retrieve an icon for display to the user. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineConfigDialog</font></tt> </td>
    <td WIDTH="249">Causes the provider of the specified line device to display a dialog that 
    allows the user to configure parameters related to the line device. </td>
  </tr>
  <tr>
    <td WIDTH="139">Inbound and outbound calls</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineMakeCall</font></tt> </td>
    <td WIDTH="249">Makes an outbound call and returns a call handle for it. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineDial</font></tt> </td>
    <td WIDTH="249">Dials (parts of one or more) dialable addresses. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineAnswer</font></tt> </td>
    <td WIDTH="249">Answers an inbound call.</td>
  </tr>
  <tr>
    <td WIDTH="139">Addresses</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetAddressCaps</font></tt> </td>
    <td WIDTH="249">Returns the telephony capabilities of an address. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetAddressStatus</font></tt> </td>
    <td WIDTH="249">Returns the current status of a specified address. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetAddressID</font></tt> </td>
    <td WIDTH="249">Retrieves the address ID of an address specified using an alternate 
    format. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineTranslateAddress</font></tt> </td>
    <td WIDTH="249">Translates between an address in canonical format and an address in 
    dialable format. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetCurrentLocation</font></tt> </td>
    <td WIDTH="249">Sets the location used as the context for address translation. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetTollList</font></tt> </td>
    <td WIDTH="249">Manipulates the toll list.</td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetTranslateCaps</font></tt> </td>
    <td WIDTH="249">Returns address translation capabilities.</td>
  </tr>
  <tr>
    <td WIDTH="139">Miscellaneous features</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetCallInfo</font></tt> </td>
    <td WIDTH="249">Returns mostly constant information about a call. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetCallStatus</font></tt> </td>
    <td WIDTH="249">Returns complete call status information for the specified call. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetAppSpecific</font></tt> </td>
    <td WIDTH="249">Sets the application-specific field of a call's information structure. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">LineRegisterRequest</font></tt> <font
    FACE="ZapfDingbats"><font FACE="ZAPFDINGBATS">&Acirc;</font><tt><font FACE="Courier">Recipient</font></tt></font> 
    </td>
    <td WIDTH="249">Registers or de-registers the application as a request recipient for the 
    specified request mode. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetRequest</font></tt> </td>
    <td WIDTH="249">Gets the next request from the Telephony DLL. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineSetCallPrivilege</font></tt> </td>
    <td WIDTH="249">Sets the application's privilege to the privilege specified. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineHandoff</font></tt> </td>
    <td WIDTH="249">Hands off call ownership and/or changes an application's privileges to a 
    call. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetNewCalls</font></tt> </td>
    <td WIDTH="249">Returns call handles to calls on a specified line or address for which the 
    application does not yet have handles. </td>
  </tr>
  <tr>
    <td WIDTH="139">　</td>
    <td WIDTH="153"><tt><font FACE="Courier">lineGetConfRelatedCalls</font></tt> </td>
    <td WIDTH="249">Returns a list of call handles that are part of the same conference call 
    as the call specified as a parameter. </td>
  </tr>
</table>
</center></div>

<h3><a NAME="TheBasicTelephonyLineDeviceStructur">The Basic Telephony Line Device 
Structures</a></h3>

<p>Along with the extensive API set for Basic Telephony, the TAPI model defines several 
data structures that are used to pass information between TAPI and the requesting 
application. The layout of the structures contains variable as well as fixed data. This 
allows the API set to contain information of indeterminate length without prior knowledge 
of the contents of the structure. </p>

<p>In order to handle variable-length structures, the defined data structures contain 
fields that indicate the total size needed to fill in all variable data (<tt><font
FACE="Courier">dwNeededSize</font></tt>) along with the total size used by TAPI when 
filling in the structure (<tt><font FACE="Courier">dwUsedSize</font></tt>). Listing 23.1 
shows how this looks in the <tt><font FACE="Courier">LINECALLLIST</font></tt> structure. </p>

<hr>

<blockquote>
  <b><p>Listing 23.1. Viewing the <tt><font FACE="Courier">LINECALLLIST</font></tt> 
  structure.<br>
  </b></p>
</blockquote>

<blockquote>
  <tt><font FACE="Courier"><p>typedef struct linecalllist_tag {<br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwTotalSize;<br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwNeededSize;<br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwUsedSize;<br>
  <br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwCallsNumEntries;<br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwCallsSize;<br>
  &nbsp;&nbsp;DWORD&nbsp;&nbsp;dwCallsOffset;<br>
  } LINECALLLIST, FAR *LPLINECALLLIST;</font></tt> </p>
</blockquote>

<hr>

<p>The <tt><font FACE="Courier">dwTotalSize</font></tt> field is first set by the calling 
application to tell TAPI how much memory has been allocated for the structure. If TAPI 
cannot fill in all values without running out of allocated space, an error is returned and 
it is the job of the requesting application to re-allocate space and make the call again. </p>

<p>Along with the total size and total needed fields, each variable-length structure has a 
fixed portion and a variable portion. The fixed portion contains values that indicate the 
size of the variable-length field and the offset (from the start of the structure) at 
which the field is located. Note the fields <tt><font FACE="Courier">dwCallsSize</font></tt> 
and <tt><font FACE="Courier">dwCallsOffset</font></tt> in the <tt><font FACE="Courier">LINECALLLIST</font></tt> 
structure shown in Listing 23.1. </p>

<p>Table 23.2 shows the list of data structures used by the Basic Telephony API set along 
with short descriptions of their use. <br>
</p>

<p align="center"><b>Table 23.2. The Basic Telephony API line device structures.</b> </p>
<div align="center"><center>

<table BORDERCOLOR="#000000" BORDER="1" WIDTH="80%">
  <tr>
    <td><i>Structure</i></td>
    <td WIDTH="324"><i>Description</i> </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEADDRESSCAPS</font></tt> </td>
    <td WIDTH="324">Describes the capabilities of a specified address. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEADDRESSSTATUS</font></tt> </td>
    <td WIDTH="324">Describes the current status of an address. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECALLINFO</font></tt> </td>
    <td WIDTH="324">Contains information about a call.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECALLLIST</font></tt> </td>
    <td WIDTH="324">Describes a list of call handles.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECALLPARAMS</font></tt> </td>
    <td WIDTH="324">Describes parameters supplied when making calls using <tt><font
    FACE="Courier">lineMakeCall</font></tt>. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECALLSTATUS</font></tt> </td>
    <td WIDTH="324">Describes the current status of a call.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECARDENTRY</font></tt> </td>
    <td WIDTH="324">Describes a calling card.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECOUNTRYENTRY</font></tt> </td>
    <td WIDTH="324">Provides the information for a single country entry. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINECOUNTRYLIST</font></tt> </td>
    <td WIDTH="324">Describes a list of countries.</td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEDEVCAPS</font></tt> </td>
    <td WIDTH="324">Describes the capabilities of a line device. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEDEVSTATUS</font></tt> </td>
    <td WIDTH="324">Describes the current status of a line device. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEDIALPARAMS</font></tt> </td>
    <td WIDTH="324">Specifies a collection of dialing-related fields. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEEXTENSIONID</font></tt> </td>
    <td WIDTH="324">Describes an extension ID. Extension IDs are used to identify service 
    provider-specific extensions for line devices. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEFORWARD</font></tt> </td>
    <td WIDTH="324">Describes an entry of the forwarding instructions. </td>
  </tr>
  <tr>
    <td WIDTH="266"><tt><font FACE="Courier">LINEFORWARDLIST</font></tt> </td>
    <td WIDTH="324">Describes a list of forwarding instructions. </td>